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
_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.
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:
@@ -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.
## Requirements
- **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
On Ubuntu or Debian:
On Debian-based distros:
```sh
# update and install the required packages
sudo apt update
sudo apt install -y git python3 python3-venv
```
@@ -47,21 +51,28 @@ sudo apt install -y git python3 python3-venv
Install Docker:
```sh
# Download docker
curl -fsSL https://get.docker.com | sudo sh
# Create docker usergroup
sudo usermod -aG docker "$USER"
newgrp docker
# Test if it can run without sudo
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
# Clone repo
git clone git.skillysue.nl/APWorldTester && cd APWorldTester
# Create environment
python3 -m venv .venv
source .venv/bin/activate
# Install APWorldTester
pip install -e .
```
@@ -73,30 +84,21 @@ 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.
That writes the template config to `~/.config/apworld-tester/config.yaml`.
Two settings that require changing:
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`
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
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:
```text
GITHUB_TOKEN=ghp_...
GITHUB_TOKEN=ghp_<your_token_here>
```
## Test worlds
Use `TestRun` to test one or more worlds:
The `TestRun` class can be used to test one or more worlds:
```python
from apworld_tester import TestRun
@@ -104,13 +106,13 @@ from apworld_tester import TestRun
TestRun("Baba Is You").run()
```
Multiple worlds:
To test multiple worlds, supply the names as a list:
```python
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
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.
## Test all worlds
`UpdateRun` updates Archipelago, refreshes the community worlds spreadsheet, downloads changed worlds, and tests everything:
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:
```python
from apworld_tester import UpdateRun
@@ -129,8 +130,7 @@ UpdateRun().run()
```
## Test a local `.apworld`
For a world you are developing, put the `.apworld` in its own directory:
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:
```text
~/my-apworlds/