Runtime

Entity

Entity identities, proofs, and long-lived handles.

This module defines the nominal entity reference types used across queries, commands, relations, and lookup APIs.

In practical game code, it separates short-lived "current runtime entity" identity from durable references that may survive across frames inside components, resources, or events. That distinction is essential for keeping liveness uncertainty explicit instead of pretending a saved reference proves the entity still exists.

Examples

// Turn a current frame entity id into a durable reference.
const handle = Game.Entity.handle(playerId)

// Add an intent when later resolution should require one component proof.
const positioned = Game.Entity.handle(playerId, Position)

Functions

makeEntityId

Creates an opaque entity id from a runtime integer id.

makeHandle

Creates a durable handle from a runtime entity id.

handle

Converts a current entity into a durable handle for storage.

decodeHandle

Decodes a handle from untrusted data, such as a component value inside a snapshot. Use it in the constructor of a component or resource that stores handles, so restoring validates them like any other value.

draft

Creates a typed entity draft from an id and a proof.

ref

Creates a read-only entity proof value.

mut

Creates a mutable entity proof value.

Functions

Explicit helpers for constructing and refining entity ids and handles.

makeEntityId

Source

Creates an opaque entity id from a runtime integer id.

This is a low-level constructor used by the runtime and command system. The value it stores is the stable per-runtime numeric identity exposed on EntityId.

makeHandle

Source

Creates a durable handle from a runtime entity id.

This is a low-level constructor used by the bound Game.Entity helpers and by runtime lookup resolution.

handle

Source

Converts a current entity into a durable handle for storage.

The handle is storage-safe, not a proof of liveness: resolve it later with lookup.getHandle(...), which fails explicitly when the entity is gone.

Pass an intent component when later code assumes a role such as "player" or "damage source". An intent does not prove the component is still present; it forces resolution through a query that proves it.

const any = Game.Entity.handle(match.entity)
const player = Game.Entity.handle(playerId, Player)

decodeHandle

Source

A handle only names an entity; it never proves the entity exists. Resolving it with lookup.getHandle(...) stays the checked step, so any positive integer id decodes.

const Target = Descriptor.ConstructedComponent({
  result: (raw: unknown) => {
    const enemy = Entity.decodeHandle(Root, isRecord(raw) ? raw["enemy"] : undefined, Health)
    return enemy.ok ? Result.success({ enemy: enemy.value }) : enemy
  }
})("Target")

draft

Source

Creates a typed entity draft from an id and a proof.

ref

Source

Creates a read-only entity proof value.

mut

Source

Creates a mutable entity proof value.

Examples

Functions

Related Types