phaser-hooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CassinoDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,330 @@
+# Phaser Hooks (like "use" hooks in React)
+
+A comprehensive state management library for Phaser games with React-like hooks pattern.
+
+## Installation
+
+```bash
+npm install phaser-hooks
+# or
+pnpm add phaser-hooks
+# or
+yarn add phaser-hooks
+```
+
+## Why "with" instead of "use"?
+
+While React hooks traditionally use the "use" prefix (e.g., useState, useEffect), this library intentionally uses "with" to avoid linting issues. Many linting configurations, including ESLint's built-in hooks rules, expect functions starting with "use" to be used only within React components and in .jsx/.tsx files.
+
+Since this library is designed to work with Phaser games, which typically use plain TypeScript/JavaScript files (.ts/.js), using the "with" prefix helps avoid false positives from linters while maintaining a clear and consistent naming convention that indicates the hook-like pattern these functions follow.
+
+This approach allows you to use these state management utilities in your Phaser games without having to modify your linting configuration or suppress warnings.
+
+## Available Hooks
+
+### Core Hooks
+
+#### `withLocalState`
+
+Scene-specific state management that gets cleaned up when the scene is destroyed.
+
+```typescript
+const playerState = withLocalState<PlayerData>(scene, 'player', {
+  hp: 100,
+  level: 1,
+  exp: 0,
+});
+```
+
+#### `withGlobalState`
+
+Application-wide state that persists across all scenes.
+
+```typescript
+const settingsState = withGlobalState<GameSettings>('settings', {
+  soundVolume: 0.8,
+  musicEnabled: true,
+});
+```
+
+#### `withStateDef`
+
+Low-level state definition with custom behaviors and validation.
+
+```typescript
+const customState = withStateDef<number>(scene, 'score', {
+  initialValue: 0,
+  validator: value => value >= 0,
+  onChange: (newValue, oldValue) => console.log('Score changed!'),
+});
+```
+
+### Enhanced Hooks
+
+#### `withPersistentState`
+
+State with automatic localStorage persistence.
+
+```typescript
+const persistentSettings = withPersistentState<UserSettings>('settings', {
+  volume: 0.8,
+  difficulty: 'normal',
+});
+```
+
+#### `withComputedState`
+
+Derived state that automatically updates when source state changes.
+
+```typescript
+const healthPercentage = withComputedState(
+  scene,
+  'healthPercent',
+  playerState,
+  player => (player.hp / player.maxHp) * 100
+);
+```
+
+#### `withUndoableState`
+
+State with undo/redo functionality.
+
+```typescript
+const undoableText = withUndoableState<string>(scene, 'text', 'initial', 10);
+
+undoableText.set('first change');
+undoableText.set('second change');
+undoableText.undo(); // Back to 'first change'
+undoableText.redo(); // Forward to 'second change'
+```
+
+#### `withDebouncedState`
+
+State with debounced updates to prevent rapid successive changes.
+
+```typescript
+const debouncedSearch = withDebouncedState<string>(scene, 'search', '', 300);
+
+// These rapid calls will be debounced
+debouncedSearch.set('a');
+debouncedSearch.set('ab');
+debouncedSearch.set('abc'); // Only this final value will be set after 300ms
+```
+
+### Utilities
+
+#### `validators`
+
+Pre-built validation functions for common patterns.
+
+```typescript
+import { validators } from 'phaser-hooks';
+
+const scoreState = withGlobalState<number>('score', 0, {
+  validator: validators.numberRange(0, 1000),
+});
+
+const nameState = withGlobalState<string>('name', '', {
+  validator: validators.nonEmptyString,
+});
+```
+
+#### `batchStateUpdates`
+
+Utility for batching multiple state updates.
+
+```typescript
+batchStateUpdates(() => {
+  playerState.set({ ...playerState.get(), hp: 90 });
+  inventoryState.set([...inventoryState.get(), 'new-item']);
+  scoreState.set(scoreState.get() + 100);
+});
+```
+
+## Basic Usage Example
+
+```typescript
+import { withLocalState, withGlobalState } from 'phaser-hooks';
+
+export class GameScene extends Phaser.Scene {
+  create() {
+    // Local state - specific to this scene
+    const playerState = withLocalState<{ hp: number; mp: number }>(
+      this,
+      'player',
+      {
+        hp: 100,
+        mp: 50,
+      }
+    );
+
+    // Global state - persists across scenes
+    const gameState = withGlobalState<{ score: number; level: number }>(
+      'game',
+      {
+        score: 0,
+        level: 1,
+      }
+    );
+
+    // Listen to changes
+    playerState.onChange((newPlayer, oldPlayer) => {
+      console.log('Player health changed:', newPlayer.hp);
+    });
+
+    // Update state
+    playerState.set({
+      ...playerState.get(),
+      hp: playerState.get().hp - 10,
+    });
+  }
+}
+```
+
+## Advanced Example
+
+```typescript
+import {
+  withPersistentState,
+  withComputedState,
+  withUndoableState,
+  validators,
+} from 'phaser-hooks';
+
+export class AdvancedGameScene extends Phaser.Scene {
+  create() {
+    // Persistent settings
+    const settings = withPersistentState<GameSettings>('settings', {
+      soundVolume: 0.8,
+      musicVolume: 0.6,
+      difficulty: 'normal',
+    });
+
+    // Player state with validation
+    const player = withLocalState<PlayerData>(
+      this,
+      'player',
+      {
+        hp: 100,
+        maxHp: 100,
+        level: 1,
+      },
+      {
+        validator: validators.oneOf(['easy', 'normal', 'hard']),
+      }
+    );
+
+    // Computed health percentage
+    const healthPercent = withComputedState(this, 'healthPercent', player, p =>
+      Math.round((p.hp / p.maxHp) * 100)
+    );
+
+    // Undoable action system
+    const actionHistory = withUndoableState<string>(this, 'actions', 'start');
+
+    // Use the states
+    console.log('Health:', healthPercent.get() + '%');
+
+    if (healthPercent.get() < 20) {
+      console.log('Low health warning!');
+    }
+  }
+}
+```
+
+### Composing Hooks
+
+You can compose your own hooks using other with\* hooks — similar to how custom React hooks are built. This is a powerful way to isolate logic, reuse behavior, and keep your scenes clean and focused.
+
+Example: Extracting a withPlayerEnergy hook from withPlayerState
+
+Imagine you have a local player state like this:
+
+```ts
+interface PlayerAttributes {
+  energy: number;
+  stamina: number;
+  strength: number;
+  agility: number;
+}
+
+const playerState = withLocalState<PlayerAttributes>(scene, 'player', {
+  energy: 100,
+  stamina: 80,
+  strength: 50,
+  agility: 40,
+});
+```
+
+You can now create a custom hook focused only on energy:
+
+```ts
+function withPlayerEnergy(scene: Phaser.Scene) {
+  const player = withLocalState<PlayerAttributes>(scene, 'player', {
+    energy: 100,
+    stamina: 80,
+    strength: 50,
+    agility: 40,
+  });
+
+  return {
+    get: () => player.get().energy,
+    set: (value: number) => player.set({ ...player.get(), energy: value }),
+    onChange: (fn: (energy: number) => void) =>
+      player.onChange(newVal => fn(newVal.energy)),
+  };
+}
+```
+
+Usage in a scene
+
+```ts
+const energy = withPlayerEnergy(this);
+
+console.log('Current energy:', energy.get());
+
+energy.set(energy.get() - 10);
+
+energy.onChange(newEnergy => {
+  if (newEnergy <= 0) {
+    console.warn('You are out of energy!');
+  }
+});
+```
+
+### Why use this pattern?
+
+✅ Keeps your scene code focused on intent (e.g., energy.get()) rather than structure (player.get().energy)
+
+✅ Allows centralized validation, side effects, or formatting for specific state slices
+
+✅ Makes it easier to refactor or share logic across scenes and systems
+
+You can extend this idea to compose computed hooks, persistent hooks, undoable hooks, and more — everything works with the same API.
+
+## TypeScript Support
+
+All hooks are fully typed and provide excellent TypeScript support:
+
+```typescript
+interface PlayerData {
+  hp: number;
+  maxHp: number;
+  level: number;
+  inventory: string[];
+}
+
+const playerState = withLocalState<PlayerData>(scene, 'player', {
+  hp: 100,
+  maxHp: 100,
+  level: 1,
+  inventory: [],
+});
+
+// TypeScript knows the exact type
+const currentPlayer: PlayerData = playerState.get();
+```
+
+## License
+
+MIT

