From 11d18db4520910bf62a789328f437dcc702094d4 Mon Sep 17 00:00:00 2001 From: NewSoupVi <57900059+NewSoupVi@users.noreply.github.com> Date: Sun, 19 Oct 2025 09:05:34 +0200 Subject: [PATCH] Docs: APWorld documentation, make a distinction between APWorld and .apworld (#5509) * APWorld docs: Make a distinction between APWorld and .apworld * Update apworld specification.md * Update apworld specification.md * Be more anal about the launcher component * Update apworld specification.md * Update apworld specification.md --- docs/apworld specification.md | 44 +++++++++++++++++------------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/apworld specification.md b/docs/apworld specification.md index be0e9cc1..7022e0ac 100644 --- a/docs/apworld specification.md +++ b/docs/apworld specification.md @@ -1,49 +1,49 @@ -# apworld Specification +# APWorld Specification Archipelago depends on worlds to provide game-specific details like items, locations and output generation. -Those are located in the `worlds/` folder (source) or `/lib/worlds/` (when installed). +These are called "APWorlds". +They are located in the `worlds/` folder (source) or `/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 provides a way to package and ship a world that is not part of the main distribution by placing a `*.apworld` -file into the worlds folder. +## .apworld File Format -**Warning:** apworlds have to be all lower case, otherwise they raise a bogus Exception when trying to import in frozen python 3.10+! +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. - -## File Format - -apworld files are zip archives, all lower case, with the file ending `.apworld`. +`.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 inside the zip archive. -The current format version has at minimum: +Metadata about the APWorld is defined in an `archipelago.json` file. + +If the APWorld is a folder, the only required field is "game": ```json { - "version": 7, - "compatible_version": 7, - "game": "Game Name" + "game": "Game Name" } ``` -The `version` and `compatible_version` fields refer to Archipelago's internal file packaging scheme -and 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. -On the other hand, the `game` field should be present in the world folder's manifest file before packaging. - 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. + 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, to eventually be displayed in various user-facing places such as WebHost and package managers. 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. + ### "Build apworlds" Launcher Component In the Archipelago Launcher, there is a "Build apworlds" component that will package all world folders to `.apworld`, @@ -86,7 +86,7 @@ The zip can contain arbitrary files in addition what was specified above. ## Caveats -Imports from other files inside the apworld have to use relative imports. e.g. `from .options import MyGameOptions` +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`