Scene Syntax & Conditions

Where things live

Scene definition

A scene is a plain object. The only required field is id. Anything not listed in the tables below is ignored by SceneManager.

// src/data/scenes/yourPack/whatever.js
import { TIME_OF_DAY, BREAK } from "../util/common.js";

export const SCENES = [
  {
    id: "home.default",              // required, globally unique
    priority: 10,                     // higher wins if multiple scenes match

    // You can write `when`, `if`, `conditions`, or `condition` at scene root.
    when: {
      placeKeys: ["player_home"],
      notPlayerFlags: ["injured"],
    },

    // Opt-in auto navigation (default is OFF):
    // - traversal: inject travel choices when outside
    // - exit: inject an Exit choice when inside a place
    autoChoices: { exit: true },

    // Text can be a string key OR an array of blocks.
    text: [
      "scene.home.default.text",
      { when: { hour: TIME_OF_DAY.evening }, key: "scene.home.default.evening" },
      BREAK,
      { when: { playerFlags: ["injured"] }, keys: ["scene.injured.0", "scene.injured.1"] },
      { keys: ["scene.flavour.0", "scene.flavour.1"], pick: "random" },
      { raw: "(You can also include raw literal text.)" },
    ],

    choices: [
      {
        id: "home.tidyUp",
        text: "choice.home.tidyUp",
        minutes: 10,
        setFlag: "homeIsTidy",
      },
    ],
  },
];

Scene fields (supported)

Text blocks

text can be a single string, or an array of blocks. SceneManager processes blocks top-to-bottom.

import { TIME_OF_DAY, BREAK } from "../util/common.js";

text: [
  "scene.home.default.text",
  { when: { hour: TIME_OF_DAY.morning }, key: "scene.home.default.morning" },
  BREAK,
  { when: { playerFlags: ["injured"] }, keys: [
      "scene.injured.0",
      "scene.injured.1",
  ]},
  { keys: ["scene.flavour.0", "scene.flavour.1"], pick: "random" },
  { raw: "(Raw text here.)" },
]

Choices

Choices are buttons shown under the scene. A choice can: advance time, move the player (location/place), set/clear flags, enqueue an urgent scene, and/or hard-jump to a specific next scene.

choices: [
  {
    id: "travel.toMarket",            // required (unique within the scene)
    text: "choice.travel.toLocation", // recommended (i18n key). If omitted, label falls back to id.

    minutes: 7,                        // optional (defaults to 0)
    hideMinutes: false,                // optional (default false). When true, hides the "(N minutes)" suffix.

    // Optional condition gate for showing the choice:
    when: { notPlayerFlags: ["injured"] },

    // If conditions fail, the choice is normally hidden.
    // showAnyway shows it as disabled (unclickable):
    // showAnyway: true,

    // Optional extra interpolation vars for the label:
    vars: { destName: "Market Square" },

    // Actions (pick what you need):
    moveToLocationId: "market_district", // move to a different location
    // setPlaceId: "shop_01",            // enter a place (place.key becomes currentPlaceKey)
    // setPlaceId: null,                 // exit to outside
    // exitToOutside: true,              // explicit exit to outside
    // moveToHome: true,                 // go home (uses game.homeLocationId/homePlaceId)

    // Flags:
    // setFlag: "waitingForPackage",    // or setFlags: ["a","b"]
    // clearFlag: "waitingForPackage",  // or clearFlags: ["a","b"]

    // Scene control:
    // nextSceneId: "special.cutscene", // hard jump (even if it wouldn't match)
    // queueSceneId: "ambulance.arrives",
    // queuePriority: 999,
  }
]

Choice fields (supported)

Auto navigation (optional)

SceneManager can auto-inject navigation choices into the currently active scene, but only when that scene opts in.

Definitions

• Outside: game.currentPlaceId == null and game.currentPlaceKey == null.
• Inside a place: either currentPlaceId or currentPlaceKey is set.

Traversal choices (when outside)

If the active scene enables autoChoices.traversal, and the player is outside, SceneManager adds choices for:

