Simulation scenario packages

Simulation worlds are configured by publishing a ZIP package from Build → Scenario in the World control panel. The package keeps the scenario YAML and all referenced drive documents together so the complete scenario is validated and published as one revision.

Package requirements

The ZIP must:

• be no larger than 8 MB and expand to no more than 16 MB;
• contain exactly one .yaml or .yml file;
• contain every file referenced by content.drive; and
• use a unique filename for every referenced document.

Documents can be in any folder in the ZIP. Biterra matches each one to the filename at the end of its YAML document_path and attaches it to the published scenario.

Use this logical path format when authoring:

document_path: simulations/<scenario-id>/documents/<filename>

For example, simulations/meridian-crisis/documents/response-plan.pdf must have exactly one response-plan.pdf in the ZIP.

Publishing a replacement package increments its revision. If teams already have progress, select Reset existing team progress before publishing an incompatible replacement. Resetting progress cannot be undone.

YAML structure

Every scenario starts with these fields:

schema_version: 1
id: example-scenario
title: Example Scenario
organisation: Example Mission
briefing: Your participant briefing.
start_node: opening

• schema_version is 1 or 2.
• id contains lowercase letters, numbers, and hyphens.
• start_node names the first entry in nodes.
• IDs are persistence keys. Do not rename a published node, choice, content item, person, channel, day, or news section while keeping the same schema version.

The main sections are:

Section	Purpose
apps	Enables, disables, orders, and renames desktop applications.
people	Defines reusable contacts for mail, chat, and calls.
content	Defines items released into desktop applications.
nodes	Defines decision points, unlocks, choices, effects, and outcomes.
injects	Defines timed or facilitator-released content in version 2.
roles	Defines role-specific views in version 2.

Applications and content

Supported app types are email, chat, browser, press-office, incident-desk, shared-drive, situation-map, phone, evidence, social-feed, news, and decisions.

apps:
  - { type: email, label: Executive Inbox, enabled: true }
  - { type: shared-drive, label: Crisis Drive, enabled: true }
  - { type: decisions, label: Decision Log, enabled: true }

people:
  - id: crisis-coordinator
    name: Amara Okafor
    role: Crisis coordinator
    avatar: woman
    voice: ops

content:
  inbox:
    - id: initial-brief
      title: Initial brief
      subject: Urgent briefing
      source: Amara Okafor
      person_id: crisis-coordinator
      body: The situation is developing.
  drive:
    - id: response-plan
      title: Crisis response plan
      body: Confirm facts before attribution.
      category: Playbooks
      version: "2.0"
      document_path: simulations/example-scenario/documents/response-plan.pdf
  calls:
    - id: coordinator-call
      person_id: crisis-coordinator
      subject: Ministerial briefing
      timestamp: "08:10"
      lines:
        - We need an agreed position before the ministerial call.

Content collections include inbox, chat, browser, press, tickets, drive, map, calls, evidence, and news. An item can use audience: debrief to stay hidden until the team reaches a terminal node. Items can also use visible_to in a version-2 role-based scenario.

Nodes and choices

Nodes form the scenario graph. Entering a node releases its unlock content. Every non-terminal choice must point to an existing next node.

nodes:
  - id: opening
    time: "08:00"
    title: Opening situation
    summary: A short situation summary.
    objective: Agree the first cross-agency action.
    unlock:
      inbox: [initial-brief]
      drive: [response-plan]
      calls: [coordinator-call]
    choices:
      - id: consult
        label: Request consultations
        action:
          kind: send_message
          app: email
          target: initial-brief
          response_template: >-
            Please convene protected consultations and circulate a shared factual brief.
        rationale_prompt: Explain why consultations are proportionate.
        next: consultation
        points: 2
        effects: { cooperation: 2 }

  - id: consultation
    time: "08:30"
    title: Consultation complete
    summary: Partners have agreed a shared factual position.
    objective: Review the outcome.
    terminal: true

Supported action kinds are send_message, publish_statement, update_incident, place_call, open_link, open_document, operational_action, and publish_post. The action app must support the selected kind.

Choices can also define submission_fields for required or optional text, textarea, and select values. Submitted values, rationale, activity, decisions, unlocks, points, and named effects are retained in the team's versioned scenario state.

Version 2 features

Schema version 2 adds:

• roles, default_role, and per-item visible_to rules;
• timed or facilitator-released injects;
• hypotheses and choice-level confidence revisions;
• node evaluation_criteria and choice submission metadata;
• outcome_rules based on cumulative signals and decision history; and
• debrief-only source_notes.

Version 1 remains supported. Use version 2 when the exercise needs these features rather than adding unsupported fields to a version-1 scenario.

Validation checklist

Before publishing, check that:

1. start_node and every choice next value name an existing node.
2. Every unlock names existing content in the matching collection.
3. Every action target exists and its kind belongs to the selected app.
4. Every drive path follows simulations/<scenario-id>/documents/<filename>.
5. Every referenced document is present exactly once in the ZIP.
6. Stable IDs have not been renamed for an in-progress scenario.

Biterra validates the complete package before publishing it. Invalid YAML, unsupported schema versions, broken references, unsafe document paths, and missing documents are rejected without replacing the published revision.