@web-engine-dev/state

Game state machine with states, transitions, state stack, update hooks, and persistence.

Features

• State Machine: Enter, update, exit lifecycle
• State Stack: Push/pop for pause screens, menus
• Transitions: Fade, wipe, custom effects
• Persistence: Save/restore state data
• Async States: Loading screens, async transitions

Installation

npm install @web-engine-dev/state
# or
pnpm add @web-engine-dev/state

Quick Start

import { GameStateManager, GameState } from '@web-engine-dev/state';

// Define states
class MenuState extends GameState {
  onEnter() {
    showMenu();
  }

  onUpdate(dt: number) {
    updateMenu(dt);
  }

  onExit() {
    hideMenu();
  }
}

class PlayState extends GameState {
  onEnter() {
    startGame();
  }

  onUpdate(dt: number) {
    updateGame(dt);
  }
}

// Create manager
const states = new GameStateManager();
states.register('menu', new MenuState());
states.register('play', new PlayState());

// Start
states.change('menu');

// Update each frame
states.update(deltaTime);

API Overview

GameState

class MyState extends GameState {
  onEnter(data?: any) {}
  onUpdate(dt: number) {}
  onRender() {}
  onExit() {}
  onPause() {}
  onResume() {}
}

State Manager

Method	Description
register(name, s)	Register a state
change(name, data)	Switch to state
push(name, data)	Push state onto stack
pop()	Pop current state
update(dt)	Update current state
render()	Render current state
current()	Get current state name

State Stack

// Push pause menu (gameplay continues underneath)
states.push('pause');

// Pop to return to gameplay
states.pop();

// Replace current state
states.change('gameOver');

Transitions

states.change('play', data, {
  transition: 'fade',
  duration: 0.5,
  color: '#000000',
});

// Custom transition
states.setTransition('wipe', new WipeTransition());

Persistence

class PlayState extends GameState {
  onSave(): StateData {
    return {
      playerPosition: player.position,
      score: game.score,
    };
  }

  onRestore(data: StateData) {
    player.position = data.playerPosition;
    game.score = data.score;
  }
}

// Save/restore
const saved = states.save();
states.restore(saved);