world

What it does

world holds two modules. ecs is a zero-dependency entity component system: entities, components, tags, resources and systems. projection turns committed state into entities: a keyed reconcile of one view(item) function per projection, with motions, a despawn queue and named layers.

The screen never owns state. A projection reads the committed player and session through its from, keys every item, and calls view(item) for the components of its entity. A commit reconciles the views: new keys enter, gone keys exit, changed items change. Motion hooks are told why they play: "mount" when the view comes or goes with its screen, "change" for a commit.

When a system runs. A system runs once a frame in its phase (input, animate, layout or sync). It is skipped while a term of its query has no entity. With scenes: [...] it runs only while one of those scenes is mounted or leaving.

Resources. resource(name, defaults) clones plain JSON defaults into every world. resource(name, () => value) calls the factory once per world, so the value may hold a Map. The engine resource Now holds the frame's moment: world writes clock.now() into it first thing in every frame. The names Now, Pointer, AnimPlayer and UiCounters are the engine's.

Config

pluginConfigs.world.

API

Mounted at app.world, reachable with ctx.require(worldPlugin).

ecs

projection

Also on projection: hold, show, mute, lift, membershipVersion, motionsOf, restOf, setDriver, viewOf, setRest, registerKey, onConverged, rerunAll, and the scene build build, built, commit, discard, left, isBuilding, onBuild, adopt. Plugins above world use them; a game rarely does. app.world.systemTimes() gives the time of each system in an agent build.

Helpers

From @moku-labs/game: component, tag, resource, mut, system, projection, and the engine's Layer, Order, Exiting, Tree, Now. defineGame returns a projection and a system typed by the game's player and session. Signatures are on the API reference.

A projection spec: name, layer, lift?, from(player, session, sw?), key(item), view(item), the motion hooks enter, exit, change and loop, and initialOnly: fields the view gives once, at birth, and another writer owns after that.

Events

Emits

Listens to

The commits of model.

Example

import { component, createApp, defineFeature, mut, projection, system, Transform, worldPlugin } from "@moku-labs/game";

type Player = { items: { id: string; x: number; y: number }[] };

// A component of the game: a name and plain defaults.
const Spin = component("Spin", { speed: 1 });

// Committed state to entities: one view per item, keyed by its id.
const boardItems = projection({
  name: "board.items",
  layer: "items",
  from: (player: Player) => player.items,
  key: item => item.id,
  view: item => [Transform({ x: item.x, y: item.y }), Spin({ speed: 2 })]
});

// A system runs once a frame in its phase while its query has an entity.
const spin = system({
  name: "board.spin",
  phase: "animate",
  query: [mut(Transform), Spin],
  run: (entities, ctx) => {
    for (const [, transform, { speed }] of entities) transform.rotation += (speed * ctx.time.delta) / 1000;
  }
});

const boardFeature = defineFeature("board", { projections: [boardItems], systems: [spin] });
const app = createApp({ plugins: [worldPlugin, boardFeature] });

// A test drives the screen without a browser: layers, mount, then look a view up by key.
app.world.projection.setLayers([{ name: "items", sort: "y" }]);
app.world.projection.mount(["board.items"], { kind: "plugin", name: "test" });
app.world.projection.entityOf("board.items", "i7");

Related

• Screens: projections, scenes and JSX.
• renderer: draws what the world holds.
• anim: the motions of the views.