package/dist/hooks/batch-state-updates.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility to batch multiple state updates
+ * @param updateFn Function that performs multiple state updates
+ *
+ * @example
+ * ```typescript
+ * batchStateUpdates(() => {
+ *   playerState.set({...playerState.get(), hp: 90});
+ *   inventoryState.set([...inventoryState.get(), 'new-item']);
+ *   scoreState.set(scoreState.get() + 100);
+ * });
+ * ```
+ */
+export declare const batchStateUpdates: (updateFn: () => void) => void;
+//# sourceMappingURL=batch-state-updates.d.ts.map

package/dist/hooks/batch-state-updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-state-updates.d.ts","sourceRoot":"","sources":["../../src/hooks/batch-state-updates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,IAAI,KAAG,IAKxD,CAAC"}

package/dist/hooks/batch-state-updates.js

@@ -0,0 +1,20 @@
+/**
+ * Utility to batch multiple state updates
+ * @param updateFn Function that performs multiple state updates
+ *
+ * @example
+ * ```typescript
+ * batchStateUpdates(() => {
+ *   playerState.set({...playerState.get(), hp: 90});
+ *   inventoryState.set([...inventoryState.get(), 'new-item']);
+ *   scoreState.set(scoreState.get() + 100);
+ * });
+ * ```
+ */
+export const batchStateUpdates = (updateFn) => {
+    // Note: This is a placeholder for potential batching optimization
+    // In a more advanced implementation, you might collect all updates
+    // and apply them in a single registry update
+    updateFn();
+};
+//# sourceMappingURL=batch-state-updates.js.map

