Scenes, levels and content (game.engine) #

How a game is organised into scenes (title, levels, loading, cinematics, credits), how one follows another, how files are loaded and freed, and the content files (archetypes, scenes, scripts) a game grows by. Readable offline: gripforge docs scenes, or the MCP tool gripforge_docs (topic scenes).

What it is for #

game.engine is the first kit of every game. It does not rewrite the runtime: the loop, the bus, variables, entities, zones, triggers, objectives, spawn and save already run in the player. It names that base and adds three layers a game grows by without engine code: archetypes (entity templates), scenes (places and screens) and scripts (rules compiled to triggers).

It is transparent without content: no archetype, scene, script or start scene means no entity, rule, variable, event or save section, and the game plays as it always did. It is installed first in every new game and is a normal dependency of the kits that claim its vocabulary; removing it needs with_dependents and confirm.

Scenes #

A scene names its world ({ kit, config?, doc? }), its entries, its instances ({ id, archetype, at, yaw?, place?, set? }), zones, per-scene data, layers, audio and ui. A game without any scene uses the implicit scene main: kits read their global collections.

A scene has:

{ "id": "title", "kind": "interface", "role": "menu", "next": "level_1", "background": { "video": "media/title.webm" } }
{ "id": "level_1", "role": "level", "world": { "kit": "world.racetrack", "doc": "oval" }, "next": "level_2" }

A scene's world hands its config to the world kit (for example world.terrain), over the kit's own config. Kits that build or dress a scene implement sceneEnter and sceneExit; their data lives in the scene's data (for example minion_routes).

Tools #

gripforge game-scenes <gkp_id> <action> (MCP gripforge_game_scenes) lists, plans, creates, orders and links scenes, edits the flow and the menu, and lists and checks the assets of each scene (gripforge game-scenes help).

The scene flow (sceneFlow config) #

Set with gripforge_gamekit_configure { id: "game.engine", config: { "sceneFlow": { … } } }.

A scene loads its files before it is entered (asset.preload); the asset list of each scene (scene_assets) is generated from its content, can be edited, and is one more source for asset.preload. Progress is the real progress of the preload, never a simulated bar.

Several scenes at once #

A change may keep the scene left: engine.scenes.enter(scene, entry, { unload: false }) or load_scene { scene, unload: false }. The scene left is hidden and paused by default and resumes at once when the game comes back. A scene can be stacked on others: push_scene { scene, below: "run" | "pause" | "hide" } (an inventory over a frozen level), pop_scene. Every loaded scene is visible or hidden, running or paused at any moment: set_scene { scene, visible, paused }. This is saved with the game. Nothing a loaded scene uses is freed.

Scripts and verbs #

A script compiles, in pure TypeScript shared by the server and the web runtime, to ordinary trigger rules that the player runs.

{ "id": "s_cellar_door", "on": "door_cellar",
  "rules": [ { "when": { "interact": "self" }, "if": [ { "has_item": "cellar_key" } ],
               "then": [ { "set_state": { "open": true } }, { "play_clip": "open" }, { "set_solid": false }, { "take_item": "cellar_key" } ],
               "else": [ { "notify": "content.door.locked" } ], "once": true } ] }

Sugars for when: interact, enter / leave (zones), scene (entered / left), talked, quest, state, and gives on an archetype or instance. Engine verbs: set_state, play_clip, set_solid, show, hide, enable_script, disable_script, load_scene, next_scene, push_scene, pop_scene, set_scene, end_game, call, set_talk, patch_data, add_data, remove_data, set_config, set_setting, set_component. Kit verbs keep working (give_item, has_item, add_money, damage…) with the shorthand { verb: arg }.

An archetype has kind (the spawn factory; prop is the engine's), asset ({ slot } or { item }), tags, components (claimed by a kit, or owned by the engine: state, solid, model, size, model.placement, entry), gives and clips.

Hooks, events, services #

{ "id": "locked_keep", "hook": "engine.scene.change", "match": { "to": "keep" }, "if": [{ "var": "story.key", "eq": false }], "cancel": true, "reason": "locked" }

Save #

The section kits["game.engine"] keeps the current scene and entry, visited scenes, per-instance state, played once-rules, disabled scripts, quest statuses, and the visible and paused state of each loaded scene. An old save without it loads into the start scene.

Engines #

The scene flow, the scripts and the hooks run in the web runtime and the Rust kit host (hooks: web and Rust). Godot, Unity and Unreal read the compiled content and the flow; a scene with native is the engine's own scene, loaded by its scene adapter.

When it does not do what you expect #

Logic tick #

Besides scenes, game.engine sets the rate of the game logic: gripforge_gamekit_configure { id: "game.engine", config: { "tick": { "hz": 30, "maxCatchUp": 4, "systems": { "npc.core.decide": 3 } } } }. Logic runs on a fixed tick, the game creator's choice from 5 to 120 Hz (default 30; strategy 10-20, action 30, twitch shooter 60; changeable live, by the authority in multiplayer), separate from the render frame and the physics step, rendering draws the last published poses interpolated between two ticks, so the game plays at the same speed at 30, 60 or 144 frames per second. systems gives a heavy system a period (N ticks, or { every, offset, hz }); never code a throttle. tick is not moddable: every player of a match uses the same tick.