world-contract

The boundary between the simulation (tosijs-3d) and an external driver (an AI narrative engine, a scripted demo, anything). The simulation is the authority on physical and systemic reality; the driver decides what any of it means. These two halves never call each other's functions — they share a serializable WorldState, a stream of best-effort SimulationEvents, and the WorldApi surface below.

Example — a driver against the surface

The driver only ever touches the contract: read state, subscribe to intentional-act events, and steer. It never reaches into the sim. (WorldStore is the reference implementation.)

// The subpath, not the barrel: the barrel defines elements and needs a DOM,
// and a driver usually runs headless or in a worker.
import { WorldStore } from 'tosijs-3d/world-store'

const world = new WorldStore() // any implementation of the contract
world.subscribe((event) => {
  // events are COMMITMENTS (interacted / picked-up / chose / died) — never proximity
  if (event.type === 'death') recordConsequence(event.entityId)
})
// The driver names the entity. Across a worker boundary a command cannot
// return a value, so do not rely on the id `spawn` hands back.
world.spawn({ id: 'witness', kind: 'npc', position: { x: 5, y: 0, z: 0 } })
world.steer('witness', { fleeFrom: 'player' }) // advisory: the sim may be late or ignore it

setIntent is deprecated: the intent is stored and nothing reads it, so an entity given only an intent does not move. steer is what the sim honours.

Every query (getState, getEntity, query) returns a copy. Writing to one changes nothing, in-process or across a worker.

Hard rules baked into these types

Running and testing a driver

A driver belongs off the frame thread, and every rule above is what makes that safe: advisory intents survive arriving late, best-effort events can be shed rather than queued, and "query is truth" survives the round trip. A driver can be tested as a black box with no renderer: the real store, seeded synthetic players, and a lossy, reordering transport. min-sim-conformance pins the coordinate-free surface for any implementation.