@react-text-game/core 0.1.0

package/dist/game.js

@@ -0,0 +1,489 @@
+import { proxy, subscribe } from "valtio";
+import { STORAGE_SYSTEM_PATH, SYSTEM_PASSAGE_NAMES } from "./constants";
+import { logger } from "./logger";
+import { _getOptions, newOptions } from "./options";
+import { createOrUpdateSystemSave } from "./saves";
+import { Storage } from "./storage";
+const objectRegistry = new Map();
+const passagesRegistry = new Map();
+const jsonPath = `${STORAGE_SYSTEM_PATH}.game`;
+/**
+ * Central orchestrator for the text game engine.
+ *
+ * The `Game` class manages all core game functionality including:
+ * - Entity registration and proxying with Valtio for reactive state
+ * - Passage registration and navigation
+ * - State serialization and persistence
+ * - Auto-save to session storage with debouncing
+ *
+ * All entities and passages are automatically registered through their constructors,
+ * and the Game provides static methods for navigation and state management.
+ *
+ * @example
+ * ```typescript
+ * // Create entities and passages (auto-registered)
+ * const player = new Player();
+ * const intro = newStory('intro', () => [...]);
+ *
+ * // Navigate
+ * Game.jumpTo('intro');
+ *
+ * // Save/Load
+ * const state = Game.getState();
+ * Game.setState(state);
+ *
+ * // Auto-save
+ * Game.enableAutoSave();
+ * Game.loadFromSessionStorage();
+ * ```
+ */
+export class Game {
+    static state = proxy({
+        currentPassageId: null,
+    });
+    static initialized = false;
+    static autoSaveEnabled = false;
+    static saveTimer = null;
+    static unsubscribeFunctions = [];
+    static AUTO_SAVE_KEY = "gameAutoSave";
+    static SAVE_DEBOUNCE_MS = 500;
+    /**
+     * Ensures the game has been initialized before allowing method calls.
+     *
+     * @private
+     * @throws Error if Game.init() has not been called
+     */
+    static ensureInitialized() {
+        if (!Game.initialized) {
+            throw new Error("Game not initialized. Please call Game.init() before using the game engine.");
+        }
+    }
+    /**
+     * Registers and proxies the provided game objects for further use by adding them to the object registry.
+     *
+     * @param {...BaseGameObject[]} objects - The array of BaseGameObject instances to be registered.
+     * @return {void} This method does not return a value.
+     */
+    static registerEntity(...objects) {
+        objects.forEach((object) => {
+            if (objectRegistry.has(object.id)) {
+                throw new Error(`Object "${object.id}" is already registered.`);
+            }
+            const proxiedObject = proxy(object);
+            objectRegistry.set(object.id, proxiedObject);
+            logger.log(`Registered entity: ${object.id}`);
+        });
+    }
+    /**
+     * Registers one or more passages into the passage registry. Each passage must have a unique identifier.
+     * Throws an error if a passage with the same id is already registered.
+     *
+     * @param {...Passage} passages The passages to be registered. Each passage should be an object containing an `id` property.
+     * @return {void} Does not return a value.
+     * @throws Error if Game.init() has not been called
+     */
+    static registerPassage(...passages) {
+        const systemPassages = Object.values(SYSTEM_PASSAGE_NAMES);
+        passages.forEach((passage) => {
+            if (passagesRegistry.has(passage.id) &&
+                // letting user to re-register system passages
+                !systemPassages.includes(passage.id)) {
+                throw new Error(`Passage "${passage.id}" is already registered.`);
+            }
+            passagesRegistry.set(passage.id, passage);
+            logger.log(`Registered passage: ${passage.id}`);
+        });
+    }
+    /**
+     * Retrieves all registered passages from the passage registry.
+     *
+     * @return {IterableIterator<Passage>} An iterator containing all the Passage objects.
+     * @throws Error if Game.init() has not been called
+     */
+    static get registeredPassages() {
+        return passagesRegistry.values();
+    }
+    /**
+     * Retrieves the current passage from the passage registry based on the current passage ID in the game state.
+     * If the current passage ID is null or the passage cannot be found, returns null.
+     *
+     * @return {Passage | null} The current passage object or null if not available.
+     * @throws Error if Game.init() has not been called
+     */
+    static get currentPassage() {
+        Game.ensureInitialized();
+        if (Game.state.currentPassageId === null) {
+            return null;
+        }
+        return passagesRegistry.get(Game.state.currentPassageId) || null;
+    }
+    /**
+     * Retrieves a passage by its unique identifier.
+     *
+     * @param {string} passageId - The unique ID of the passage to retrieve.
+     * @return {Passage|null} The passage object if found, or null if no passage exists with the given ID.
+     * @throws Error if Game.init() has not been called
+     */
+    static getPassageById(passageId) {
+        Game.ensureInitialized();
+        return passagesRegistry.get(passageId) || null;
+    }
+    /**
+     * Retrieves all the passages from the passages registry.
+     *
+     * @return {Array<Passage>} An array containing all the Passage objects.
+     * @throws Error if Game.init() has not been called
+     */
+    static getAllPassages() {
+        Game.ensureInitialized();
+        return Array.from(passagesRegistry.values());
+    }
+    /**
+     * Navigates the game to a specified passage.
+     *
+     * @param {Passage|string} passage - The passage object or identifier of the passage to jump to.
+     * @return {void} Does not return any value.
+     * @throws {Error} Throws an error if the specified passage is not found or if Game.init() has not been called
+     */
+    static jumpTo(passage) {
+        Game.ensureInitialized();
+        const passageId = typeof passage === "string" ? passage : passage.id;
+        const retrievedPassage = passagesRegistry.get(passageId) || null;
+        if (!retrievedPassage) {
+            throw new Error(`Passage "${passageId}" not found.`);
+        }
+        Game.state.currentPassageId = retrievedPassage
+            ? retrievedPassage.id
+            : null;
+        logger.log(`Jumped to passage: ${passageId}`);
+    }
+    /**
+     * Sets the current passage in the game state.
+     *
+     * @param {Passage|string} passage - The passage to be set as current. Can be either a Passage object or a string representing the passage ID.
+     * @return {void} This method does not return a value.
+     * @throws Error if Game.init() has not been called
+     */
+    static setCurrent(passage) {
+        Game.ensureInitialized();
+        Game.state.currentPassageId =
+            typeof passage === "string" ? passage : passage.id;
+        logger.log(`Set current passage: ${Game.state.currentPassageId}`);
+    }
+    /**
+     * Retrieves the proxied object from the object registry based on its ID.
+     * If the object is not found in the registry, the original object is returned.
+     *
+     * @internal - Used by hooks for reactive state management
+     * @param object - The original object to find in the registry
+     * @returns The proxied object from the registry if present, otherwise the original object
+     */
+    static _getProxiedObject(object) {
+        return objectRegistry.get(object.id) || object;
+    }
+    /**
+     * Retrieves all proxied objects from the object registry.
+     *
+     * @internal - Used for batch operations during save/load
+     * @returns An array of BaseGameObject instances stored in the object registry
+     */
+    static _getAllProxiedObjects() {
+        return Array.from(objectRegistry.values());
+    }
+    /**
+     * Provides access to the internal game state for reactive hooks.
+     *
+     * @returns The game's internal reactive state
+     * @throws Error if Game.init() has not been called
+     */
+    static get selfState() {
+        Game.ensureInitialized();
+        return Game.state;
+    }
+    /**
+     * Saves the current game state, including critical passage information, into storage.
+     *
+     * This method saves the Game's internal state (current passage) to the Storage system.
+     * It does NOT save entity states - use entity.save() or Game.getState() for that.
+     *
+     * @private - Called internally by Game.getState()
+     */
+    static save() {
+        const internalState = {
+            currentPassageId: Game.state.currentPassageId,
+        };
+        Storage.setValue(jsonPath, internalState, true);
+        logger.log(`Game state saved: ${JSON.stringify(internalState)}`);
+    }
+    /**
+     * Loads the saved game state from storage and sets the current passage ID in the game state.
+     *
+     * @private - Called internally by Game.setState()
+     * @throws Error if no saved state is found
+     */
+    static load() {
+        const savedState = Storage.getValue(jsonPath);
+        if (!savedState.length) {
+            throw new Error("No saved state found.");
+        }
+        const { currentPassageId } = savedState[0];
+        Game.state.currentPassageId = currentPassageId || null;
+        logger.log(`Game state loaded: ${JSON.stringify(savedState[0])}`);
+    }
+    /**
+     * Captures the complete game state including all entities and passages.
+     *
+     * This method:
+     * 1. Saves the Game's internal state (current passage)
+     * 2. Saves all registered entity states
+     * 3. Returns the complete state object
+     *
+     * @returns The complete serializable game state
+     * @throws Error if Game.init() has not been called
+     *
+     * @example
+     * ```typescript
+     * const savedState = Game.getState();
+     * localStorage.setItem('save1', JSON.stringify(savedState));
+     * ```
+     */
+    static getState(_fromI = false) {
+        if (!_fromI) {
+            Game.ensureInitialized();
+        }
+        Game.save();
+        for (const [, object] of objectRegistry) {
+            object.save();
+        }
+        return Storage.getState();
+    }
+    /**
+     * Restores the complete game state including all entities and passages.
+     *
+     * This method:
+     * 1. Sets the Storage state
+     * 2. Loads the Game's internal state (current passage)
+     * 3. Loads all registered entity states
+     *
+     * @param state - The game state to restore
+     * @throws Error if Game.init() has not been called
+     *
+     * @example
+     * ```typescript
+     * const savedState = JSON.parse(localStorage.getItem('save1'));
+     * Game.setState(savedState);
+     * ```
+     */
+    static setState(state) {
+        Game.ensureInitialized();
+        Storage.setState(state);
+        Game.load();
+        for (const [, object] of objectRegistry) {
+            object.load();
+        }
+    }
+    /**
+     * Saves the current game state to session storage with debouncing.
+     *
+     * Uses a 500ms debounce to prevent excessive writes during rapid state changes.
+     *
+     * @private - Called automatically when auto-save is enabled
+     */
+    static saveToSessionStorage() {
+        if (Game.saveTimer) {
+            clearTimeout(Game.saveTimer);
+        }
+        Game.saveTimer = setTimeout(() => {
+            const state = Game.getState();
+            sessionStorage.setItem(Game.AUTO_SAVE_KEY, JSON.stringify(state));
+        }, Game.SAVE_DEBOUNCE_MS);
+    }
+    /**
+     * Enables auto-save functionality.
+     *
+     * Subscribes to all game state changes (Game state and all entity states)
+     * and automatically saves to session storage with 500ms debouncing.
+     *
+     * @throws Error if Game.init() has not been called
+     *
+     * @example
+     * ```typescript
+     * Game.enableAutoSave();
+     * // Now any state change will auto-save after 500ms
+     * player.health = 50; // Will trigger auto-save
+     * ```
+     */
+    static enableAutoSave() {
+        Game.ensureInitialized();
+        if (Game.autoSaveEnabled) {
+            logger.warn("Auto-save is already enabled");
+            return;
+        }
+        Game.autoSaveEnabled = true;
+        // Subscribe to Game state changes
+        const unsubGame = subscribe(Game.state, () => {
+            Game.saveToSessionStorage();
+        });
+        Game.unsubscribeFunctions.push(unsubGame);
+        // Subscribe to all registered entities
+        for (const [, object] of objectRegistry) {
+            const unsubEntity = subscribe(object, () => {
+                Game.saveToSessionStorage();
+            });
+            Game.unsubscribeFunctions.push(unsubEntity);
+        }
+        logger.log("Auto-save enabled");
+    }
+    /**
+     * Disables auto-save functionality and clears all subscriptions.
+     *
+     * Cleans up all Valtio subscriptions and cancels any pending debounced saves.
+     *
+     * @throws Error if Game.init() has not been called
+     */
+    static disableAutoSave() {
+        Game.ensureInitialized();
+        if (!Game.autoSaveEnabled) {
+            logger.warn("Auto-save is already disabled");
+            return;
+        }
+        // Clear debounce timer
+        if (Game.saveTimer) {
+            clearTimeout(Game.saveTimer);
+            Game.saveTimer = null;
+        }
+        // Unsubscribe all listeners
+        Game.unsubscribeFunctions.forEach((unsubscribe) => unsubscribe());
+        Game.unsubscribeFunctions = [];
+        Game.autoSaveEnabled = false;
+        logger.log("Auto-save disabled");
+    }
+    /**
+     * Loads game state from session storage if available.
+     *
+     * @returns True if state was loaded successfully, false otherwise
+     * @throws Error if Game.init() has not been called
+     *
+     * @example
+     * ```typescript
+     * if (Game.loadFromSessionStorage()) {
+     *   console.log('Game loaded from auto-save');
+     * } else {
+     *   Game.jumpTo('start');
+     * }
+     * ```
+     */
+    static loadFromSessionStorage() {
+        Game.ensureInitialized();
+        const savedState = sessionStorage.getItem(Game.AUTO_SAVE_KEY);
+        if (!savedState) {
+            return false;
+        }
+        try {
+            const state = JSON.parse(savedState);
+            Game.setState(state);
+            logger.log("Game state loaded from session storage");
+            return true;
+        }
+        catch (error) {
+            logger.error("Failed to load state from session storage:", error);
+            return false;
+        }
+    }
+    /**
+     * Clears the auto-saved state from session storage.
+     *
+     * @throws Error if Game.init() has not been called
+     *
+     * @example
+     * ```typescript
+     * Game.clearAutoSave(); // Remove auto-save data
+     * ```
+     */
+    static clearAutoSave() {
+        Game.ensureInitialized();
+        sessionStorage.removeItem(Game.AUTO_SAVE_KEY);
+        logger.log("Auto-save data cleared from session storage");
+    }
+    /**
+     * Initializes the game engine with the provided options.
+     *
+     * This method MUST be called before any other Game methods can be used.
+     * Calling this method marks the Game as initialized and allows access to all other functionality.
+     *
+     * Optionally integrates with `@react-text-game/saves` package if installed.
+     *
+     * @param opts - Configuration options for the game
+     * @returns Promise that resolves when initialization is complete
+     *
+     * @example
+     * ```typescript
+     * await Game.init({
+     *   // your options here
+     * });
+     *
+     * // Now you can use other Game methods
+     * Game.jumpTo('start');
+     * ```
+     */
+    static async init(opts) {
+        newOptions(opts);
+        Game.initialized = true;
+        if (Game.options.isDevMode) {
+            logger.warn("Game is running in dev mode, do not use in production!");
+        }
+        Game.setCurrent(SYSTEM_PASSAGE_NAMES.START_MENU);
+        const initialState = Game.getState(true);
+        await createOrUpdateSystemSave(initialState);
+        if (!Game.options.isDevMode) {
+            Game.loadFromSessionStorage();
+            Game.enableAutoSave();
+        }
+        else {
+            logger.warn("Save to session storage is turned off due to dev mode");
+        }
+        logger.log(`Game initialized with options: ${JSON.stringify(opts)}`);
+    }
+    /**
+     * Gets the game options.
+     *
+     * @returns The current game options
+     * @throws Error if Game.init() has not been called
+     */
+    static get options() {
+        Game.ensureInitialized();
+        return _getOptions();
+    }
+    /**
+     * Updates the game options with the provided settings.
+     *
+     * @param {NewOptions} options - The new options to update the game configuration.
+     * @return {void} No return value.
+     */
+    static updateOptions(options) {
+        Game.ensureInitialized();
+        newOptions(options);
+    }
+    /**
+     * Resets the game state for testing purposes.
+     *
+     * Clears all entity and passage registries, disables auto-save, and resets initialization state.
+     * This method is intended for use in test environments only.
+     *
+     * @internal
+     */
+    static _resetForTesting() {
+        // Disable auto-save if enabled
+        if (Game.autoSaveEnabled) {
+            Game.disableAutoSave();
+        }
+        // Clear all registries
+        objectRegistry.clear();
+        passagesRegistry.clear();
+        // Reset initialization state
+        Game.initialized = false;
+        // Reset state
+        Game.state.currentPassageId = null;
+    }
+}
+//# sourceMappingURL=game.js.map