package/dist/hooks/batch-state-updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-state-updates.js","sourceRoot":"","sources":["../../src/hooks/batch-state-updates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAAoB,EAAQ,EAAE;IAC9D,kEAAkE;IAClE,mEAAmE;IACnE,6CAA6C;IAC7C,QAAQ,EAAE,CAAC;AACb,CAAC,CAAC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,11 @@
+export * from './batch-state-updates';
+export * from './type';
+export * from './validators';
+export * from './with-computed-state';
+export * from './with-debounced-state';
+export * from './with-global-state';
+export * from './with-local-state';
+export * from './with-persistent-state';
+export * from './with-state-def';
+export * from './with-undoable-state';
+//# 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,uBAAuB,CAAC;AACtC,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,11 @@
+export * from './batch-state-updates';
+export * from './type';
+export * from './validators';
+export * from './with-computed-state';
+export * from './with-debounced-state';
+export * from './with-global-state';
+export * from './with-local-state';
+export * from './with-persistent-state';
+export * from './with-state-def';
+export * from './with-undoable-state';
+//# 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,uBAAuB,CAAC;AACtC,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/hooks/type.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Callback function type for state changes
+ * @template T The type of the state value
+ * @param newValue The new state value after the change
+ * @param oldValue The previous state value before the change
+ */
+export type StateChangeCallback<T> = (newValue: T, oldValue: T) => void;
+/**
+ * Utility type for state selectors
+ * @template T The input state type
+ * @template U The computed result type
+ */
+export type StateSelector<T, U> = (state: T) => U;
+/**
+ * Utility type for state updaters
+ * @template T The state type
+ */
+export type StateUpdater<T> = (currentState: T) => T;
+/**
+ * Core interface for all state management hooks in Phaser games.
+ * Provides a React-like state management API with get/set/onChange functionality.
+ *
+ * @template T The type of the state value being managed
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const scoreState: HookState<number> = withLocalState(scene, 'score', 0);
+ *
+ * // Getting current value
+ * const currentScore = scoreState.get();
+ *
+ * // Setting new value
+ * scoreState.set(100);
+ *
+ * // Listening to changes
+ * scoreState.onChange((newScore, oldScore) => {
+ *   console.log(`Score changed from ${oldScore} to ${newScore}`);
+ * });
+ * ```
+ */
+export type HookState<T> = {
+    /**
+     * Gets the current state value
+     * @returns The current state value
+     */
+    get: () => T;
+    /**
+     * Sets a new state value and triggers change listeners
+     * @param value The new value to set
+     */
+    set: (value: T) => void;
+    /**
+     * Registers a callback to be called whenever the state changes
+     * @param callback Function to call when state changes
+     */
+    onChange: (callback: StateChangeCallback<T>) => void;
+};
+//# sourceMappingURL=type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../src/hooks/type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC,CAAC;IAEb;;;OAGG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAExB;;;OAGG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACtD,CAAC"}

