mirror of
https://github.com/ArchipelagoMW/Archipelago.git
synced 2026-07-17 22:10:43 -07:00
Patrick Wehbe
131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# APWorld Specification
|
|
|
|
Archipelago depends on worlds to provide game-specific details like items, locations and output generation.
|
|
These are called "APWorlds".
|
|
They are located in the `worlds/` folder (source) or `<install dir>/lib/worlds/` (when installed).
|
|
See [world api.md](world%20api.md) for details.
|
|
APWorlds can either be a folder, or they can be packaged as an .apworld file.
|
|
|
|
## .apworld File Format
|
|
|
|
The `.apworld` file format provides a way to package and ship an APWorld that is not part of the main distribution
|
|
by placing a `*.apworld` file into the worlds folder.
|
|
|
|
`.apworld` files are zip archives, all lower case, with the file ending `.apworld`.
|
|
The zip has to contain a folder with the same name as the zip, case-sensitive, that contains what would normally be in
|
|
the world's folder in `worlds/`. I.e. `worlds/ror2.apworld` containing `ror2/__init__.py`.
|
|
|
|
**Warning:** `.apworld` files have to be all lower case,
|
|
otherwise they raise a bogus Exception when trying to import in frozen python 3.10+!
|
|
|
|
## Metadata
|
|
|
|
Metadata about the APWorld is defined in an `archipelago.json` file.
|
|
|
|
If the APWorld is a folder, the only required field is "game":
|
|
```json
|
|
{
|
|
"game": "Game Name"
|
|
}
|
|
```
|
|
|
|
There are also the following optional fields:
|
|
* `minimum_ap_version` and `maximum_ap_version` - which if present will each be compared against the current
|
|
Archipelago version respectively to filter those files from being loaded.
|
|
* `world_version` - an arbitrary version for that world in order to only load the newest valid world.
|
|
An APWorld without a world_version is always treated as older than one with a version
|
|
(**Must** use exactly the format `"major.minor.build"`, e.g. `1.0.0`)
|
|
* `authors` - a list of authors of the world. Displayed in user-facing places like the Supported Games page
|
|
on WebHost. Should always be a list of strings.
|
|
|
|
If the APWorld is packaged as an `.apworld` zip file, it also needs to have `version` and `compatible_version`,
|
|
which refer to the version of the APContainer packaging scheme defined in [Files.py](../worlds/Files.py).
|
|
These get automatically added to the `archipelago.json` of an .apworld if it is packaged using the
|
|
["Build APWorlds" launcher component](#build-apworlds-launcher-component),
|
|
which is the correct way to package your `.apworld` as a world developer. Do not write these fields yourself.
|
|
|
|
### Choosing `minimum_ap_version` and `maximum_ap_version`
|
|
|
|
Both fields are optional, and most worlds only ever need `minimum_ap_version`.
|
|
|
|
* **`minimum_ap_version`** - the most cost-effective approach is to set it to the latest stable Archipelago
|
|
version when you first create your world, then only raise it when you deliberately start using a new core
|
|
feature that requires a newer version. When you want such a feature you can choose to either bump
|
|
`minimum_ap_version`, write code that supports both the old and new core conditionally (for example a
|
|
`try`/`except` around a moved import), or decide the feature is not worth it and leave it alone. There is
|
|
usually no need to determine your world's "true" minimum version, since most players run the latest release
|
|
or close to it.
|
|
* **`maximum_ap_version`** - rarely needed. Only set it when you already know a particular Archipelago version
|
|
breaks your world and you cannot quickly fix it or handle the difference conditionally. Most incompatibilities
|
|
are better resolved by updating the world instead. The main legitimate use case is a world or tool that is
|
|
tightly coupled to core's generation behavior, where supporting both sides of a breaking change in a single
|
|
release is not feasible.
|
|
|
|
When present, both fields use the same `"major.minor.build"` string format as the Archipelago version itself,
|
|
for example `"0.6.4"`.
|
|
|
|
### "Build APWorlds" Launcher Component
|
|
|
|
In the Archipelago Launcher (on [source only](/docs/running%20from%20source.md)), there is a "Build APWorlds"
|
|
component that will package all world folders to `.apworld`, and add `archipelago.json` manifest files to them.
|
|
These .apworld files will be output to `build/apworlds` (relative to the Archipelago root directory).
|
|
The `archipelago.json` file in each .apworld will automatically include the appropriate
|
|
`version` and `compatible_version`.
|
|
The component can also be called from the command line to allow for specifying a certain list of worlds to build.
|
|
For example, running `Launcher.py "Build APWorlds" -- "Game Name"` will build only the game called `Game Name`.
|
|
|
|
If a world folder has an `archipelago.json` in its root, any fields it contains will be carried over.
|
|
So, a world folder with an `archipelago.json` that looks like this:
|
|
|
|
```json
|
|
{
|
|
"game": "Game Name",
|
|
"minimum_ap_version": "0.6.4",
|
|
"world_version": "2.1.4",
|
|
"authors": ["NewSoupVi"]
|
|
}
|
|
```
|
|
|
|
will be packaged into an `.apworld` with a manifest file inside of it that looks like this:
|
|
|
|
```json
|
|
{
|
|
"minimum_ap_version": "0.6.4",
|
|
"world_version": "2.1.4",
|
|
"authors": ["NewSoupVi"],
|
|
"version": 7,
|
|
"compatible_version": 7,
|
|
"game": "Game Name"
|
|
}
|
|
```
|
|
|
|
This is the recommended workflow for packaging your world to an `.apworld`.
|
|
|
|
### .apignore Exclusions
|
|
|
|
By default, any additional files inside of the world folder will be packaged into the resulting `.apworld` archive and
|
|
can then be read by the world. However, if there are any other files that aren't needed in the resulting `.apworld`, you
|
|
can automatically prevent the build component from including them by specifying them in a file called `.apignore` inside
|
|
the root of the world folder.
|
|
|
|
The `.apignore` file selects files in the same way as the `.gitignore` format with patterns separated by line describing
|
|
which files to ignore. For example, an `.apignore` like this:
|
|
|
|
```gitignore
|
|
*.iso
|
|
scripts/
|
|
!scripts/needed.py
|
|
```
|
|
|
|
would ignore any `.iso` files and anything in the scripts folder except for `scripts/needed.py`.
|
|
|
|
Some exclusions are made by default for all worlds such as `__pycache__` folders. These are listed in the
|
|
`GLOBAL.apignore` file inside of the `data` directory.
|
|
|
|
## Caveats
|
|
|
|
Imports from other files inside the APWorld have to use relative imports. e.g. `from .options import MyGameOptions`
|
|
|
|
Imports from AP base have to use absolute imports, e.g. `from Options import Toggle` or
|
|
`from worlds.AutoWorld import World`
|