3.7 KiB
Archipelago World Tester
This project checks whether community Archipelago worlds can generate a seed.
It reads the community worlds spreadsheet, downloads each world's newest .apworld file, and runs Archipelago's generator against it in a Docker container.
Each world is tested five ways:
- by itself
- with two players of the same game
- with 2–5 of Archipelago's built-in worlds
- by itself with its options randomized
- with other worlds and its options randomized
Each test is repeated with different seeds. The results are combined into one of six stability values:
| Value | Meaning |
|---|---|
| Stable | Every attempt succeeded |
| Minor issues | Solo and multiworld tests worked, but a randomized test failed |
| Flaky | Some attempts succeeded and others failed |
| Solo only | Works by itself, but fails with other worlds |
| Broken | Could not generate at all |
| Unknown | No usable result, for example because the .apworld was missing or a ROM was required |
A successful test means the world loaded, generated a seed, and computed the spoiler log at the configured level. With the default playthrough level, this also checks that the seed is completable.
Requirements
- Python 3.10 or newer
- Git — used to clone Archipelago and check out the version being tested
- Docker — must be usable by your user without
sudo - A GitHub token — required to access the GitHub API. It does not need any scopes
- Base ROMs — optional; some worlds cannot generate without them
Installation
System packages
On Ubuntu or Debian:
sudo apt update
sudo apt install -y git python3 python3-venv
Install Docker:
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
docker run --rm hello-world
The last command should work without sudo.
Install the package
git clone <repository-url> archipelago-world-tester
cd archipelago-world-tester
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
Configuration
Write a starter config and edit the paths in it:
apworld-tester init
That writes ~/.config/apworld-tester/config.yaml (or
$XDG_CONFIG_HOME/apworld-tester/config.yaml) and prints the path.
Set general.output_directory - everything a run generates lives there,
including the Archipelago checkout and the downloaded apworlds - and
general.roms_directory for the worlds that need a base ROM.
The config is looked for in this order, first hit wins:
$APWORLD_TESTER_CONFIG~/.config/apworld-tester/config.yamlconfig.yamlbeside a source checkout
apworld-tester config-path prints which one is in use, or lists
every location it tried.
Create .env with your GitHub token:
GITHUB_TOKEN=ghp_...
Test worlds
Use TestRun to test one or more worlds:
from apworld_tester import TestRun
TestRun("Baba Is You").run()
Multiple worlds:
TestRun(["Baba Is You", "Anodyne"]).run()
To test all worlds that have already been downloaded:
TestRun(cached=True).run()
The first run clones Archipelago and builds the Docker image, which can take several minutes.
Test all worlds
UpdateRun updates Archipelago, refreshes the community worlds spreadsheet, downloads changed worlds, and tests everything:
from apworld_tester import UpdateRun
UpdateRun().run()
Test a local .apworld
For a world you are developing, put the .apworld in its own directory:
~/my-apworlds/
└── My Game/
└── my_game.apworld
Then run:
from apworld_tester import TestRun
TestRun(
"My Game",
root_directory="/home/you/my-apworlds",
).run()