@web-engine-dev/hot-reload

Development-time hot reloading for assets, scripts, and components.

Features

• Asset Hot Reload: Textures, audio, data files
• Script Reload: Component and system updates
• State Preservation: Keep game state across reloads
• WebSocket Server: Real-time file watching
• Selective Reload: Target specific assets

Installation

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

Quick Start

import { HotReloadServer, HotReloadClient } from '@web-engine-dev/hot-reload';

// Server-side (Node.js)
const server = new HotReloadServer({
  port: 3001,
  watch: ['./src', './assets'],
});
server.start();

// Client-side (Browser)
const client = new HotReloadClient({
  url: 'ws://localhost:3001',
});

client.on('asset-changed', (path) => {
  assets.reload(path);
});

client.on('script-changed', (path) => {
  scripts.reload(path);
});

API Overview

Server

const server = new HotReloadServer({
  port: 3001,
  watch: ['./src', './assets'],
  ignored: ['node_modules', '.git'],
  debounce: 100,
});

server.start();
server.stop();

// Programmatic notifications
server.notifyChange('assets/texture.png');

Client

const client = new HotReloadClient({
  url: 'ws://localhost:3001',
  reconnect: true,
  reconnectInterval: 1000,
});

client.on('connect', () => {});
client.on('disconnect', () => {});
client.on('asset-changed', (path) => {});
client.on('script-changed', (path) => {});
client.on('full-reload', () => {});

State Preservation

// Before reload
const state = hotReload.saveState();

// After reload
hotReload.restoreState(state);

// Or automatic
hotReload.enableStatePreservation({
  serialize: () => gameState,
  deserialize: (data) => {
    gameState = data;
  },
});

Integration

import { enableHotReload } from '@web-engine-dev/hot-reload';

// Enable in development
if (import.meta.env.DEV) {
  enableHotReload({
    assets: assetManager,
    scripts: scriptManager,
    world: ecsWorld,
  });
}