package/dist/game.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.js","sourceRoot":"","sources":["../src/game.ts"],"names":[],"mappings":"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"}

package/dist/helpers.d.ts

@@ -0,0 +1,2 @@
+export declare const callIfFunction: <T, Props>(value: T | ((props: Props | undefined) => T), props?: Props | undefined) => T;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,KAAK,EACnC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,KAAK,CAAC,CAAC,EAC5C,QAAQ,KAAK,GAAG,SAAS,KAC1B,CAIF,CAAC"}

package/dist/helpers.js

@@ -0,0 +1,6 @@
+export const callIfFunction = (value, props) => {
+    return typeof value === "function"
+        ? value(props)
+        : value;
+};
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,CAC1B,KAA4C,EAC5C,KAAyB,EACxB,EAAE;IACH,OAAO,OAAO,KAAK,KAAK,UAAU;QAC9B,CAAC,CAAE,KAAyC,CAAC,KAAK,CAAC;QACnD,CAAC,CAAC,KAAK,CAAC;AAChB,CAAC,CAAC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export * from './useCurrentPassage';
+export * from './useGameEntity';
+export * from './useGameIsStarted';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,4 @@
+export * from './useCurrentPassage';
+export * from './useGameEntity';
+export * from './useGameIsStarted';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/hooks/useCurrentPassage.d.ts

