How a game fits together

A game is made of scenes, a scene simulates one world, and a world holds the entities the player sees and touches. Each level is a React component mounted inside the level above it, and UI can sit at any level.

flowchart TB
    Game --> Scene --> Landscape --> Entity
    Game -.-> GU[global UI]
    Scene -.-> SU[scene UI]
    Landscape -.-> WU[world UI]
    Entity -.-> EU[entity UI]
    GU & SU & WU & EU --> Screen

Solid arrows are nesting. Dotted arrows are UI at that level, which the engine draws on the screen over the canvas.

The levels

Level	What it is	It lives as long as
Game	The whole game: its scenes and which one opens first, its plugins, its save, and UI shared by every scene	the page
Scene	One screen of the game, such as a lobby or a level. Only the active scene is mounted, and the engine’s Scene component holds no state of its own	the scene is active
Landscape	The scene’s map, its look and its physics, and every entity in it	its scene is active
Entity	One thing in the world, such as a coin or a door, with a pose and, as it needs them, a model, a body and behaviours	it is destroyed, or its world unmounts

The rule to remember

Put each piece at the lowest level that owns it, because a level’s children go when it goes. UI inside a scene unmounts when the game switches scenes, so a score shown only in a level belongs in that scene, and a coin count shown everywhere belongs at the game’s level. A behaviour inside an entity reads that entity, through useEntity(), and is removed with it.

The nesting decides lifetime, not reach. A hook such as useWallet() reads the player’s wallet from anywhere inside Game, and a system reads and writes the whole world on every step. UI covers the UI primitives at every level.

The words the docs use

• Trait: state on an entity, such as its pose or wallet. defineTrait names it for the dump and devtools and declares whether a room streams it. Its exported name ends in Trait. Entity explains how to add one.
• Behaviour: a child component of an Entity that gives it something to do, such as Spin, Pickup or Health. Each is a trait, a system that acts on it, and the component that adds the trait. Entity lists the engine’s and shows how to write one.
• System: a function the step runs over the world, such as the one that moves every character or takes a coin into a wallet. Systems run in phases, in the order input, motion, rules and physics. Systems covers where a system runs and how it reads the player’s input.
• Plugin: a capability a game lists in its plugins, which brings its systems, inputs, commands and saves. The engine ships its own, such as characters() and inventory(), and a game declares its own with definePlugin. Plugins lists them.
• Step: one fixed tick of the game’s simulation: 30 a second in a game with rooms and 60 in a game played alone, unless the game names the other. Each step runs every system once, phase by phase, so the same input gives the same result. Systems covers it.
• Room: one running copy of a multiplayer game that players join together. It runs the game’s own scene with no window, decides what happens, and sends each player the result. A room holds 20 players by default and up to 100. Multiplayer says what runs where.
• Client: the game running on a player’s device, in the browser. In a room game it sends the player’s input to the room, draws what the room sends back, and moves the player’s own character at once without waiting for the room. A game played alone runs the whole simulation in the client. Multiplayer covers it.

A tour of the example game shows each level and most of these words in one small game. Frame lists what one frame runs and what each line costs, and Internals covers what the engine does underneath.