initial commit

README.md

@@ -1,3 +1,162 @@
-# APWorldTester
+# 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:
+
+```sh
+sudo apt update
+sudo apt install -y git python3 python3-venv
+```
+
+Install Docker:
+
+```sh
+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
+
+```sh
+git clone <repository-url> archipelago-world-tester
+cd archipelago-world-tester
+```
+
+Using `uv`:
+
+```sh
+uv sync
+```
+
+Or using `pip`:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Configuration
+
+Write a starter config and edit the paths in it:
+
+```bash
+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:
+
+```text
+GITHUB_TOKEN=ghp_...
+```
+
+## Test worlds
+
+Use `TestRun` to test one or more worlds:
+
+```python
+from apworld_tester import TestRun
+
+TestRun("Baba Is You").run()
+```
+
+Multiple worlds:
+
+```python
+TestRun(["Baba Is You", "Anodyne"]).run()
+```
+
+To test all worlds that have already been downloaded:
+
+```python
+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:
+
+```python
+from apworld_tester import UpdateRun
+
+UpdateRun().run()
+```
+
+## Test a local `.apworld`
+
+For a world you are developing, put the `.apworld` in its own directory:
+
+```text
+~/my-apworlds/
+└── My Game/
+    └── my_game.apworld
+```
+
+Then run:
+
+```python
+from apworld_tester import TestRun
+
+TestRun(
+    "My Game",
+    root_directory="/home/you/my-apworlds",
+).run()
+```
 
-Test Suite for Archipelago Worlds