@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/docs/guides/scenarios.md

@@ -0,0 +1,515 @@
+# Scenarios
+
+A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant. This guide explains the model, then covers creating, running, and authoring scenarios.
+
+## The model
+
+Games often ship several variants. A business simulation might have 'Standard', 'AI Disruption', and 'Merger' editions that share one engine and one set of UIs but differ in starting values, narrative text, and media. Without scenarios each variant is either a separate game, duplicating everything, or a manual configuration exercise for the facilitator.
+
+A scenario packages the differences as one selectable unit. It holds two things:
+
+1. **Settings overrides**: values that override the game's [settings](./settings.md) for this variant, keyed by settings identifier
+2. **Static assets**: files (images, videos, documents) in the scenario's own `assets/` directory, which the engine and UIs reach through `asset:<path>` references (see [Asset references](./file-handling.md#asset-references))
+
+The facilitator picks a scenario when the session starts, and the game runs with its values as a starting point. Its overrides sit between the settings defaults and whatever the facilitator changes for the session (see [Resolution order](#resolution-order)), so a scenario is a starting point, not a lock.
+
+- **Data-only.** Scenarios carry no logic. They override settings values that the engine, hooks, validators, and UIs already interpret. For different behaviour, put conditional logic in the engine and drive it through settings
+- **Fixed for the session.** A scenario's overrides reach the game through `Init`, so switching scenario means starting again from tick 0
+- **Optional.** Games work without scenarios
+- **One may be the default.** A scenario can mark itself `default: true`, and it is used whenever none is chosen
+- **One may be restricted.** A scenario marked `restricted: true` is built for one audience rather than every client the package is shared with. The package never names that audience: the runtime hosting the game decides who has been granted it
+- **The directory is the declaration.** A scenario is available because it exists under `scenarios/`, and nothing references it
+
+Scenarios come from two places, and they meet in the same settings layer. **Author-time scenarios** are part of the package: you write them by hand, or save them from the dev server's scenario editor, and check them in with the rest of the game. **Custom scenarios** are built by facilitators or customer organisations at session time in a hosted runtime, for a game that opts in (see [Custom scenarios](#custom-scenarios-production-runtimes)). The runtime stores them; they never become part of the package.
+
+### When to use scenarios
+
+Use scenarios when:
+
+- You want to ship several flavours of the same game (different storylines, difficulty levels, themes)
+- Variants share the same engine and UIs but need different starting settings or different media
+- You want facilitators to choose a variant when a session starts
+
+You do not need scenarios if your game has only one variant, if the differences are small enough for a single [setup screen](./setup.md), or if you need to switch variants in the middle of play (a scenario is fixed for the session).
+
+## What you'll learn
+
+- How to create a scenario with settings overrides and assets
+- How to initialise a game with a specific scenario
+- How to load scenario assets in UIs
+- How to test scenarios with the dev server and CLI
+- When to bump `scenarioFormat` so a saved custom scenario is never applied to a game it no longer fits
+
+## Prerequisites
+
+You need an existing game with at least one engine. If you don't have one:
+
+- [Create a Capability](./capabilities.md)
+- [Create an engine](./engine.md)
+- [Shaping Games](./games.md)
+
+## Creating a scenario
+
+### 1. Create the scenario resource
+
+```bash
+pnpm run sdk new scenario '{
+  "definition": {
+    "identifier": "ai_influence",
+    "locales": {
+      "en": {
+        "name": "AI Influence",
+        "description": "A scenario where AI disrupts the market"
+      }
+    },
+    "settings": {
+      "engine": {
+        "BaseDemand": 50,
+        "AIFactor": 1.5
+      }
+    }
+  },
+  "rootDirectory": "."
+}'
+```
+
+This creates:
+
+```
+scenarios/ai_influence/
+├── scenario.sdk.json
+└── assets/
+    └── shared/
+```
+
+The directory is the declaration: nothing registers it.
+
+### 2. Add assets (optional)
+
+Place static files in the `assets/` directory:
+
+```
+scenarios/ai_influence/
+└── assets/
+    └── shared/
+        ├── hero.jpg
+        ├── briefing.pdf
+        └── intro-video.mp4
+```
+
+Files in a scenario's `assets/` directory are referenced as `asset:<path>` and resolve only while that scenario is active. To share one file across several scenarios without copying it, put it in a package-level `shared-assets/` directory and reference it as `shared:<path>` (see [Sharing assets across scenarios](#sharing-assets-across-scenarios) below).
+
+### 3. Mark it as the default (optional)
+
+Nothing references a scenario: the directory under `scenarios/` is the whole of the declaration. To have this one picked when no `--scenario` flag is given, set `default` on the scenario itself:
+
+```bash
+pnpm run sdk update scenario ai_influence --patch '[
+  { "op": "add", "path": "/definition/default", "value": true }
+]'
+```
+
+**Important:** At most one scenario per package may have `"default": true`. If a default is set, it is used automatically when no `--scenario` flag is provided.
+
+A scenario cannot set a setting the game locks with `readOnly`, or a game setting it fixes with `gameSettingsConstraints`: the build refuses it with `SETTINGS_LOCKED`, pointing at the value, even when the value matches the game's own. Remove it from the scenario. See [Lock a setting](./settings.md#lock-a-setting).
+
+### 4. Restrict it to one audience (optional)
+
+Most scenarios are variants every client gets. Some are built for one client, and those should not appear in everybody's scenario picker. Set `restricted` on the scenario:
+
+```bash
+pnpm run sdk update scenario viking_edition --patch '[
+  { "op": "add", "path": "/definition/restricted", "value": true }
+]'
+```
+
+The flag says the scenario is for a particular audience. It never says who they are: that belongs to the runtime hosting the game, which knows about organisations and grants, and keeping it out of the package is what lets the same package be shared between clients.
+
+What a production runtime does with the flag is its own business, but it must not offer a restricted scenario for selection, list it, resolve it by identifier, or serve its assets to a caller it has not granted it to.
+
+Three things are worth knowing before you rely on it:
+
+- **The dev server ignores it.** There are no organisations locally and the package is yours, so restricted scenarios are offered exactly like any other. You cannot test the restriction from here
+- **A restricted scenario cannot also be the default.** A default is what a caller gets when it picks nothing, so it has to be one every caller can be offered. The build refuses a scenario that sets both
+- **It does not cover `shared:` assets.** Files under the package-level `shared-assets/` directory resolve whatever scenario is active, so anything belonging to one client goes under that scenario's own `assets/`, not in `shared-assets/`
+
+The flag protects the scenario only on a runtime that implements grants: one that does not recognise the field offers the scenario normally. What it always does is record the intent in the package, reviewed alongside the content it describes, rather than leaving it to a setting somebody remembers to tick after the upload.
+
+## Scenario definition
+
+A scenario is a directory under `scenarios/`, named by its identifier:
+
+```
+scenarios/ai_influence/
+├── scenario.sdk.json   # Locales, settings overrides, default and restricted flags
+└── assets/
+    └── shared/         # Static files referenced as asset:<path>
+```
+
+The `scenario.sdk.json` file:
+
+```json
+{
+    "definition": {
+        "locales": {
+            "en": {
+                "name": "AI Influence",
+                "description": "A scenario focused on AI-driven market disruption"
+            }
+        },
+        "settings": {
+            "engine": {
+                "BaseDemand": 50,
+                "AIFactor": 1.5
+            },
+            "ui": {
+                "showAIPanel": true
+            }
+        }
+    },
+    "rootDirectory": "."
+}
+```
+
+The `settings` block is keyed by settings identifier (the directory name under `settings/`), then by settings property. The scenario itself is named by its directory, so its bundle carries no `identifier`. At most one scenario per package may set `"default": true`.
+
+## Settings overrides
+
+A scenario overrides [settings resources](./settings.md), keyed by
+settings identifier. It sets only the properties it changes; everything else
+keeps its default. Here the package holds `settings/engine/`, `settings/ui/`
+and `settings/session/`:
+
+```json
+{
+    "definition": {
+        "locales": { "en": { "name": "Hard Mode" } },
+        "settings": {
+            "engine": { "BaseDemand": 30, "InflationRate": 0.15 },
+            "ui": { "showHints": false },
+            "session": { "ShowJoinLinks": false }
+        }
+    }
+}
+```
+
+### Validation
+
+Every override is checked against the named settings resource's `settingsSchema`, by `sdk build` and `sdk build --validate-only` as well as at session start. Overrides are partial, so omitting a key is fine and it falls through to its default. What fails is a key the schema does not declare, usually a misspelling, or a declared key set to a value the schema rejects.
+
+One more thing fails: an identifier that names no settings resource the package declares. It is an override that reads as applied and resolves nothing, so the build catches a misspelling rather than the session it was meant to change.
+
+A failure names the settings resource and the offending key. Read it as a question about both sides: the override may be wrong, or the settings schema may have moved on without the scenario following.
+
+### The number of rounds and the teams
+
+The number of ticks, the team bounds and names, and whether the waiting room opens on start are the built-in `game` settings, so a scenario overrides them under `settings.game` like any other settings resource. A short edition of the game:
+
+```json
+{
+    "definition": {
+        "locales": { "en": { "name": "Short" } },
+        "settings": {
+            "game": { "maxTicks": 4, "teams": { "max": 4 } }
+        }
+    }
+}
+```
+
+`teams.mode` is not among them: a game is independent or shared-state whichever scenario is active. See [The game settings](./settings.md#the-game-settings) for every field.
+
+### Resolution order
+
+A scenario's overrides sit between the settings defaults and the session overrides, so a facilitator can still change a value for one session: the scenario is a starting point, not a lock. See [Overriding settings](./settings.md#overriding-settings) for the full resolution order.
+
+## Overriding team names
+
+A scenario can also rename teams, which is handy when each scenario is a themed variant with its own set of brands. Set `game.teams.defaultNames` in its `settings` (an ordered, localised list, the same shape as a game's `teams.defaultNames`). The scenario's list replaces the game's whole whenever the scenario is active, so list a name for every team the scenario expects.
+
+```json
+{
+    "definition": {
+        "locales": { "en": { "name": "Soft drinks" } },
+        "settings": {
+            "game": {
+                "teams": {
+                    "defaultNames": [
+                        { "en": { "name": "Coca-Cola" } },
+                        { "en": { "name": "Pepsi" } },
+                        { "en": { "name": "Fanta" } }
+                    ]
+                }
+            }
+        }
+    }
+}
+```
+
+Entries are applied by the stable team index: entry N names the team with index N, the same as a game's `teams.defaultNames`. A re-added team recovers its scenario entry along with its index. Names resolve in the session's locale, fall back to another declared locale and then to the positional default ('Team N'), and remain advisory: operators can rename teams at session setup. See [Multi-team games](./multi-team-games.md#naming-teams) for the full resolution rules.
+
+## Running with scenarios
+
+### CLI
+
+```bash
+# Initialize with a specific scenario
+pnpm run sdk init --scenario ai_influence
+
+# Initialize with the default scenario (if one is marked default)
+pnpm run sdk init
+
+# Tick as normal: the scenario is remembered across ticks
+pnpm run sdk tick
+```
+
+### Dev server
+
+```bash
+# Start with a specific scenario
+pnpm run sdk dev --scenario ai_influence
+
+# Start with the default scenario
+pnpm run sdk dev
+```
+
+A scenario's overrides reach your game through `Init`, so a session already
+several ticks in has passed the only moment they mean anything. Switching one is
+therefore a restart rather than an adjustment: the dev drawer's **Scenario** tab
+confirms first, then returns every team to tick 0 (and a game with a
+configuration step back to it), so you can configure on top of the new scenario
+before starting.
+
+From a terminal, the same thing:
+
+```bash
+pnpm run sdk scenario ai_influence   # or `none` for the settings defaults
+```
+
+### Managing scenarios while the server runs
+
+The **Scenario** tab is a small manager, and everything it does writes into your
+own source tree:
+
+- **Activate** one, with the confirmation above
+- **Add scenario** asks for an identifier (a short lowercase name, which names
+  the directory) and where its values start from: the package's own
+  settings defaults, or a copy of one you already have. It writes
+  `scenarios/<identifier>/scenario.sdk.json` straight away from the session put
+  on that starting point, and opens the scenario editor on the new scenario. A
+  copy carries everything its source declares, its locales and descriptions
+  included, under the new identifier as its name, and is never the default
+- **Edit** opens the editor on an existing scenario, leaving the session where
+  it is: the editor edits a draft of the scenario, which reaches a session only
+  once it is saved and a session is started on it
+- **Delete** removes the directory and its assets. The active scenario is
+  refused, because the session is resolved against it: switch to another one
+  first
+
+A production runtime saves a facilitator's scenario to its own store and never
+writes into a package, so all of this is author-time tooling rather than part of
+the runtime contract.
+
+### The scenario editor
+
+The editor is your game's [`scenario_editor` slot](./scenario-editor.md),
+opened **on** one scenario at `/scenario-editor`. It has no entry of its own
+(no menu item, no surface to navigate to), because an editor with nowhere to
+save is a screen that wastes the work somebody does on it. Add and Edit are the
+ways in.
+
+It opens in a new tab, and it edits a draft of that scenario, not the session:
+the session you were looking at keeps its scenario and settings while you work,
+and only **Save** changes anything, by writing the draft into the scenario's
+bundle.
+
+**Save** writes the settings back into that scenario's bundle, replacing its
+`settings` and leaving every other field as you wrote it. **Done** closes the tab's business and returns you to the session.
+
+A game with no `scenario_editor` slot has
+nothing to author scenarios in; the values can still be set with `sdk configure` (keyed by settings identifier)
+and captured by adding a scenario from the current settings.
+
+## Loading scenario assets in UIs
+
+A scenario's files are read through `asset:<path>` references, where `<path>` is relative to the scenario's `assets/` directory; package-level files use `shared:<path>` (see [Sharing assets across scenarios](#sharing-assets-across-scenarios)). Every surface resolves them the same way, with `useAssetUrl` or the `getAssetUrl` callback, and logic reads them with `readAsset`:
+
+```tsx
+import { useAssetUrl } from '@seriousgaming/sdk/ui';
+
+function HeroImage() {
+    const src = useAssetUrl('asset:shared/hero.jpg');
+    return <img src={src} alt="Hero" />;
+}
+```
+
+[Asset references](./file-handling.md#asset-references) covers the schemes, how a reference becomes a URL, and what happens when no scenario is active.
+
+## Sharing assets across scenarios
+
+When two scenarios play the same storyline but differ in a config value, copying the storyline's media into both `assets/` directories means every later edit must be made twice. A package-level `shared-assets/` directory removes the duplication: store each file once and reference it as `shared:<path>` from any scenario.
+
+```
+my-package/
+├── shared-assets/
+│   └── storyline/
+│       ├── hero.jpg
+│       └── intro-video.mp4
+├── scenarios/
+│   ├── ai_influence/scenario.sdk.json
+│   └── merger_influence/scenario.sdk.json
+```
+
+Both scenarios reference the same file, anywhere an `asset:` reference is valid:
+
+```json
+{
+    "definition": {
+        "settings": {
+            "engine": {
+                "Hero": "shared:storyline/hero.jpg"
+            }
+        }
+    }
+}
+```
+
+- `shared:<path>` resolves against `shared-assets/` at the package root, never against a scenario, so it works even when no scenario is active
+- There is no shadowing: a scenario that needs its own version of a file references `asset:<path>` and ships that file in its own `assets/` directory
+- The directory is folder-convention only: no schema, declaration, or CRUD. `seriousgaming-sdk build` copies `shared-assets/` into the bundle root, and a hosted runtime resolves `shared:` references the same way the dev server does
+
+Settings duplication between the two scenarios is fine; asset duplication is the part that drifts. See the [share assets across scenarios recipe](../recipes/share-assets-across-scenarios.md) for the full task.
+
+## Updating a scenario
+
+Replace the full definition:
+
+```bash
+pnpm run sdk update scenario ai_influence '{
+  "definition": {
+    "identifier": "ai_influence",
+    "locales": {
+      "en": { "name": "AI Influence (Updated)" },
+      "fr": { "name": "Influence IA" }
+    },
+    "settings": {
+      "engine": { "BaseDemand": 40 }
+    }
+  },
+  "rootDirectory": "."
+}'
+```
+
+Or apply a patch:
+
+```bash
+pnpm run sdk update scenario ai_influence --patch '[
+  { "op": "replace", "path": "/definition/locales/en/name", "value": "AI Influence v2" },
+  { "op": "replace", "path": "/definition/settings/engine/BaseDemand", "value": 40 }
+]'
+```
+
+## Deleting a scenario
+
+```bash
+pnpm run sdk delete scenario ai_influence --yes
+```
+
+This removes the scenario directory, which is the whole of its declaration. The
+dev drawer's **Scenario** tab does the same thing while the server runs, which is
+the quicker route when you have just saved one by accident.
+
+## Build output
+
+When you run `pnpm run sdk build`, scenarios are included in the output:
+
+- Scenario definitions are written to `seriousgaming.json` under the `scenarios` array
+- Scenario assets are copied to `dist/scenarios/<identifier>/assets/`
+
+## Best practices
+
+1. **Use scenarios for variant bundles, not minor tweaks.** If the difference is a single settings value, a setup screen is simpler.
+
+2. **Keep scenarios data-only.** Don't put logic in scenarios: use settings to drive conditional behaviour.
+
+3. **Organise assets by purpose.** Use `shared/` for locale-independent files. If you need locale-specific assets, use locale subdirectories (e.g. `en/`, `fr/`) and reference the appropriate path from a settings value.
+
+4. **Mark a default.** If your game has scenarios, mark one as `default: true` so facilitators don't have to remember the identifier.
+
+5. **Validate overrides against settings schemas.** Scenario settings values are validated against each named settings resource's `settingsSchema` during build. If a value doesn't match, the build will fail.
+
+## Custom scenarios (production runtimes)
+
+Games designed to be customised by end users (facilitators or customer organisations who save their own scenarios at session time and reuse them across sessions) opt in with one declaration on the game definition:
+
+```json
+{
+    "identifier": "com.example.cyber",
+    "customScenarios": { "supported": true }
+}
+```
+
+The field is a **production-policy signal**. A hosted runtime that recognises it keeps the scenarios facilitators save across sessions and offers them in the scenario picker beside the game's built-in ones. A saved scenario's overrides apply in the same layer as a built-in scenario's, between the settings defaults and the session overrides. When a scenario is copied, files it references with `asset:<path>` are copied into runtime storage, so the copy keeps working if the original changes; `shared:<path>` references are left as they are.
+
+How saved scenarios are named, scoped and edited is up to the runtime.
+
+Save-as-scenario is offered from the game's [`scenario_editor`](./scenario-editor.md) slot only, never from [`setup`](./setup.md). Setup is a separate, session-only configuration step: its output lands in the session-override layer and is never persisted as a scenario.
+
+The editor is optional. `customScenarios.supported` is what switches custom scenarios on, and a game whose settings schemas describe each value well (a title, a description with units, a range, an `enum` where the choices are closed) can be edited by an AI agent, or in a runtime's generic form, with no editor UI at all. See [Describe every setting](./settings.md#describe-every-setting).
+
+### Scenario format: when to bump it
+
+A custom scenario outlives the release it was saved against: a facilitator saves one today and runs it after your next update. Schema validation catches a setting that was renamed or removed, but not one whose meaning changed, so you tell the runtime with `scenarioFormat` in `seriousgaming.sdk.json`:
+
+```json
+{
+    "identifier": "com.example.cyber",
+    "customScenarios": { "supported": true },
+    "scenarioFormat": 2
+}
+```
+
+It is an integer of at least 1, and leaving it out means 1. A runtime stores the format and your package version with every custom scenario it saves, and refuses to apply a saved scenario whose format differs from your package's, naming both. A scenario saved under the same format is still validated against your current settings schemas each time it is applied.
+
+Bump it when a scenario saved against the previous release may no longer be correct:
+
+- A setting removed, renamed, or reshaped (an object split in two, a number that becomes an enum)
+- A change in what a value means (a percentage that becomes a fraction, a per-round amount that becomes a total)
+- A change in how the game loads scenario assets (a reference resolved from a different path)
+- A lock or a narrower range on a setting a saved scenario may already set: a new `readOnly` in a settings schema, or a new or tighter entry in `gameSettingsConstraints` (see [Lock a setting](./settings.md#lock-a-setting)). A lock is enforced when a value is written, so the format is what stops an older scenario that carries the value from applying
+
+Do not bump it for a purely additive change, such as a new setting with a default: an older scenario leaves the new setting at its default and still applies. Bumping when you did not need to costs facilitators their saved scenarios, so bump only for a change that would make an old scenario wrong.
+
+Package scenarios under `scenarios/` carry no format. They ship with the package, so they always match it, and the dev server's save writes none.
+
+The dev server is an author-time tool, not a runtime simulator, so it does not persist runtime-built scenarios. It has its own author-time save flow, described below.
+
+## Save as a scenario (dev server)
+
+The dev drawer's **Scenario** tab adds, edits, and deletes package scenarios (see [Managing scenarios while the server runs](#managing-scenarios-while-the-server-runs)). Each writes into the package on disk, which is the whole of the wiring, so a saved scenario behaves identically to one authored by hand.
+
+The scenario editor page's **Save** button writes the editor's draft into the scenario it was opened on, as a real `scenarios/<identifier>/scenario.sdk.json` bundle. Any `blob:*` references in that configuration are materialised as files under the scenario's `assets/shared/` and rewritten to `asset:*`, so the resulting bundle is self-contained and ready to check in. `shared:*` references are left intact, because they already point at the package-level `shared-assets/` directory. Only `settings` is replaced, the number of rounds and the team settings under `settings.game` among them: the scenario's locales, `default`, `restricted` and anything else in the bundle stay as they were. A setting the game locks with `readOnly` is left out of what is written, since the build refuses a scenario that names one, and a save whose settings break a schema, a locked value changed or a value out of range, is refused with nothing written.
+
+Typical edit flow:
+
+```bash
+pnpm run sdk dev --scenario baseline
+# open the dev drawer, then Scenario, then Edit on baseline
+# change values in the scenario editor, then click Save
+# scenarios/baseline/scenario.sdk.json is overwritten on disk
+```
+
+This is the author-time counterpart to runtime custom scenarios (above): the same primitive, with the reference translation running the opposite way.
+
+| Flow                                                              | Where the scenario lives            | Translation direction |
+| ----------------------------------------------------------------- | ----------------------------------- | --------------------- |
+| Runtime custom scenarios (`customScenarios: { supported: true }`) | Runtime blob store                  | `asset:*` → `blob:*`  |
+| Author-time package scenarios (SDK dev server)                    | `scenarios/<id>/` under the package | `blob:*` → `asset:*`  |
+
+Hosted runtimes do not surface this author-time save. Whether they offer their own save to facilitators is controlled by `customScenarios`, and the dev server offers its own regardless, because the author owns the package.
+
+## Next steps
+
+- [Shaping games](./games.md): set what the game is
+- [Building a scenario editor](./scenario-editor.md): the screen for authoring lasting scenarios
+- [Building a setup screen](./setup.md): the short form at session creation
+- [Internationalisation](./internationalization.md): multi-language support for scenario locales