API Reference

Core Hooks

`withLocalState`

Scene-specific state that automatically cleans up when the scene is destroyed.

function withLocalState<T>(
  scene: Phaser.Scene,
  key: string,
  initialValue: T,
  options?: HookOptions<T>
): HookState<T>

Parameters

Parameter	Type	Description
`scene`	`Phaser.Scene`	The Phaser scene instance
`key`	`string`	Unique identifier for this state
`initialValue`	`T`	Initial state value
`options`	`HookOptions<T>`	Optional configuration

Returns

HookState<T> - State management object

Example

const playerState = withLocalState(this, 'player', {
  hp: 100,
  level: 1,
});

console.log(playerState.get()); // { hp: 100, level: 1 }

`withGlobalState`

Application-wide state that persists across all scenes.

function withGlobalState<T>(
  scene: Phaser.Scene,
  key: string,
  initialValue: T,
  options?: HookOptions<T>
): HookState<T>

Parameters

Parameter	Type	Description
`scene`	`Phaser.Scene`	The Phaser scene instance
`key`	`string`	Unique identifier for this state
`initialValue`	`T`	Initial state value
`options`	`HookOptions<T>`	Optional configuration

Returns

HookState<T> - State management object

Example

const settingsState = withGlobalState(this, 'settings', {
  soundVolume: 0.8,
  musicEnabled: true,
});

console.log(settingsState.get()); // { soundVolume: 0.8, musicEnabled: true }

Enhanced Hooks

`withPersistentState`

State with automatic localStorage or sessionStorage persistence.

function withPersistentState<T>(
  key: string,
  initialValue: T,
  storage: 'local' | 'session',
  options?: HookOptions<T>
): HookState<T>

Parameters

Parameter	Type	Description
`key`	`string`	Unique identifier for this state
`initialValue`	`T`	Initial state value (used if no saved value exists)
`storage`	`'local' \| 'session'`	Storage type: ‘local’ for localStorage, ‘session’ for sessionStorage
`options`	`HookOptions<T>`	Optional configuration

Returns

HookState<T> - State management object

Example

const userSettings = withPersistentState(
  'settings',
  { volume: 0.8, difficulty: 'normal' },
  'local'
);

// Updates automatically save to localStorage
userSettings.set({ volume: 0.5, difficulty: 'hard' });

`withComputedState`

Derived state that automatically updates when source state changes.

function withComputedState<TSource, TComputed>(
  scene: Phaser.Scene,
  key: string,
  sourceState: HookState<TSource>,
  computeFn: (source: TSource) => TComputed,
  options?: HookOptions<TComputed>
): HookState<TComputed>

Parameters

Parameter	Type	Description
`scene`	`Phaser.Scene`	The Phaser scene instance
`key`	`string`	Unique identifier for this state
`sourceState`	`HookState<TSource>`	Source state to watch
`computeFn`	`(source: TSource) => TComputed`	Function to compute derived value
`options`	`HookOptions<TComputed>`	Optional configuration

Returns

HookState<TComputed> - Computed state object (read-only)

Example

const playerState = withLocalState(this, 'player', {
  hp: 75,
  maxHp: 100,
});

const healthPercent = withComputedState(
  this,
  'healthPercent',
  playerState,
  (player) => Math.round((player.hp / player.maxHp) * 100)
);

console.log(healthPercent.get()); // 75

`withUndoableState`

State with built-in undo/redo functionality.

function withUndoableState<T>(
  scene: Phaser.Scene,
  key: string,
  initialValue: T,
  historyLimit?: number,
  options?: HookOptions<T>
): UndoableHookState<T>

Parameters

Parameter	Type	Description
`scene`	`Phaser.Scene`	The Phaser scene instance
`key`	`string`	Unique identifier for this state
`initialValue`	`T`	Initial state value
`historyLimit`	`number`	Maximum number of history entries (default: 50)
`options`	`HookOptions<T>`	Optional configuration

Returns

UndoableHookState<T> - State object with undo/redo methods

Additional Methods