package/dist/hooks/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/dist/hooks/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../src/hooks/type.ts"],"names":[],"mappings":""}

package/dist/hooks/validators.d.ts

@@ -0,0 +1,26 @@
+/**
+ * State validator function type
+ */
+export type StateValidator = (value: unknown) => boolean | string;
+/**
+ * Creates a state validator function for common patterns
+ */
+export declare const validators: {
+    /**
+     * Validates that a number is within a range
+     */
+    numberRange: (min: number, max: number) => StateValidator;
+    /**
+     * Validates that a string is not empty
+     */
+    nonEmptyString: (value: unknown) => boolean | string;
+    /**
+     * Validates that an array has a specific length range
+     */
+    arrayLength: (min: number, max?: number) => StateValidator;
+    /**
+     * Validates that a value is one of the allowed options
+     */
+    oneOf: <T>(allowedValues: T[]) => StateValidator;
+};
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/hooks/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,MAAM,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;uBAEK,MAAM,OAAO,MAAM,KAAG,cAAc;IAY5C;;OAEG;4BACqB,OAAO,KAAG,OAAO,GAAG,MAAM;IAQlD;;OAEG;uBAEK,MAAM,QAAQ,MAAM,KAAG,cAAc;IAe7C;;OAEG;YAEA,CAAC,iBAAiB,CAAC,EAAE,KAAG,cAAc;CAO1C,CAAC"}

package/dist/hooks/validators.js

@@ -0,0 +1,54 @@
+/**
+ * Creates a state validator function for common patterns
+ */
+export const validators = {
+    /**
+     * Validates that a number is within a range
+     */
+    numberRange: (min, max) => (value) => {
+        const num = value;
+        if (typeof num !== 'number' || Number.isNaN(num)) {
+            return 'Value must be a number';
+        }
+        if (num < min || num > max) {
+            return `Value must be between ${min} and ${max}`;
+        }
+        return true;
+    },
+    /**
+     * Validates that a string is not empty
+     */
+    nonEmptyString: (value) => {
+        const str = value;
+        if (typeof str !== 'string' || str.trim().length === 0) {
+            return 'Value must be a non-empty string';
+        }
+        return true;
+    },
+    /**
+     * Validates that an array has a specific length range
+     */
+    arrayLength: (min, max) => (value) => {
+        const arr = value;
+        if (!Array.isArray(arr)) {
+            return 'Value must be an array';
+        }
+        if (arr.length < min) {
+            return `Array must have at least ${min} items`;
+        }
+        if (max !== undefined && arr.length > max) {
+            return `Array must have at most ${max} items`;
+        }
+        return true;
+    },
+    /**
+     * Validates that a value is one of the allowed options
+     */
+    oneOf: (allowedValues) => (value) => {
+        if (!allowedValues.includes(value)) {
+            return `Value must be one of: ${allowedValues.join(', ')}`;
+        }
+        return true;
+    },
+};
+//# sourceMappingURL=validators.js.map

package/dist/hooks/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/hooks/validators.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;;OAEG;IACH,WAAW,EACT,CAAC,GAAW,EAAE,GAAW,EAAkB,EAAE,CAC7C,CAAC,KAAc,EAAoB,EAAE;QACnC,MAAM,GAAG,GAAG,KAAe,CAAC;QAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,OAAO,wBAAwB,CAAC;QAClC,CAAC;QACD,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,EAAE,CAAC;YAC3B,OAAO,yBAAyB,GAAG,QAAQ,GAAG,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEH;;OAEG;IACH,cAAc,EAAE,CAAC,KAAc,EAAoB,EAAE;QACnD,MAAM,GAAG,GAAG,KAAe,CAAC;QAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvD,OAAO,kCAAkC,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,WAAW,EACT,CAAC,GAAW,EAAE,GAAY,EAAkB,EAAE,CAC9C,CAAC,KAAc,EAAoB,EAAE;QACnC,MAAM,GAAG,GAAG,KAAkB,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,wBAAwB,CAAC;QAClC,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACrB,OAAO,4BAA4B,GAAG,QAAQ,CAAC;QACjD,CAAC;QACD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YAC1C,OAAO,2BAA2B,GAAG,QAAQ,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEH;;OAEG;IACH,KAAK,EACH,CAAI,aAAkB,EAAkB,EAAE,CAC1C,CAAC,KAAc,EAAoB,EAAE;QACnC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAU,CAAC,EAAE,CAAC;YACxC,OAAO,yBAAyB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACJ,CAAC"}

