Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
197 lines (151 sloc) 7.72 KB


Command line program for creating, running and analyzing outcome simulations.

endgame is part of the effort to create an accessible playground for testing future scenarios and ideas for human civilization development.

For most of the work related to creating and processing simulations it uses the outcome-sim library.

For more info check out

This is a work in progress. To learn about what features are already implemented and what you can try with the latest release check out the mini tutorial near the end of this readme.

It’s a toolkit

endgame is a set of tools that help you create, test, run and analyse outcome simulations.

Content creation and management

  • initialize new modules, scenarios and proofs with commented noob-friendly templates
  • lint existing content and report errors
  • test load simulations from scenarios or snapshots to report information like source statistics (e.g. number of elements), predicted memory usage and simulation speed, etc
  • download dependencies

Simulation running

  • run simulations in either interactive or auto mode, using scenarios, snapshots or proofs as input
  • server mode can make endgame into a remote simulation runner, taking commands and sending data over http
  • cluster mode acts like a server, but in the background splits the workload between many machines

Data analysis

  • read data from snapshots
  • plot data from snapshots onto graphs

It's easy to use

endgame is meant to be easy to use out of the box. It's distributed as single-file executable, without the need for any additional dependencies.

That said, we recognize that command line interfaces are not for anyone. That's why there's a graphical user interface version available as well. Check out endgame-gui.

It’s open and free

endgame is free software. It's meant to allow anyone to work with outcome simulations, whether it's creating content, running simulations or analysing the data.

Mini Tutorial

Let's showcase some of what we can do with the current version of endgame.

Download and run

First you need to get endgame. You can either build from source or run a binary provided with the latest release.

If there's a binary provided that matches your system architecture then great. If not you will need to build from source.

Don't worry though, building from source is not that hard with Rust. First you need to install rust, and then use cargo to build the project.

git clone
cd endgame
cargo run

cargo run builds and runs the application for you. You can also run it with --release flag, which will apply optimizations during compilation, making the program itself faster, but the compilation process will take longer.

Initialize a new scenario

Let's create a new scenario based on a "tutorial" template. It will be very basic, but will get us started.

./endgame init scenario test_scenario -t tutorial

The above command will create a new directory named test_scenario. That's our newly created scenario. Inside you will find scenario.yaml manifest and a modules directory. Inside the modules directory there should be a test_module with it's own manifest and an examples.yaml file.

Interactive runner

Most important feature available in 0.1.1 is the interactive simulation runner.

./endgame run scenario <path-to-scenario>

--interactive option is the default here, so this will start an interactive session. Notice that we have to specify a scenario subcommand. This is because in the future there will be more possibilities for inputs for the run command, such as snapshots and proofs. Right now we can only use scenarios.

You should be greeted with a few lines looking similar to this:

Running interactive session using scenario at: ".../endgame/test_scenario"
[INFO] generating sim instance from scenario at: .../endgame/test_scenario/
[INFO] there are 1 mods listed in the scenario manifest
[INFO] mod found: "test_module" version: "0.1.0" (version specifier in scenario manifest: "^0.1.0")
[INFO] found all mods listed in the scenario manifest (1)
[INFO] successfully created sim_instance
You're now in interactive mode.
See possible commands with "help". Exit using "quit" or ctrl-d.

Config file interactive.yaml doesn't exist, loading default config settings
[1-1-2018 1:00]

The interactive mode enables you to interact with the simulation as it's being run. There are a few different commands that enable you to do a bunch of different things. Run help to see all available commands. You can use TAB key to navigate through the commands more easily too (autocomplete). Try just typing "h" and then press TAB twice, it should show you possible commands beginning with "h".

Simply pressing enter with no input ("empty command") progresses the simulation by one turn. A turn is a number of base simulation ticks, you can set the number of ticks per turn using the configuration (cfg) variable ticks_per_turn. By default it's set to 2. Let's change this and make one turn do 24 ticks:

cfg ticks_per_turn 2

Preview the list of currently set cfg variables with:

ticks_per_turn          2
show_on                 true
show_list               []

Now when we process one turn the prompt should change by 2 hours at a time.

For now there are only 3 cfg variables available to us, as seen above. show command shows takes data from the simulation and shows it to us. It uses the show_list cfg variable as input - it's a list of addresses that can be used to pull data from the simulation. Let's add an address to the show_list.

show-add /region/e01001/generic/test_element/string/string_var

Now when you use the show command it should print out the value of the string_var from the address.

Of course the address has to point to a variable that exists in the simulation.

Let's open the module file that declares the objects that we just referenced in the above address - the examples.yaml file inside the test_module.

There is not much inside, only a few very basic declarations. On the top level we have entity_types, entities and elements. Let's look at elements for now, or rather the only element there is, which is test_element. See how it has the trigger_tick set to "day". This means it will only execute on a day tick, which occurs every 24 hour ticks. So to see any changes to the string/string_var we will have to wait at least 24 hour ticks.

Let's get back into endgame's interactive mode and fast-forward the simulation to some future state, let's say one year. We can use run-until to do just that.

run-until 1-1-2019

This will calculate the number of ticks from the current date until the target date and run until it's there.

There's also a simpler run command that takes in a number of base hour ticks and executes exactly that number. You can use CTRL-D (EOF) or CTRL-C to break out of run and run-until. There are also runf and runf-until which can be faster (because they're not listening for signals while running) but don't allow for breaking out of the execution.

You can export the current configuration to file with


Adding and modifying the variables from the command line can be tiresome, you can edit the cfg file itself (interactive.yaml) and then just use:


to load it into the currently running interactive session. Every time an interactive session is started it will look for this file in the current working directory and automatically load it if it exists.