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:

1. $APWORLD_TESTER_CONFIG
2. ~/.config/apworld-tester/config.yaml
3. config.yaml beside 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()