@@ -0,0 +1,10 @@
+import { Passage } from "../passages/passage";
+/**
+ * Retrieves the current passage in the game based on the reactive game state.
+ * If there is no current passage ID, the function returns null.
+ *
+ * @function
+ * @returns {Passage | null} The current passage object, or null if no passage is active.
+ */
+export declare const useCurrentPassage: () => Passage | null;
+//# sourceMappingURL=useCurrentPassage.d.ts.map

package/dist/hooks/useCurrentPassage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCurrentPassage.d.ts","sourceRoot":"","sources":["../../src/hooks/useCurrentPassage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAO,OAAO,GAAG,IAQ9C,CAAC"}

package/dist/hooks/useCurrentPassage.js

@@ -0,0 +1,17 @@
+import { useProxy } from "valtio/utils";
+import { Game } from "../game";
+/**
+ * Retrieves the current passage in the game based on the reactive game state.
+ * If there is no current passage ID, the function returns null.
+ *
+ * @function
+ * @returns {Passage | null} The current passage object, or null if no passage is active.
+ */
+export const useCurrentPassage = () => {
+    const reactiveGameState = useProxy(Game.selfState);
+    if (reactiveGameState.currentPassageId === null) {
+        return null;
+    }
+    return Game.getPassageById(reactiveGameState.currentPassageId);
+};
+//# sourceMappingURL=useCurrentPassage.js.map

