scenarios

Scenario Authoring Guide

A scenario is a description of a starting world, robots, and entities, along with (optionally) specific winning conditions and description text. All the various game modes in Swarm (classic mode, creative mode, tutorial, challenges, etc.) are described via scenarios. Scenarios are stored in human-friendly .yaml files, so it is very easy---and encouraged!---for you to create your own scenarios representing puzzles, challenges, works of art, or whatever you want. This page formally documents the .yaml format and also provides some tips for authoring your own scenarios.

If you're impatient to get started, note that a much quicker route is to look at the scenario files stored in data/scenarios of the swarm repository, copy one, and make whatever changes you want, using the other files as examples.

If you notice any errors or have any questions or suggestions, feel free to join the #swarm channel on Libera.Chat, or open a pull request!

Loading scenarios

The "blessed" scenarios that come with Swarm are stored in data/scenarios and can be accessed via the "New game" menu. However, other scenarios can be loaded directly from a file: simply run swarm with the --scenario flag (-i for short) and point it to a specific .yaml file containing a scenario. For example:

swarm --scenario myscenarios/fun.yaml

Examples

Many examples can be found in https://github.com/swarm-game/swarm/tree/main/data/scenarios .

The scenario file format

Scenarios are stored in YAML files. If you want to learn about YAML, see the link above; this is not a YAML tutorial. However, Swarm tends to use a fairly simple subset of YAML, and should be easy to pick up even if you have never seen YAML before. Swarm uses the Haskell yaml library for parsing .yaml files.

Scenario schema

To ease writing Scenario YAML files, you can use a JSON schema that includes the information below in a machine readable format. This will allow your editor to highlight the errors as you are writing.

VS Code

If you are using Visual Studio Code or VSCodium, you need to have the YAML extension installed. The appropriate settings.json is already configured for you in the cloned swarm repo.

CLI

You can also check the files from the command line:

# install latest check-jsonschema executable version
pip install check-jsonschema
# try it on provided scenarios
scripts/validate/json-schemas.sh

YAML schema

See the autogenerated SCHEMA.md.