• Connected locations: based on game.location.neighbors (choice id: travel.location.<neighborId>, text key: choice.travel.toLocation, minutes from edge).
• Places in the current location: based on game.location.places (choice id: travel.place.<placeId>, text key: choice.travel.toPlace, minutes from place.props.minutesFromStreet / place.props.minutes / place.props.travelMinutes or default 2).

Injected choices include vars: { destName }. If your scene already defines a choice with the same id, SceneManager does not add a duplicate.

Exit choice (when inside a place)

If the active scene enables autoChoices.exit, and the player is inside a place, SceneManager injects an Exit choice unless you already defined one.

• Injected id: place.exit
• Injected text key: choice.place.exit
• Injected minutes: place.props.minutesFromStreet / place.props.minutes / place.props.travelMinutes or default 2
• Injected action: exitToOutside: true

Conditions

Conditions decide whether a scene/text/choice is active. Wherever a condition block is supported, you can use any of: when, if, conditions, or condition.

Boolean combinators (all supported keys)

// Explicit AND / OR / NOT
when: {
  and: [ { ... }, { ... } ],   // alias: all
  or:  [ { ... }, { ... } ],   // alias: any
  not: { ... },
}

// Arrays are treated as implicit AND:
when: [
  { outside: true },
  { hour: { between: [18, 23] } },
]

Condition keys (matchers)

Hour gates (UTC)

The hour condition supports several forms. Between ranges are start inclusive and end exclusive. If between: [x, x] the implementation treats it as “all day”.

import { TIME_OF_DAY } from "../util/common.js";

// exact hour
when: { hour: 18 }

// any of these hours
when: { hour: [18, 19, 20] }

// comparator gate (ANDed)
when: { hour: { gte: 18, lt: 23 } }

// between gate (wraps midnight when start > end)
when: { hour: { between: [22, 5] } }

// explicit eq / ne
when: { hour: { ne: 3 } }

// convenience buckets
when: { hour: TIME_OF_DAY.morning }

Numeric gates (stats & skills)

Numeric gates are used by playerStats, playerStat, and playerSkills.

Base stat vs computed stat

// Default: computed/current value
when: {
  playerStats: {
    strength: { gte: 6 },
  }
}

// Use base stat (if the player model supports it)
when: {
  playerStats: {
    strength: { gte: 6, base: true },
  }
}

// Same idea with playerStat shorthand
when: {
  playerStat: { name: "strength", base: true, gte: 6 }
}

Localization vars

When text/choices are translated, the localizer receives a vars object. You can interpolate values in strings using braces: "It is {time.hhmm}", "You are on {street.name}", etc.

Available vars (scene text)

vars = {
  time: {
    hour,       // 0..23 (UTC)
    minute,     // 0..59 (UTC)
    hhmm,       // formatted time, e.g. "18:45"
  },
  location: {
    id,         // current location id
    name,
    tags,       // unique tag list
  },
  place: {
    id,         // current place id (or null)
    key,        // current place key (or null)
    name,       // place.name if inside a real place; otherwise a derived street/virtual name
  },
  street: {
    name,       // derived from any neighbor edge streetName (fallback "Street")
  },
  player: {
    stats: { /* precomputed numeric stats */ }
  },
  npcsHere: [
    { id, name },
    ...
  ],
}

Choice label vars

Choice labels receive all scene vars, plus: minutes (the choice minutes) and anything from choice.vars.

Example i18n string

// i18n dictionary:
"scene.street.default.text": "You are outside on {street.name}. It's {time.hhmm}."

// might render:
You are outside on Maple Street. It's 18:45.

Gotchas

Condition blocks are shared everywhere

Scene selection, conditional text blocks, and conditional choices all use the same condition engine. If it works in one place, it works in all three.

showAnyway renders disabled choices (and clicks do nothing)

If a choice fails its conditions and showAnyway: true, the choice is shown but disabled. Clicking it does not execute actions.

setPlaceKey is not supported on choices

Newlines and paragraph spacing

SceneManager does not reliably insert automatic newlines between blocks. If you need spacing, embed \n or \n\n inside your localized strings.

When nothing matches

If no scene matches, SceneManager falls back to either a configured fallback scene (constructor fallbackSceneId) or the first registered scene, so the game never hard-crashes. If you see an unexpected fallback, your conditions are probably too strict.