@web-engine-dev/prefab

Reusable entity templates (prefabs) for game engines. Supports variants, nesting, and runtime modification.

Features

• Entity Templates: Reusable entity definitions
• Variants: Override properties from base prefab
• Nesting: Prefabs containing other prefabs
• Runtime Override: Modify instances at runtime
• Hot Reload: Update prefabs during development

Installation

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

Quick Start

import { PrefabManager, Prefab } from '@web-engine-dev/prefab';

// Create prefab manager
const prefabs = new PrefabManager(world);

// Register prefab
prefabs.register('enemy', {
  components: {
    Transform: { x: 0, y: 0 },
    Sprite: { texture: 'enemy.png' },
    Health: { value: 100 },
    AI: { behavior: 'patrol' },
  },
});

// Instantiate
const enemy = prefabs.instantiate('enemy', {
  Transform: { x: 100, y: 50 },
});

API Overview

Prefab Definition

const playerPrefab = {
  name: 'Player',

  components: {
    Transform: { x: 0, y: 0 },
    Sprite: { texture: 'player.png' },
    Health: { value: 100, max: 100 },
    Movement: { speed: 5 },
  },

  children: [
    {
      name: 'Weapon',
      components: {
        Transform: { x: 10, y: 0 },
        Sprite: { texture: 'sword.png' },
      },
    },
  ],
};

Variants

// Base enemy
prefabs.register('enemy', {
  /* ... */
});

// Variant - stronger enemy
prefabs.registerVariant('strong_enemy', 'enemy', {
  overrides: {
    Health: { value: 200 },
    Sprite: { texture: 'strong_enemy.png' },
  },
});

// Instantiate variant
prefabs.instantiate('strong_enemy');

Runtime Override

const entity = prefabs.instantiate('enemy', {
  // Override specific properties
  Transform: { x: 100, y: 200 },
  Health: { value: 50 }, // Damaged enemy
});

Nested Prefabs

prefabs.register('tank', {
  components: {
    Transform: {},
    Sprite: { texture: 'tank_body.png' },
  },
  children: [
    {
      prefab: 'turret', // Reference another prefab
      overrides: {
        Transform: { x: 0, y: -5 },
      },
    },
  ],
});

Loading from Files

// Load prefab from JSON
await prefabs.load('prefabs/player.json');

// Load directory
await prefabs.loadDirectory('prefabs/');