The stage: lights, particles, floors

Français · Type: reference · Audience: author · Context: engine repository, created project · Status: ready · Applies from: 3.4.0

A room can show more than its backdrop: layers in front of and behind the characters, things that hide a character standing behind them, pools of light, rain or dust, several floors joined by stairs, and a transition when the room is entered. This page is the reference of a room's stage and of the layout fields that place it.

The stage of a room

Three parts share the work:

• the content says what exists and when: stage in the room file;
• the layout says where: layers, occluders, walkZones, walkLinks, lights and emitters in the room's layout, written by the Studio's editors;
• the painter draws it.

Nothing on the stage is game state. A layer, a light or a particle never changes what the solver sees, and a gated walk link is a way to walk, never a puzzle by itself: the puzzle is a rule. tests/stage.test.ts proves the sample game with a stage on every room and finds the same states.

stage: {
  layers: [
    { id: 'sky', image: 'pier/sky', role: 'backdrop' },               // behind everything (else `decor` is the backdrop)
    { id: 'counter', image: 'pier/counter', role: 'scenery' },        // among the characters, by its layout `z`
    { id: 'lantern', image: 'pier/lantern', role: 'foreground', visible: 'lantern_lit' },  // in front of everyone
    { id: 'fog', image: 'pier/fog', role: 'effect' },                 // above all
  ],
  lights: [{ id: 'lamp', kind: 'radial', color: '#ffd28a', intensity: 0.7, visible: 'lantern_lit' }],
  emitters: [{ id: 'spray', kind: 'rain', rate: 40 }],
  transition: 'fade',                                                  // cut (default), fade, wipe
  links: { stairs: { if: 'gate_open', locked: 'The gate is shut.' } }, // the logic of a walk link
},

An old room is a stage of one backdrop (decor) and one walk zone (walk, named main): nothing to rewrite.

Guarantee · stage-not-state · referenced · executed on aff6caab7514 · scope self-checked by the author (AI), not reviewed Layers, lights and a transition on every room of the sample game change nothing the solver reports: the same verdict, the same number of states, the same number of softlocks.

In the room: stage

The types are in src/engine/core/types/stage.ts.

layers

lights

emitters

Particles are seeded: the same room draws the same particles.

transition

How the room appears when entered: cut (default), fade or wipe, or { kind, ms } to set the duration. Reduced motion makes every transition a cut.

links

The logic of the layout's walk links, by link id: if (the link can be walked only while it holds) and locked (what the hero says when trying it while it is closed). See Walk links below.

In the layout: where it stands

The Studio's editors write these in the room's layout file; you do not type them by hand (see Placement and stage).

A zoomed camera also moves up and down to keep the hero in view. The geometry itself (walk areas, holes, depth scale, the camera) is explained on Geometry.

Walk links and their puzzle

A link that is closed (its if in stage.links does not hold) cannot be walked: the hero walks to its foot, says its locked line, and the action goes on from there. So the rules about what stands behind the link must check the same condition: the puzzle is the rule, the link only stops the walk. The lint warns when a rule behind a link does not check its condition (walk-link-gate):

# in the created project
npx quest-n-click lint

# in the engine repository
GAME=<id> npm run lint

The walker takes the fewest links between two points.

Which painter draws what

renderer: 'canvas' (on the room, or on the game for every room) chooses the Canvas painter. Masks from images or layers, lights, particles and blend modes are drawn only by it; occluders from a polygon are drawn by both painters. The validator says so on a room painted by the DOM painter (the default). ?renderer=canvas or ?renderer=dom in the game's URL forces one painter for every room, to compare them.

Limit · stage-dom-painter On the DOM painter (the default), mask occluders, lights, particles and blend modes are not drawn. Set renderer: 'canvas' on the rooms that need them.

Reduced motion (the setting, or the system's prefers-reduced-motion) turns off parallax, particles and transitions.

Since

Layers, masks, lights, particles, transitions, several walk zones and links, the per-zone zoom, the Canvas painter and walk-link-gate: 3.4.0. Before 3.4, a room had one backdrop and one walk area, which is still how an old room reads.

Related identifiers

• layout.width, the camera command: Staging.
• walk, scale, entries, hotspots: Geometry.
• Placing layers, lights and zones in the Studio: Placement and stage.
• "I can see it but cannot reach it": Visible but unreachable.

Edit the source of this page · Report an error