package/dist/hooks/with-computed-state.d.ts

@@ -0,0 +1,24 @@
+import { type HookState, type StateSelector } from './type';
+/**
+ * Creates a computed state that derives its value from other states
+ * @template T The input state type
+ * @template U The computed result type
+ * @param scene The Phaser scene instance
+ * @param key Unique identifier for the computed state
+ * @param sourceState The source state to derive from
+ * @param selector Function to compute the derived value
+ * @returns HookState with computed value
+ *
+ * @example
+ * ```typescript
+ * const playerState = withLocalState<{hp: number, maxHp: number}>(scene, 'player', {...});
+ * const healthPercentage = withComputedState(
+ *   scene,
+ *   'healthPercent',
+ *   playerState,
+ *   (player) => (player.hp / player.maxHp) * 100
+ * );
+ * ```
+ */
+export declare const withComputedState: <T, U>(scene: Phaser.Scene, key: string, sourceState: HookState<T>, selector: StateSelector<T, U>) => HookState<U>;
+//# sourceMappingURL=with-computed-state.d.ts.map

package/dist/hooks/with-computed-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-computed-state.d.ts","sourceRoot":"","sources":["../../src/hooks/with-computed-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,CAAC,EACpC,OAAO,MAAM,CAAC,KAAK,EACnB,KAAK,MAAM,EACX,aAAa,SAAS,CAAC,CAAC,CAAC,EACzB,UAAU,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,KAC5B,SAAS,CAAC,CAAC,CAoBb,CAAC"}

package/dist/hooks/with-computed-state.js

@@ -0,0 +1,40 @@
+import { withLocalState } from './with-local-state';
+/**
+ * Creates a computed state that derives its value from other states
+ * @template T The input state type
+ * @template U The computed result type
+ * @param scene The Phaser scene instance
+ * @param key Unique identifier for the computed state
+ * @param sourceState The source state to derive from
+ * @param selector Function to compute the derived value
+ * @returns HookState with computed value
+ *
+ * @example
+ * ```typescript
+ * const playerState = withLocalState<{hp: number, maxHp: number}>(scene, 'player', {...});
+ * const healthPercentage = withComputedState(
+ *   scene,
+ *   'healthPercent',
+ *   playerState,
+ *   (player) => (player.hp / player.maxHp) * 100
+ * );
+ * ```
+ */
+export const withComputedState = (scene, key, sourceState, selector) => {
+    // Initialize with computed value
+    const initialValue = selector(sourceState.get());
+    const computedState = withLocalState(scene, key, initialValue);
+    // Update computed state when source changes
+    sourceState.onChange(newSourceValue => {
+        const newComputedValue = selector(newSourceValue);
+        computedState.set(newComputedValue);
+    });
+    return {
+        get: computedState.get,
+        set: () => {
+            throw new Error(`[withComputedState] Cannot directly set computed state "${key}". Update the source state instead.`);
+        },
+        onChange: computedState.onChange,
+    };
+};
+//# sourceMappingURL=with-computed-state.js.map

package/dist/hooks/with-computed-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-computed-state.js","sourceRoot":"","sources":["../../src/hooks/with-computed-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,KAAmB,EACnB,GAAW,EACX,WAAyB,EACzB,QAA6B,EACf,EAAE;IAChB,iCAAiC;IACjC,MAAM,YAAY,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,MAAM,aAAa,GAAG,cAAc,CAAI,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;IAElE,4CAA4C;IAC5C,WAAW,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE;QACpC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;QAClD,aAAa,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,EAAE,aAAa,CAAC,GAAG;QACtB,GAAG,EAAE,GAAS,EAAE;YACd,MAAM,IAAI,KAAK,CACb,2DAA2D,GAAG,qCAAqC,CACpG,CAAC;QACJ,CAAC;QACD,QAAQ,EAAE,aAAa,CAAC,QAAQ;KACjC,CAAC;AACJ,CAAC,CAAC"}