Briefing Docs

Quick start

Each scenario is a folder inside static/scenarios/. The folder name becomes the URL slug.

A scenario folder can contain up to three data files:

Just the scenario file?

With just scenario.json, the briefing page automatically generates:

The briefing.yaml lets you override any of these defaults and add educational context that doesn't exist in the game data.

But you can go further...

Every field is optional. Add only what you need. Edit the code below to see the preview update in real time, then use the copy button to grab the YAML for your briefing file.

author_url

Makes the author name in the navigation bar a clickable link.

situation

The prose shown under "The Situation" heading. Overrides the scenario's Description field. Supports bold (**text**) and italic (*text*) markdown. Use | for multi-line text.

gameplay_summary

A short paragraph shown below the scenario panel. Supports HTML for emphasis. If omitted, an auto-generated summary of rounds, actions and credits is shown.

play

Replaces the default Copy Scenario + Launch Player flow with a single button that links to a hosted version of the game. Useful when your scenario is already running on a public URL and players don't need to load it manually. The optional label overrides the button text (defaults to "Play Scenario").

info_card

A highlighted card with background context. Great for explaining a key concept. The optional image field references a file in the scenario folder.

actions_intro

Introductory text shown before the entity cards. Supports markdown. A sensible default is provided if omitted.

entity_descriptions

Descriptions shown on each entity card. Keys must match the entity ID from your scenario JSON exactly. Supports markdown. Without this, entity cards show with no description text.

Introduce These

Heavy Metal

Description of Heavy Metal and its role in the ecosystem.

Vetiver Grass

Description of Vetiver Grass and its role in the ecosystem.

1234567

entity_descriptions: HeavyMetal: | Description of Heavy Metal and its role in the ecosystem. VetiverGrass: | Description of Vetiver Grass and its role in the ecosystem.

Tip: Open your scenario.json and look at Scenario.Entities[].ID to find the exact IDs to use as keys.

objectives

Override the auto-generated objectives. If omitted, objectives are built from the scenario's WinConditions with their icons, thresholds and round requirements. Each objective can reference an entity (by ID) to inherit its icon, or specify a custom icon.

To Meet Objectives

Heavy Metal Population

Maintain a healthy population.

Keep Heavy Metal above 500 for 3 rounds

Financial Sustainability

Don't overspend on introductions.

Keep budget above 2,000 for 2 rounds

123456789

objectives: - title: Heavy Metal Population entity: HeavyMetal description: Maintain a healthy population. goal: Keep Heavy Metal above 500 for 3 rounds - title: Financial Sustainability icon: currency description: Don't overspend on introductions. goal: Keep budget above 2,000 for 2 rounds

watch_out

Highlighted warnings shown in the "Watch Out For" section. Each item can reference an entity (inherits icon and name), a custom icon, or both a custom icon and name.

Watch Out For

Heavy Metal

Watch out for Heavy Metal levels getting out of control.

Overspending

Spending too much too early can leave you short on funds later.

123456

watch_out: - entity: HeavyMetal description: Watch out for Heavy Metal levels getting out of control. - icon: currency name: Overspending description: Spending too much too early can leave you short on funds later.

why_this_matters

Educational context shown under "Why This Matters". This is where you connect the scenario to real-world science, ecology or current events. Supports markdown.

further_reading

A list of external links shown as cards under "Further Reading".

Full example

Here's a complete briefing.yaml showing all fields together. Remember, every field is optional — start with just entity_descriptions and add more as needed.

author_url: https://example.com/profile

situation: |
  A former copper mine has left behind **toxic tailings**
  that are contaminating the surrounding soil and waterways.

gameplay_summary: |
  You have <strong>12 rounds</strong> to rehabilitate
  the mine site while keeping your budget healthy.

play:
  url: https://example.com/play/copper-tailings
  label: Play on EcoKnow Live

info_card:
  title: What are "Mine Tailings"?
  body: |
    The toxic waste material left over after the
    valuable metals have been extracted.

actions_intro: |
  You can **introduce** species into zones or
  **harvest** them to manage populations.

entity_descriptions:
  VetiverGrass: |
    Vetiver grass tolerates heavy metals and
    stabilises soil to prevent erosion.
  Fish: |
    Fish help filter heavy metals from water.

objectives:
  - title: Healthy Waters
    entity: Fish
    description: Ensure fish populations recover.
    goal: Keep Fish above 400 for 3 rounds

watch_out:
  - entity: HeavyMetal
    description: The toxic run off you need to clean up.
  - icon: currency
    name: Overspending
    description: Don't spend too much too early.

why_this_matters: |
  This scenario is based on real environmental challenges
  faced by communities near mining operations.

further_reading:
  - title: Phytoremediation
    description: How plants remove pollutants from soil.
    url: https://en.wikipedia.org/wiki/Phytoremediation