Function: createEntity()

createEntity<Vars>(id, variables): SimpleObject<Vars & AssertNoOptionals<Vars>>

Defined in: packages/core/src/gameObjects/fabric.ts:48

Convenience factory that wraps SimpleObject creation.

This function mirrors the fabric-style APIs used for passages so entity authors can define state in plain objects and still get reactive behaviour. The created entity is registered with the game engine via the BaseGameObject constructor and exposes its variables as direct properties.

IMPORTANT: All properties in variables must be required (non-optional). The AssertNoOptionals type enforces this at compile time. Optional properties are not supported because the Proxy-based implementation cannot distinguish between undefined optional values and missing properties. If you need optional-like behavior, use explicit undefined with a union type (e.g., field: undefined as string | undefined).

Type Parameters

Vars

Vars extends InitVarsType

Parameters

id

string

Unique identifier used for registry lookups and persistence.

variables

Vars & AssertNoOptionals<Vars>

Initial reactive state for the entity. Nested objects and arrays are supported and proxied. Must not contain optional properties.

Returns

SimpleObject<Vars & AssertNoOptionals<Vars>>

A SimpleObject instance that can be used anywhere a BaseGameObject is expected.

Example

// ✅ Correct - All properties are required
const player = createEntity('player', {
  health: 100,
  name: 'Hero',
  inventory: [] as string[]
});

// ✅ Correct - Use explicit undefined for optional-like behavior
const character = createEntity('character', {
  name: 'NPC',
  quest: undefined as string | undefined
});

// ❌ Wrong - Optional properties will cause compilation error
const player = createEntity('player', {
  health: 100,
  mana?: 50  // TypeScript error: optional keys not allowed
});