Skilly/APWorldTester
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Skilly
2026-09-06 16:47:06 +02:00
parent eba8c0eb8a
commit ccd3d8ebf3
1 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
README.md
View File

@@ -1,8 +1,9 @@
# Archipelago World Tester # Archipelago World Tester
_Disclaimer: AI was used in this project_
This project checks whether community Archipelago worlds can generate a seed. This project checks whether [community Archipelago worlds](https://docs.google.com/spreadsheets/d/1iuzDTOAvdoNe8Ne8i461qGNucg5OuEoF-Ikqs8aUQZw/edit?gid=58422002#gid=58422002) 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. It reads the community worlds spreadsheet, downloads each world's newest `.apworld` file, and runs Archipelago's generator against it in a Docker container.
To see the results of this live in action, see [worlds.archipelago.skillysue.nl](https://worlds.archipelago.skillysue.nl)
Each world is tested five ways: Each world is tested five ways:
@@ -25,6 +26,8 @@ Each test is repeated with different seeds. The results are combined into one of
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. 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 ## Requirements
- **Python 3.10 or newer** - **Python 3.10 or newer**
@@ -37,9 +40,10 @@ A successful test means the world loaded, generated a seed, and computed the spo
### System packages ### System packages
On Ubuntu or Debian: On Debian-based distros:
```sh ```sh
# update and install the required packages
sudo apt update sudo apt update
sudo apt install -y git python3 python3-venv sudo apt install -y git python3 python3-venv
``` ```
@@ -47,21 +51,28 @@ sudo apt install -y git python3 python3-venv
Install Docker: Install Docker:
```sh ```sh
# Download docker
curl -fsSL https://get.docker.com | sudo sh curl -fsSL https://get.docker.com | sudo sh
# Create docker usergroup
sudo usermod -aG docker "$USER" sudo usermod -aG docker "$USER"
newgrp docker newgrp docker
# Test if it can run without sudo
docker run --rm hello-world docker run --rm hello-world
``` ```
The last command should work without `sudo`.
### Install the package ### Install the package
```sh ```sh
git clone <repository-url> archipelago-world-tester # Clone repo
cd archipelago-world-tester git clone git.skillysue.nl/APWorldTester && cd APWorldTester
# Create environment
python3 -m venv .venv python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
# Install APWorldTester
pip install -e . pip install -e .
``` ```
@@ -73,30 +84,21 @@ Write a starter config and edit the paths in it:
apworld-tester init apworld-tester init
``` ```
That writes `~/.config/apworld-tester/config.yaml` (or That writes the template config to `~/.config/apworld-tester/config.yaml`.
`$XDG_CONFIG_HOME/apworld-tester/config.yaml`) and prints the path. Two settings that require changing:
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: - `general.output_directory` The output directory for running the tester, including cloning the Archipelago repo and downloaded apworlds.
- `general.roms_directory` Directory where base ROMs are located for apworlds that need one.
1. `$APWORLD_TESTER_CONFIG` ### GitHub
2. `~/.config/apworld-tester/config.yaml` The tester checks and downloads hundreds of apworlds from GitHub repositories. It is highly recommended to register a GitHub token and store it in an .env file as follows:
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 ```text
GITHUB_TOKEN=ghp_... GITHUB_TOKEN=ghp_<your_token_here>
``` ```
## Test worlds ## Test worlds
The `TestRun` class can be used to test one or more worlds:
Use `TestRun` to test one or more worlds:
```python ```python
from apworld_tester import TestRun from apworld_tester import TestRun
@@ -104,13 +106,13 @@ from apworld_tester import TestRun
TestRun("Baba Is You").run() TestRun("Baba Is You").run()
``` ```
Multiple worlds: To test multiple worlds, supply the names as a list:
```python ```python
TestRun(["Baba Is You", "Anodyne"]).run() TestRun(["Baba Is You", "Anodyne"]).run()
``` ```
To test all worlds that have already been downloaded: To test all worlds that have already been downloaded, add `cached=True`:
```python ```python
TestRun(cached=True).run() TestRun(cached=True).run()
@@ -119,8 +121,7 @@ TestRun(cached=True).run()
The first run clones Archipelago and builds the Docker image, which can take several minutes. The first run clones Archipelago and builds the Docker image, which can take several minutes.
## Test all worlds ## Test all worlds
The real benefit of the tester is to parse the community worlds spreadsheet and re-test all changed apworlds. The `UpdateRun` class does exactly this. It updates Archipelago if needed, refreshes the community worlds spreadsheet, downloads and tests changed worlds:
`UpdateRun` updates Archipelago, refreshes the community worlds spreadsheet, downloads changed worlds, and tests everything:
```python ```python
from apworld_tester import UpdateRun from apworld_tester import UpdateRun
@@ -129,8 +130,7 @@ UpdateRun().run()
``` ```
## Test a local `.apworld` ## Test a local `.apworld`
In case you want to test a world for which you have an apworld locally, you can supply a directory instead. First, put the `.apworld` in its own directory:
For a world you are developing, put the `.apworld` in its own directory:
```text ```text
~/my-apworlds/ ~/my-apworlds/