package/dist/hooks/useCurrentPassage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCurrentPassage.js","sourceRoot":"","sources":["../../src/hooks/useCurrentPassage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAG7B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAmB,EAAE;IAClD,MAAM,iBAAiB,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEnD,IAAI,iBAAiB,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,IAAI,CAAC,cAAc,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;AACnE,CAAC,CAAC"}

package/dist/hooks/useGameEntity.d.ts

@@ -0,0 +1,21 @@
+import { BaseGameObject } from "../baseGameObject";
+/**
+ * Monitors changes to a given game entity by wrapping it in a Valtio proxy.
+ * This hook enables React components to automatically re-render when the entity's state changes.
+ *
+ * @param gameObject - The game entity to observe. Must extend BaseGameObject and be registered.
+ * @return The proxied game entity that triggers re-renders on state changes.
+ *
+ * @example
+ * ```tsx
+ * import { useGameEntity } from "@app/hooks";
+ * import { environment } from "@game/entities/environment";
+ *
+ * function TemperatureDisplay() {
+ *   const env = useGameEntity(environment);
+ *   return <div>Temperature: {env.variables.temperature}°C</div>;
+ * }
+ * ```
+ */
+export declare function useGameEntity<T extends BaseGameObject>(gameObject: T): T;
+//# sourceMappingURL=useGameEntity.d.ts.map

