Files

gamehoster-game.json

Game-wide configuration: title, how players browse and create, the two clocks, and capacity. See Usage → Games.

gamehoster-game-startup.js

An optional script that runs once, on the server, when the game first starts up, before any player connects. Use it for one-time setup, such as creating a set of standing instances to drop into. See Usage → Games.

gamehoster-player-join-schema.json

What a player provides on connect, fixed for the whole session. An array of field objects, each with fully-qualified keys and no sync/audience (join data is fixed, never streamed state). See Usage → Players.

gamehoster-player-join.js

Runs on the server the moment a player connects, and does two jobs: it routes the player into an instance (picking a live one that still has room or creating a fresh one) and then sets them up, filling their per-instance state from their fixed join data. Gamehoster.Context.playerId is the joining player; once they have joined, Gamehoster.Context.instanceId names their instance. See Usage → Players.

gamehoster-player-schema.json

The player's per-instance state (the fields they carry inside an instance) in the compact, typed form: a map keyed by field name, each entry an object { type, sync, [audience], [smooth], [default] }. See Usage → Players. The instance and entity schemas share this exact shape. Each field declares sync (how a client obtains the value) and, unless it is server-only, an audience (who may receive it), plus an optional smooth.

gamehoster-player-leave.js

Backend: cleanup when a player leaves their instance. Gamehoster.Context.playerId is the leaving player and Gamehoster.Context.instanceId their instance. See Usage → Players.

gamehoster-player-view.js

Optional: per-viewer relevance (fog of war). It runs on the backend at the send rate, viewer-centric (Gamehoster.Context.playerId is the viewer), and marks which players and entities are relevant to that viewer with Gamehoster.View.Include(id). Relevance is the outer gate: a thing you are not shown sends you none of its fields, and one becoming relevant arrives as an enter (leaving, as a leave), so include a thing slightly before it is needed to pre-fetch it. Omit this file and everything is relevant to everyone: full visibility. Large data (maps, level geometry) is modelled as entities so it streams once on enter, not per tick. See Usage → Players.

gamehoster-player-update-backend.js

The player's own per-tick update: the optional, backend-only private extra, run after the shared gamehoster-player-update-frontend.js (which the backend runs first). It writes only its own state, but unlike the shared file it may reach that player's server and sent fields and make discrete authoritative writes, and it may call Gamehoster.Entropy(). Gamehoster.Context.playerId is the player and Gamehoster.Context.instanceId the instance. Omit it entirely for an all-shared player. See Usage → Updates.

gamehoster-player-update-frontend.js

The player's own per-tick update: the shared body, run on both sides (the client and the backend, which runs it first). It predicts where it can: it may read the shared and sent fields of relevant objects plus its own owner fields, and may .Set only its own shared / owner fields; it never reads server fields. It may call Gamehoster.Random() (predictable) but not Gamehoster.Entropy(), since predicted state must stay deterministic. Gamehoster.Context.playerId is the player and Gamehoster.Context.instanceId the instance. Optional: omit it for an all-private player that lives only in gamehoster-player-update-backend.js. See Usage → Updates.

gamehoster-instance-schema.json

The instance's own state, the fields that describe the whole room rather than any one player or entity: the phase (waiting / playing / over), the winner, and the fixed tuning constants that shape a match. Same compact form as the player schema: a map keyed by field name, each entry { type, sync, [audience], [smooth], [default] }. Instance state stays small and always relevant (phase, score, constants); it is never gated by view. See Usage → Instances.

gamehoster-instance-update-backend.js

The instance update's optional, backend-only private extra: step 3 of the tick, run after the shared gamehoster-instance-update-frontend.js (which the backend runs first). The one place for global, authoritative change: the phase machine (waiting → playing → over), scoring, the serve, cross-cutting logic, and spawning or destroying entities. It may write server / sent fields and call Gamehoster.Entropy(). Gamehoster.Context.instanceId is the instance; there is no current player here. See Usage → Updates.

