Prefab

A template for spawning WorldObjects with a pre-defined component graph. Prefabs are the engine's primary unit of object composition: rather than instantiating a world object and bolting components onto it imperatively, you describe what an "enemy" or "bullet" is once via a Prefab, then ask the World to materialise it whenever you need one.

Anatomy

A prefab carries three things:

• A name, which uniquely identifies it within any PrefabRegistry it is registered against and prefixes the ids of every object it spawns.
• An optional list of tags that every spawn inherits.
• A PrefabComponentMap: keys to factory functions that produce the object's starting components when invoked.

Each Prefab.buildObject call walks the component map, invokes every factory with the same PrefabComponentContext, then registers the resulting components on the new object in a single batch. Because factories run per-spawn, the components themselves are never shared between objects.

Uniqueness and ids

Object ids are minted by an internal IDGenerator keyed by the prefab's name, so an object spawned from enemy is identifiable by an id like enemy@1. The generator is per-prefab-instance, not per-name — if you accidentally construct two new Prefab({ name: 'enemy' }) and use them both against the same world, their id streams will overlap. Register your prefabs against a PrefabRegistry to make that misuse impossible.

Construction

Prefabs are designed to be constructed once at module scope and referenced by every caller that wants to spawn from them:

export const EnemyPrefab = new Prefab({
  name: 'enemy',
  tags: ['hostile'],
  components: {
    controller: ({ object }) => new EnemyController(object),
    graphics: ({ object }) => PolygonGraphics.asRectangle(object, 32, 32),
  },
});

// Elsewhere:
world.createFromPrefab(EnemyPrefab, new Point(100, 100));