package/dist/hooks/useGameEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGameEntity.d.ts","sourceRoot":"","sources":["../../src/hooks/useGameEntity.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAqCjD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAexE"}

package/dist/hooks/useGameEntity.js

@@ -0,0 +1,70 @@
+import { useProxy } from "valtio/utils";
+import { Game } from "../game";
+const getErrorMessage = (id) => [
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "⚠️  Entity Registration Error",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+    `Entity "${id}" is not registered with the game engine.`,
+    "",
+    "Why this happened:",
+    "  React components need entities to be registered as Valtio proxies",
+    "  to detect state changes and trigger re-renders automatically.",
+    "",
+    "How to fix:",
+    "  Entities should auto-register in their constructor via:",
+    "    Game.registerEntity(this)",
+    "",
+    `  If "${id}" is a custom entity, ensure its constructor`,
+    "  calls the parent BaseGameObject constructor which handles registration:",
+    "",
+    "  Example:",
+    "    constructor(props) {",
+    "      super(props); // This registers the entity",
+    "    }",
+    "",
+    "Troubleshooting:",
+    `  1. Check if "${id}" extends BaseGameObject`,
+    "  2. Verify the constructor calls super() with an id",
+    "  3. Make sure the entity is imported before using useGameEntity",
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+].join("\n");
+/**
+ * Monitors changes to a given game entity by wrapping it in a Valtio proxy.
+ * This hook enables React components to automatically re-render when the entity's state changes.
+ *
+ * @param gameObject - The game entity to observe. Must extend BaseGameObject and be registered.
+ * @return The proxied game entity that triggers re-renders on state changes.
+ *
+ * @example
+ * ```tsx
+ * import { useGameEntity } from "@app/hooks";
+ * import { environment } from "@game/entities/environment";
+ *
+ * function TemperatureDisplay() {
+ *   const env = useGameEntity(environment);
+ *   return <div>Temperature: {env.variables.temperature}°C</div>;
+ * }
+ * ```
+ */
+export function useGameEntity(gameObject) {
+    const proxiedObject = Game._getProxiedObject(gameObject);
+    try {
+        return useProxy(proxiedObject);
+    }
+    catch (error) {
+        // if error is a TypeError, it means the object is not registered
+        if (error instanceof TypeError) {
+            const errorMessage = getErrorMessage(gameObject.id);
+            console.error(errorMessage);
+            throw new Error(errorMessage);
+        }
+        else {
+            throw error; // rethrow other types of errors
+        }
+    }
+}
+//# sourceMappingURL=useGameEntity.js.map