@web-engine-dev/level

Level and world management for game development - loading, unloading, transitions, and streaming.

Features

• Level Loading: Async level loading with progress
• Level Transitions: Fade, wipe, custom effects
• Additive Loading: Load multiple levels together
• Level Streaming: Large world chunk loading
• Entity Persistence: Move entities between levels

Installation

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

Quick Start

import { LevelManager, Level } from '@web-engine-dev/level';

// Create level manager
const levels = new LevelManager({
  world: ecsWorld,
  assets: assetManager,
});

// Register levels
levels.register('menu', './levels/menu.json');
levels.register('level1', './levels/level1.json');

// Load level
await levels.load('menu');

// Transition to level
await levels.transition('level1', {
  effect: 'fade',
  duration: 0.5,
});

API Overview

Level Manager

Method	Description
register(name, path)	Register a level
load(name)	Load level, unload current
loadAdditive(name)	Load level additively
unload(name)	Unload specific level
transition(name, opt)	Transition with effect
isLoaded(name)	Check if level is loaded

Level Definition

{
  "name": "Level 1",
  "entities": [
    {
      "name": "Player",
      "components": {
        "Transform": { "x": 0, "y": 0 },
        "Sprite": { "texture": "player.png" }
      }
    }
  ],
  "assets": ["textures/player.png", "audio/music.mp3"]
}

Transitions

await levels.transition('level1', {
  effect: 'fade',
  duration: 0.5,
  color: '#000000',
});

// Custom transition
levels.registerTransition('wipe', (progress) => {
  // Custom render logic
});

Additive Loading

// Load main level
await levels.load('overworld');

// Add indoor area
await levels.loadAdditive('house_interior');

// Unload indoor when leaving
levels.unload('house_interior');

Entity Persistence

// Mark entity to persist across levels
levels.persist(playerEntity);

// Entity moves to new level
await levels.load('level2');
// Player still exists!

// Remove persistence
levels.unpersist(playerEntity);