Simulation scenario packages

Build a simulation in Build → Scenario in the World control panel. The scenario maker shows events and their choice routes on a canvas, arranged by day and role. Add score signals to choices, then use Build → Endings to write the ending text shown when those scores meet a rule. Write a default ending for paths that match no rule. Publish directly from the maker when the scenario does not add or replace drive documents. Use a ZIP package to publish YAML together with new or changed drive documents.

Scenario maker

1. Define the participant roles in Build → Roles. Each role can start at a different event; routes from different roles can later meet at the same event.
2. In Build → Scenario, choose Add event in a role or shared lane. Use Add another day to extend the timeline. Drag events between lanes or days to organise the canvas.
3. Select an event to edit its Details and Event content. Add choices to the event and drag each choice's connector to the event that follows it. A role's connector points to its starting event, not to a choice.
4. Select a choice to edit its Choice, optional Response fields, and Effects (score signals). Use Build → Endings for the default ending and any score-based ending rules.
5. Switch between Nodes and YAML to inspect or edit the source. Select Validate and publish. The maker validates the YAML structure before sending it; the server also checks graph, content, and document references. If participants already have progress and a reset is required, confirm the reset by typing RESET.

Download YAML saves the current draft for review or use in a ZIP. Day placement, role-lane placement, and event positions are saved in YAML as editor metadata; choice routes and role starting events control the exercise flow. Keep published IDs stable while participants have progress.

The maker can retain existing published document paths, but it cannot upload new document files by itself. Use Upload ZIP for those changes.

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, Biterra asks you to confirm a reset for incompatible changes. Resetting progress cannot be undone.

YAML structure

The current builder writes version 2 scenarios with these fields:

schema_version: 2
id: example-scenario
title: Example Scenario
organisation: Example Mission
briefing: Your participant briefing.
start_node: operations-brief
roles:
  - { id: operations, label: Operations, start_node: operations-brief }
  - { id: communications, label: Communications, start_node: communications-brief }
default_role: operations
desktop:
  days:
    - { id: day-1, label: Day 1 }
    - { id: day-2, label: Day 2 }

• schema_version is 1 or 2.
• id contains lowercase letters, numbers, and hyphens.
• start_node names the fallback starting event. In version 2, each role can set its own start_node; a role without one uses the fallback.
• Version 2 requires at least one role and a default_role matching a role ID.
• 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.
desktop.days	Defines the ordered days used by the scenario canvas.
nodes	Defines events, unlocks, choices, effects, and routes.
injects	Defines timed or facilitator-released content in version 2.
roles	Defines participant roles and their starting events in version 2.
ending, outcome_rules	Defines fallback and score-based completion text in version 2.

Roles, days, and canvas layout

A role starts at roles[].start_node, or at the scenario's start_node when that field is omitted. Two roles can start at different events and both reach the same later event through their choices. A role connector can only point to an event. content.*[].visible_to controls which roles can see a content item.

Each event belongs to a desktop.days[].id through its day field; omitted day defaults to day-1. The optional editor_lane (<role-id> or __shared__) and editor_position ({ x, y }) preserve how an event is arranged on the canvas. A shared lane is a visual placement, not an extra role or an access rule. Routing comes from role starts and choice next values, regardless of canvas placement.

The optional top-level desktop_background is an image URL for the participant desktop. It is separate from the World appearance setting named Simulation Desktop Background.

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.
    - id: communications-briefing
      title: Communications brief
      subject: Press enquiries
      source: Amara Okafor
      person_id: crisis-coordinator
      body: Please prepare a public update.
  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

Events are stored as nodes in YAML. Entering an event releases its unlock content. An event's email, message, post, or page is a content item referenced by that event's unlock; each new event can have its own item. Every choice must point to an existing next event. A terminal event has no choices.

nodes:
  - id: operations-brief
    time: "08:00"
    title: Operations briefing
    summary: The operations team receives its brief.
    objective: Agree the first cross-agency action.
    day: day-1
    editor_lane: operations
    editor_position: { x: 320, y: 180 }
    unlock:
      inbox: [initial-brief]
      drive: [response-plan]
      calls: [coordinator-call]
    choices:
      - id: operations-consult
        label: Request consultations
        next: joint-briefing
        points: 2
        effects: { cooperation: 2 }

  - id: communications-brief
    time: "08:05"
    title: Communications briefing
    summary: The communications team receives its own message.
    objective: Prepare a public update.
    day: day-1
    editor_lane: communications
    unlock:
      inbox: [communications-briefing]
    choices:
      - id: communications-consult
        label: Coordinate the update
        next: joint-briefing

  - id: joint-briefing
    time: "09:00"
    title: Joint briefing
    summary: Both teams have reached the same event.
    objective: Review the outcome together.
    day: day-2
    editor_lane: __shared__
    terminal: true

Older YAML can still contain choice action behavior. The visual builder preserves it and offers Remove old behavior, but new choices route directly to events without an app action. Supported legacy 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 optionally define submission_fields for text, textarea, and select values. Submitted values, 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;
• per-role start_node values, desktop.days, and event day, editor_lane, and editor_position metadata;
• timed or facilitator-released injects;
• legacy hypotheses and choice-level confidence revisions, which remain readable in YAML but are no longer edited in the visual builder;
• node evaluation_criteria and choice submission metadata;
• ending for the fallback completion text, and outcome_rules with their own title and text selected from cumulative signals and decision history; and
• debrief-only source_notes.

An ending is the completion text shown after the last event. Score rules select that text; they do not route the participant to another event. Older outcome_node references remain readable and are converted to ending text when opened in the visual builder.

ending:
  title: Exercise complete
  text: The teams completed the exercise.
outcome_rules:
  - id: coordinated-response
    priority: 10
    when:
      cooperation: { min: 2 }
    title: Coordinated response
    text: The teams agreed on a joint approach.

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. The scenario start_node, each role's optional start_node, and every choice next value name an existing event.
2. Each event's day names a defined day, and day IDs are unique.
3. Every unlock names existing content in the matching collection; each visible_to role ID exists.
4. Every legacy action target exists and its kind belongs to the selected app.
5. Score-based endings have a default ending, and each rule has a title and text.
6. Every drive path follows simulations/<scenario-id>/documents/<filename>.
7. Every referenced document is present exactly once in the ZIP.
8. 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.