gamehoster-instance-update-frontend.js

The instance update's shared body, run on both sides (the client and the backend, which runs it first): the predictable part, reading shared / sent fields and writing only shared ones. No spawn or destroy; scoring, the serve and the phase machine are backend-only and arrive as sent state. May call Gamehoster.Random() but not Gamehoster.Entropy(). Gamehoster.Context.instanceId is the instance. Optional, like its backend counterpart: a slot may have either file, both, or neither. See Usage → Updates.

gamehoster-commands/<name>/gamehoster-command-schema.json

One directory per command under gamehoster-commands/: holding this parameter schema, the gamehoster-command.json writes manifest, and the handler. The schema is the command's input parameters, keyed by name: each entry is { type } (for example an axis number, or a { from, to } pair). Command parameters carry no sync/audience; they are transient input, not stored state. An empty object is a bare trigger with no parameters. See Usage → Commands.

gamehoster-commands/<name>/gamehoster-command.json

The command's declarative dependency manifest, one key, writes: the list of state fields the handler may change, as dotted paths player.<field> (the sender's own state) or instance.<field>. A command whose only effect is a server-side spawn or authoritative change writes [].

{ "writes": ["player.y"] }

writes feeds the deploy-time predictability check and nothing else. A field's sync is fixed in its schema, the same for every viewer; it never splits shared-vs-sent per player at runtime. From writes the engine proves, once, that each shared field is reproducible on every client that can see it (its inputs owner-driven and in view); a field that could depend on out-of-view state must be sent, and the check rejects the definition until it is. See Usage → Commands.

gamehoster-commands/<name>/gamehoster-command-handler-frontend.js

The shared handler. Applies the command on both sides. Gamehoster.Context.playerId is the sending player and Gamehoster.Context.instanceId their instance. It writes only the sender's shared and owner fields, and only the ones the command writes, so every client reproduces the same result. A command that isn't allowed right now is simply ignored: the handler reads the sender's state and does nothing when it doesn't permit the action. Being deterministic it has Gamehoster.Random() but not Gamehoster.Entropy(). See Usage → Commands.

gamehoster-commands/<name>/gamehoster-command-handler-backend.js

Optional. Runs on the server only, right after the shared handler, for a command with a private or authoritative effect: a hidden roll, an entity spawn, a write to a sent or server field. It reaches the world through the same Gamehoster.* as the shared handler, with the sender in Gamehoster.Context, and being server-only it may write everything and use Gamehoster.Entropy(). Most commands have none. See Usage → Commands.

gamehoster-entities/<type>/gamehoster-entity-schema.json

One directory per entity type under gamehoster-entities/. The schema is the entity's own state, in the same compact form as the player and instance schemas: a map keyed by field name, each entry { type, sync, [audience], [smooth], [default] }. Entities are the unit of relevance, so large streamed data (maps, geometry, assets) is modelled as an entity and sent once on enter. See Usage → Entities.

gamehoster-entities/<type>/gamehoster-entity-update-backend.js

The entity update's optional, backend-only private extra: step 2 of the tick, run after the shared gamehoster-entity-update-frontend.js (which the backend runs first). It writes only its own state, but may reach that entity's server / sent fields and call Gamehoster.Entropy(). Gamehoster.Context.entityId is the entity and Gamehoster.Context.instanceId its instance. Omit it for an all-shared entity, as pong's ball does, keeping only the shared file. See Usage → Updates.

gamehoster-entities/<type>/gamehoster-entity-update-frontend.js

The entity update's shared body, run on both sides (the client and the backend, which runs it first), the predictable part: reads shared / sent fields, writes its own shared fields only. May call Gamehoster.Random() but not Gamehoster.Entropy(). Gamehoster.Context.entityId is the entity and Gamehoster.Context.instanceId its instance. Optional: pong's ball is one integration step and keeps only this file; an all-private entity keeps only gamehoster-entity-update-backend.js. See Usage → Updates.