Apex
This game allows you to manage a virtual environment containing entities that depend on each other as sources of energy. A food chain arises from the configuration of various entities and their specified diets.
Play in your browser
Apex also runs in a web browser, phones included, with nothing to install:
Click or tap the page once to start it, then tap "create new sim" and "start simulation", and
watch. Tapping the results screen returns to setup. The keyboard controls below work there too,
except that q ends the simulation (showing its results) instead of quitting, and there is no quit
button, as closing the tab ends the game. Nothing is reported to trace from the browser.
The browser build is made with pygbag from src/, whose
main.py is its entry point (python -m pygbag --build src builds it into src/build/web).
.github/workflows/browser.yml builds it on every pull request and deploys it. The sounds ship as
.ogg copies alongside the .wav files, because a browser build cannot play .wav.
Types of Living Entities
- Chicken
- Pig
- Cow
- Wolf
- Fox
- Rabbit
Each of these attempt to gain energy and reproduce. At the bottom of the food chain is Grass, which chickens, pigs, cows and rabbits are able to eat.
Berry bushes are a second food source. A bush that has accumulated enough energy periodically grows Berries on its own location, up to a cap. Chickens, pigs and rabbits eat berries; pigs can also eat the bush itself. Cows eat grass only.
Foxes hunt chickens, pigs and rabbits. Wolves hunt those three as well as cows and foxes.
Without grass, cows starve, and every other species depends on the berries the remaining bushes grow.
How does grass respawn?
Living entities spawn excrement when their energy needs are met and this turns into grass over time. The grow time, shared by all excrement in a simulation, is picked at random between 100 and 299 ticks, and excrement next to water turns into grass in half that time.
Controls
| Key | Action |
|---|
| space / escape | pause/unpause |
| m | mute/unmute |
| h | highlight oldest living entity |
| e | toggle entity eyes |
| v | toggle view (global/local) |
| up | increase view distance (in local view) |
| down | decrease view distance (in local view) |
| d | debug mode |
| c | spawn a chicken |
| p | spawn a pig |
| k | spawn a cow |
| w | spawn a wolf |
| f | spawn a fox |
| b | spawn a rabbit |
| l | toggle tick speed limit |
| ] | increase tick speed (if enabled) |
| [ | decrease tick speed (if enabled) |
| f11 | toggle fullscreen mode |
| r | restart |
| q | quit (in the browser: end the simulation and show its results) |
Text mode
--text runs the simulation in a terminal instead of a pygame window, no window or sound needed:
python3 src/apex.py --text
The grid is drawn one character per location, showing the entity on top as the window does:
C chicken, P pig, K cow, W wolf, F fox, R rabbit, " grass, & berry bush, * berries,
~ water, # rock, x excrement and . bare ground. Below it are the tick count, the population of
each species, the latest event (a death or a birth) and the legend. Colour is used where the terminal
supports it, and the letters alone are enough where it does not. A terminal too small for the grid
shows as much of it as fits.
| Key | Action |
|---|
| space / escape | pause/unpause |
| c / p / k / w / f / b | spawn a chicken / pig / cow / wolf / fox / rabbit |
| ] / [ | increase / decrease tick speed |
| l | toggle tick speed limit |
| r | start a new simulation |
| q | quit (the environment summary is printed once the terminal is restored) |
When every living entity has died the simulation stops and waits for r or q. Text mode needs
Python's curses module, which Linux and macOS include; on Windows, pip install windows-curses
first. --record is not available in text mode, and the browser build is unaffected.
Recording a replay
--record <path.usda> records the first simulation's history as a time-sampled
OpenUSD stage, one time code per tick (30 per second), that can be scrubbed in
usdview, Blender or any USD tool. It needs the optional
usd-recorder package (Python 3.10 or newer;
it brings in usd-core), which the game does not otherwise need:
pip install -r requirements-record.txt
python3 src/apex.py --record run.usda
Start a simulation as usual; the file is written when that simulation ends (or when you restart or
quit), and later simulations are not recorded. Every entity is recorded at (x, y, layer), where
layer is its place in its location's stack (the top one is what the game draws), in the game's
colour, with its kind (Grass, Chicken, Wolf, ...) and, for living entities, its energy;
the stage carries the livingEntities, grass and excrement counts per tick. Without --record
nothing is recorded or imported, and the browser build is unaffected.
The replay above is a 600-tick simulation on a 16×16 grid (6,407 entities over the run, a 10 MB
stage), recorded headlessly by stepping Simulation and UsdRecording tick by tick the way the
simulation screen does, then rendered top-down with headless Blender's USD importer and Cycles in
the recorded colours.
Usage reporting
Usage reporting is on by default: Apex sends its name (apex), the version from version.txt and the events startup (when the game starts) and simulation-started (when a simulation begins) to trace at https://trace.danielstephenson.dev. Each event also carries a random installation ID (the tag install) so installations can be counted rather than events; beyond that, nothing about you, your machine, your IP address or the simulation's contents is sent. The reporting happens on a background thread, never blocks the game, and is dropped silently if the service is unreachable.
The first run creates a settings.json next to version.txt and prints a one-line notice.
The installation ID is a random UUID kept in trace-install-id under the user data directory: ~/.local/share/apex/ on Linux (or $XDG_DATA_HOME/apex/), ~/Library/Application Support/apex/ on macOS and %APPDATA%\apex\ on Windows. It identifies no person, account or address; delete the file to get a new one. Setting the environment variable TRACE_INSTALL_ID sends that value instead and leaves the file alone. The file is only created while reporting is on, so every opt-out below also stops it. The browser build never reports, so it has no ID.
To turn reporting off, any one of these is enough:
-
"usage_reporting": {"enabled": false} in settings.json:
{
"usage_reporting": {
"enabled": false
}
}
-
the environment variable TRACE_USAGE_REPORTING=off (also false, 0, no), which turns off every program that reports to trace
-
the environment variable DO_NOT_TRACK=1 (see consoledonottrack.com)
The environment variables win over settings.json. The usage_reporting.endpoint and usage_reporting.key entries in the same block select where reports go and the key they are sent with.
Details: https://danielstephenson.dev/usage-reporting
Research
See RESEARCH.md for the ecological and artificial-life research this simulator's mechanics are grounded in, and how to use it when designing new features.
Support
You can find the support discord server here.
Authors and acknowledgement
Developers
| Name | Main Contributions |
|---|
| Daniel Stephenson | Creator |
Inspiration
This project is based on Kreatures and Interakt.
Libraries
This project makes use of graphik and py_env_lib.
Screenshots
Sounds
📄 License
This project is licensed under the Preponderous Non-Commercial License (Preponderous-NC).
It is free to use, modify, and self-host for non-commercial purposes, but commercial use requires a separate license.
Disclaimer: Preponderous Software is not a legal entity.
All rights to works published under this license are reserved by the copyright holder, Daniel McCoy Stephenson.
Full license text:
https://github.com/Preponderous-Software/preponderous-nc-license/blob/main/LICENSE.md
