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
For more info check out theoutcomeproject.com
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
- 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
- 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.
Let's showcase some of what we can do with the current version of
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 https://github.com/adamsky/endgame 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
directory. Inside the
modules directory there should be a
test_module with it's own
manifest and an
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
Now when you use the
show command it should print out the value of the
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
There is not much inside, only a few very basic declarations. On the top level
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
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.
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
run-until. There are also
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.