Core

Command

Deferred command builders and typed entity-draft helpers.

This module exists for the part of ECS work that wants to describe mutation now and make it visible later. Systems often decide that an entity should be spawned, despawned, or extended while iterating queries, but the actual world change is intentionally deferred until the schedule reaches Game.Schedule.applyDeferred().

Command is therefore the write-side companion to Query:

queries prove what exists right now
commands stage what should exist after the next deferred boundary

Reach for this module when gameplay logic needs explicit world mutation, especially for setup, reset, projectiles, pickups, despawns, and relation edits that should stay schedule-visible instead of happening implicitly.

Examples

// Build drafts as values so spawn intent stays explicit inside the system.
const EnemyWave = Game.System("EnemyWave", {}, ({ commands }) => {
  const enemy = Game.Command.spawn(
    // Validate raw authored input through the constructed descriptor.
    Game.Command.entryRaw(Position, { x: 96, y: 32 }),
    // Add already-validated marker or config components directly.
    [Enemy, {}],
    [Health, 3]
  )

  if (!enemy.ok) {
    return
  }

  // Queue the world write now. The entity becomes visible later.
  commands.spawn(enemy.value)
})

// Make the deferred mutation boundary part of the schedule itself.
const update = Game.Schedule(
  EnemyWave,
  Game.Schedule.applyDeferred(),
  observeSpawnedEnemies
)

Functions

entry

Creates a typed component entry.

entryResult

Lifts an already validated value into an entry result, keeping the failure visible to spawn(...) / insert(...).

entryRaw

Validates raw input through a constructed descriptor and returns an entry result.

insert

Adds entries to a draft. Plain entries return the new draft; if any entry is a Result, the draft is returned as a Result whose error lists every entry's failure (or null).

spawn

Starts a staged entity from component entries.

relate

Stages one outgoing relation edge on an entity draft.

makeCommands

Creates a fresh command queue for a system execution.

Functions

Public command builders that stage entity and component mutations as explicit values.

entry

Source

Creates a typed component entry.

entryResult

Source

Lifts an already validated value into an entry result, keeping the failure visible to spawn(...) / insert(...).

entryRaw

Source

Validates raw input through a constructed descriptor and returns an entry result.

const draft = Game.Command.spawn(
  Game.Command.entryRaw(Position, { x: 8, y: 12 }),
  [Player, {}]
)
if (!draft.ok) return
commands.spawn(draft.value)

insert

Source

Adds entries to a draft. Plain entries return the new draft; if any entry is a Result, the draft is returned as a Result whose error lists every entry's failure (or null).

spawn

Source

Starts a staged entity from component entries.

Drafts are plain values: build them anywhere (including small factories), then queue them with commands.spawn(...). Entries may be [Descriptor, value] pairs or results from entryRaw(...); see insert(...) for how failures are reported.

const makeBullet = (x: number, y: number) =>
  Game.Command.spawn([Position, { x, y }], [Velocity, { x: 0, y: -8 }])

commands.spawn(makeBullet(10, 20))

relate

Source

Stages one outgoing relation edge on an entity draft.

Drafts stay pure: this only records intent so the runtime can attempt to attach the relation when the spawn command is applied.

makeCommands

Source

Creates a fresh command queue for a system execution.

The returned API is intentionally imperative for system authors, but all mutations stay deferred until flush() is applied by the runtime.

Examples

Functions

Related Types