@directivegames/genesys.js 3.1.24

package/dist/src/storage/storageProvider.js

@@ -0,0 +1,181 @@
+/**
+ * IStorageProvider defines the minimal interface for remote or local asset retrieval.
+ *
+ * Detailed explanation:
+ * - Abstracts the mechanics of turning an asset path into a usable URL.
+ * - Allows the engine to download JSON data without coupling to a specific backend.
+ * - Implementations may choose to cache files, sign URLs or enforce expiration policies.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Provide a custom implementation when integrating with cloud storage or game specific pipelines.
+ * - Keep paths relative to projectContext prefixes for portability.
+ * - Expand this interface cautiously since every storage backend must honor new methods.
+ */
+export var AssetPathEncodeState;
+(function (AssetPathEncodeState) {
+    AssetPathEncodeState[AssetPathEncodeState["Unknown"] = 0] = "Unknown";
+    AssetPathEncodeState[AssetPathEncodeState["Encoded"] = 1] = "Encoded";
+    AssetPathEncodeState[AssetPathEncodeState["Decoded"] = 2] = "Decoded";
+})(AssetPathEncodeState || (AssetPathEncodeState = {}));
+/*
+ * AssetPath is a class that represents a path to an asset.
+ * It can be resolved to a fetch compatible URL.
+ */
+export class AssetPath {
+    constructor(initialPath) {
+        /*
+        * The initial potentially unresolved path, can be one of the following:
+        * /foo/bar.txt: path relative to the site root
+        * foo/bar.txt: path relative to the current page
+        * @engine/foo/bar.txt: path relative to the site root
+        * @project/foo/bar.txt: path relative to the project root
+        * http://localhost:3000/foo/bar.txt: absolute path
+        */
+        Object.defineProperty(this, "initialPath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /*
+        * Resolved fetch compatible path, can be used to call fetch(url) directly
+        */
+        Object.defineProperty(this, "resolvedPathEncoded", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /*
+        * Resolved decoded path, only for debugging purposes
+        */
+        Object.defineProperty(this, "resolvedPathDecoded", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.initialPath = initialPath;
+    }
+    /**
+     * Creates an AssetPath from a string
+     * @param initialPath The initial path
+     * @returns The AssetPath
+     */
+    static fromString(initialPath) {
+        return new AssetPath(initialPath);
+    }
+    /**
+     * Joins multiple paths together
+     * @param paths The paths to join
+     * @returns The joined path
+     */
+    static join(...paths) {
+        if (paths.length < 2) {
+            return this.useForwardSlashes(paths.join('/'));
+        }
+        // clean up all the path elements so they can be joined cleanly
+        paths = paths.map(elem => this.useForwardSlashes(elem));
+        const startWithSlash = paths[0].startsWith('/');
+        const endWithSlash = paths[paths.length - 1].endsWith('/');
+        paths = paths.map(elem => this.removeLeadingSlash(elem));
+        paths = paths.map(elem => this.removeTrailingSlash(elem));
+        let joinedPath = paths.join('/');
+        if (startWithSlash) {
+            joinedPath = '/' + joinedPath;
+        }
+        if (endWithSlash) {
+            joinedPath = joinedPath + '/';
+        }
+        return joinedPath;
+    }
+    static normalizeUrl(input) {
+        let decoded;
+        // Try to decode every %XX. If it's not valid percent-encoding, just keep the original.
+        try {
+            decoded = decodeURIComponent(input);
+        }
+        catch {
+            decoded = input;
+        }
+        // Now escape any characters that would break a URL (spaces, unicode, etc.)
+        const encoded = encodeURI(decoded);
+        return { decoded, encoded };
+    }
+    /**
+     * Converts backslashes to forward slashes
+     * @param path The path to convert
+     * @returns The path with backslashes converted to forward slashes
+     */
+    static useForwardSlashes(path) {
+        return path.replace(/\\/g, '/');
+    }
+    /**
+     * Removes leading slashes from a path
+     * @param path The path to remove leading slashes from
+     * @returns The path with leading slashes removed
+     */
+    static removeLeadingSlash(path) {
+        return path.replace(/^\/+/g, '');
+    }
+    /**
+     * Removes trailing slashes from a path
+     * @param path The path to remove trailing slashes from
+     * @returns The path with trailing slashes removed
+     */
+    static removeTrailingSlash(path) {
+        return path.replace(/\/+$/g, '');
+    }
+    /**
+     * Returns a string representation of the asset path
+     */
+    toString() {
+        return `AssetPath(initial="${this.initialPath}", resolved=${this.resolvedPathEncoded}, decoded=${this.resolvedPathDecoded})`;
+    }
+    /**
+     * Returns true if the path has been resolved
+     */
+    isResolved() {
+        return this.resolvedPathEncoded !== null;
+    }
+    /**
+     * Resolves the path to a fetch compatible URL, throws an error if the path is already resolved
+     * @param resolvedPath The resolved path
+     * @param encodeState The encode state of the path
+     */
+    resolvePath(resolvedPath, encodeState) {
+        if (this.resolvedPathEncoded !== null) {
+            throw new Error('Path already resolved');
+        }
+        try {
+            const { decoded, encoded } = AssetPath.normalizeUrl(resolvedPath);
+            if (encodeState === AssetPathEncodeState.Unknown) {
+                this.resolvedPathEncoded = encoded;
+                this.resolvedPathDecoded = decoded;
+            }
+            else if (encodeState === AssetPathEncodeState.Encoded) {
+                this.resolvedPathEncoded = resolvedPath;
+                this.resolvedPathDecoded = decoded;
+            }
+            else if (encodeState === AssetPathEncodeState.Decoded) {
+                this.resolvedPathEncoded = encoded;
+                this.resolvedPathDecoded = resolvedPath;
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to resolve path: ${resolvedPath}`);
+        }
+        return this;
+    }
+    /**
+     * Returns the resolved path, throws an error if the path is not resolved
+     */
+    getResolvedPath(urlEncoded = true) {
+        const resolvedPath = urlEncoded ? this.resolvedPathEncoded : this.resolvedPathDecoded;
+        if (resolvedPath === null) {
+            throw new Error(`${this} not resolved`);
+        }
+        return resolvedPath;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZVByb3ZpZGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2Uvc3RvcmFnZVByb3ZpZGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7R0FZRztBQTZCSCxNQUFNLENBQU4sSUFBWSxvQkFJWDtBQUpELFdBQVksb0JBQW9CO0lBQzlCLHFFQUFXLENBQUE7SUFDWCxxRUFBVyxDQUFBO0lBQ1gscUVBQVcsQ0FBQTtBQUNiLENBQUMsRUFKVyxvQkFBb0IsS0FBcEIsb0JBQW9CLFFBSS9CO0FBRUQ7OztHQUdHO0FBQ0gsTUFBTSxPQUFPLFNBQVM7SUFxQnBCLFlBQVksV0FBbUI7UUFwQi9COzs7Ozs7O1VBT0U7UUFDYzs7Ozs7V0FBb0I7UUFFcEM7O1VBRUU7UUFDTTs7OzttQkFBcUMsSUFBSTtXQUFDO1FBRWxEOztVQUVFO1FBQ007Ozs7bUJBQXFDLElBQUk7V0FBQztRQUdoRCxJQUFJLENBQUMsV0FBVyxHQUFHLFdBQVcsQ0FBQztJQUNqQyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNJLE1BQU0sQ0FBQyxVQUFVLENBQUMsV0FBbUI7UUFDMUMsT0FBTyxJQUFJLFNBQVMsQ0FBQyxXQUFXLENBQUMsQ0FBQztJQUNwQyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNJLE1BQU0sQ0FBQyxJQUFJLENBQUMsR0FBRyxLQUFlO1FBQ25DLElBQUksS0FBSyxDQUFDLE1BQU0sR0FBRyxDQUFDLEVBQUUsQ0FBQztZQUNyQixPQUFPLElBQUksQ0FBQyxpQkFBaUIsQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUM7UUFDakQsQ0FBQztRQUNELCtEQUErRDtRQUMvRCxLQUFLLEdBQUcsS0FBSyxDQUFDLEdBQUcsQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDLElBQUksQ0FBQyxpQkFBaUIsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO1FBQ3hELE1BQU0sY0FBYyxHQUFHLEtB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

package/dist/src/systems/ClassRegistry.d.ts

@@ -0,0 +1,98 @@
+export declare enum Prefix {
+    ENGINE = "ENGINE.",
+    GAME = "GAME.",
+    THREE = "THREE."
+}
+export type Constructor<T = any> = (new (...args: any[]) => T) & {
+    prototype: T;
+};
+/**
+ * Registry for managing and accessing class constructors across the engine.
+ * Provides functionality to register, retrieve, and instantiate classes from different sources.
+ */
+export declare class ClassRegistry {
+    private static registry;
+    private static reverseRegistry;
+    private static builtInClassesRegistered;
+    private static redirectorMap;
+    /**
+     * Registers a class as an engine component.
+     * @param constructor - The class constructor to register
+     */
+    static registerEngineClass(constructor: Constructor, className?: string): void;
+    /**
+     * Registers a class as a game component.
+     * @param constructor - The class constructor to register
+     */
+    static registerGameClass(constructor: Constructor): void;
+    static addClassesToRedirect(classes: Record<string, string>): void;
+    /**
+     * Get the registry as a readonly map.
+     * @returns The registry as a readonly map
+     */
+    static getRegistry(): ReadonlyMap<string, Constructor>;
+    /**
+     * Retrieves a class constructor by its full name.
+     * @param fullName - The full name of the class (including prefix)
+     * @returns The class constructor
+     * @throws Error if the class is not found in the registry
+     */
+    static getClass<T = any>(fullName: string): Constructor<T>;
+    /**
+     * Removes all game classes from the registry.
+     * Used when reloading game code to prevent stale references.
+     */
+    static clearGameClasses(): void;
+    /**
+     * Creates a new instance of a registered class.
+     * @param className - The full name of the class to instantiate
+     * @param isDeserializing - Whether the object is being deserialized
+     * @param args - Arguments to pass to the constructor
+     * @returns A new instance of the specified class
+     */
+    static constructObject(className: string, isDeserializing: boolean, ...args: any[]): any;
+    /**
+     * Retrieves the class name of an object or its constructor.
+     * @param object - The object to get the class name from
+     * @returns The class name of the object or its constructor
+     */
+    static getClassOrConstructorName(object: any): string;
+    /**
+     * Retrieves the full name of a class from its constructor.
+     * @param object - The object to get the class name from
+     * @returns The full name of the class or null if not found
+     */
+    static getClassName(object: any): string | null;
+    /**
+     * Retrieves the full name of a class from its constructor.
+     * @param object - The object to get the class name from
+     * @returns The full name of the class
+     * @throws Error if the class is not found in the registry
+     */
+    static getClassNameChecked(object: any): string;
+    /**
+     * Searches for a registered class by its constructor name.
+     * @param constructorName - The name of the constructor to search for
+     * @returns The full registered name (e.g., "ENGINE.MeshComponent") or null if not found
+     */
+    static getClassNameByConstructorName(constructorName: string): string | null;
+    /**
+     * Retrieves a class constructor by its constructor name.
+     * Useful for hot reload scenarios where you need to find the fresh constructor.
+     * @param constructorName - The name of the constructor to search for
+     * @returns The class constructor or null if not found
+     */
+    static getClassByConstructorName<T = any>(constructorName: string): Constructor<T> | null;
+    static registerBuiltInClasses(): void;
+    private static registerClass;
+}
+/**
+ * Decorator for registering a class as an engine component.
+ * @returns Class decorator function
+ */
+export declare function EngineClass(className: string): (constructor: Constructor) => void;
+/**
+ * Decorator for registering a class as a game component.
+ * @returns Class decorator function
+ */
+export declare function GameClass(): (constructor: Constructor) => void;