Method	Description	Returns
`undo()`	Reverts to previous state	`boolean` - Success status
`redo()`	Advances to next state	`boolean` - Success status
`canUndo()`	Checks if undo is available	`boolean`
`canRedo()`	Checks if redo is available	`boolean`
`clearHistory()`	Clears undo/redo history	`void`

Example

const gameHistory = withUndoableState(this, 'history', 'start', 10);

gameHistory.set('move-1');
gameHistory.set('move-2');

gameHistory.undo(); // Back to 'move-1'
gameHistory.redo(); // Forward to 'move-2'

console.log(gameHistory.canUndo()); // true
console.log(gameHistory.canRedo()); // false

`withDebouncedState`

State with debounced updates to prevent rapid successive changes.

function withDebouncedState<T>(
  scene: Phaser.Scene,
  key: string,
  initialValue: T,
  delay: number,
  options?: HookOptions<T>
): HookState<T>

Parameters

Parameter	Type	Description
`scene`	`Phaser.Scene`	The Phaser scene instance
`key`	`string`	Unique identifier for this state
`initialValue`	`T`	Initial state value
`delay`	`number`	Debounce delay in milliseconds
`options`	`HookOptions<T>`	Optional configuration

Returns

HookState<T> - State management object

Example

const searchState = withDebouncedState(this, 'search', '', 300);

// These rapid calls will be debounced
searchState.set('a');
searchState.set('ab');
searchState.set('abc');
// Only 'abc' will be set after 300ms

Utility Functions

`batchStateUpdates`

Batches multiple state updates together.

function batchStateUpdates(updateFn: () => void): void

Parameters

Parameter	Type	Description
`updateFn`	`() => void`	Function containing state updates

Example

batchStateUpdates(() => {
  playerState.set({ ...playerState.get(), hp: 90 });
  inventoryState.set([...inventoryState.get(), 'sword']);
  scoreState.set(scoreState.get() + 100);
});

Types

`HookState<T>`

The core state management interface returned by all hooks.

interface HookState<T> {
  get(): T;
  set(value: T): void;
  on(event: 'change', callback: (newValue: T, oldValue: T) => void): () => void;
  once(event: 'change', callback: (newValue: T, oldValue: T) => void): () => void;
  off(event: 'change', callback: (newValue: T, oldValue: T) => void): void;
  clearListeners(): void;
}

Methods

Method	Description	Parameters	Returns
`get()`	Gets current state value	None	`T`
`set(value)`	Sets new state value	`value: T`	`void`
`on('change', callback)`	Registers change listener	`event: 'change'`, `callback: (newValue: T, oldValue: T) => void`	`() => void` (unsubscribe function)
`once('change', callback)`	Registers one-time listener	`event: 'change'`, `callback: (newValue: T, oldValue: T) => void`	`() => void` (unsubscribe function)
`off('change', callback)`	Removes listener	`event: 'change'`, `callback: (newValue: T, oldValue: T) => void`	`void`
`clearListeners()`	Removes all listeners	None	`void`

`UndoableHookState<T>`

Extended state interface with undo/redo functionality.

interface UndoableHookState<T> extends HookState<T> {
  undo(): boolean;
  redo(): boolean;
  canUndo(): boolean;
  canRedo(): boolean;
  clearHistory(): void;
}

`HookOptions<T>`

Configuration options for hooks.

interface HookOptions<T> {
  validator?: (value: T) => true | string;
  debug?: boolean;
}

Properties

Property	Type	Description
`validator`	`(value: T) => true \| string`	Optional validation function. Return `true` if valid, or an error message string if invalid.
`debug`	`boolean`	Enable debug logging for this state (default: false)

Example

const healthState = withLocalState(
  this,
  'health',
  100,
  {
    validator: (value) => {
      if (value < 0) return 'Health cannot be negative';
      if (value > 100) return 'Health cannot exceed 100';
      return true;
    },
    debug: true,
  }
);

Next Steps

HookState Interface - Detailed HookState documentation
Validators - Built-in validators reference
Getting Started - Quick start guide