Docs: add dev FAQ for 'should I start with the APWorld or the client?' (#5716)

* Docs: add dev FAQ for 'should I start with the APWorld or the client?'

* fix indentation of bullet point wrapped lines

* use %20 for spaces in links

* link to adding games.md and add #ap-modding-help to adding games.md

* make APQuest a link

* also linkify 'run a local server'

* reword the 'judging client is easier' point to reflect a broader range of first-timers

* move the 'not 100%' point into the introductory sentences, and tweak related wording

* correct link
This commit is contained in:
Ixrec
2026-01-20 19:14:43 +00:00
committed by GitHub
parent 76e0619b79
commit 5932160f15
2 changed files with 45 additions and 1 deletions

View File

@@ -17,7 +17,8 @@ it will not be detailed here.
The client is an intermediary program between the game and the Archipelago server. This can either be a direct
modification to the game, an external program, or both. This can be implemented in nearly any modern language, but it
must fulfill a few requirements in order to function as expected. Libraries for most modern languages and the spec for
various packets can be found in the [network protocol](/docs/network%20protocol.md) API reference document.
various packets can be found in the [network protocol](/docs/network%20protocol.md) API reference document. Additional help with specific game
engines and rom formats can be found in the #ap-modding-help channel in the [Discord](https://archipelago.gg/discord).
### Hard Requirements

View File

@@ -6,6 +6,49 @@ including [Contributing](contributing.md), [Adding Games](<adding games.md>), an
---
### I've never added a game to Archipelago before. Should I start with the APWorld or the game client?
Strictly speaking, this is a false dichotomy: we do *not* recommend doing 100% of client work before the APWorld,
or 100% of APWorld work before the client. It's important to iterate on both parts and test them together.
However, the early iterations tend to be very similar for most games,
so the typical recommendation for first-time AP developers is:
- Start with a proof-of-concept for [the game client](adding%20games.md#client)
- Figure out how to interface with the game. Whether that means "modding" the game, or patching a ROM file,
or developing a separate client program that edits the game's memory, or some other technique.
- Figure out how to give items and detect locations in the actual game. Not every item and location,
just one of each major type (e.g. opening a chest vs completing a sidequest) to prove all the items and locations
you want can actually be implemented.
- Figure out how to make a websocket connection to an AP server, possibly using a client library (see [Network Protocol](<network%20protocol.md>).
To make absolutely sure this part works, you may want to test the connection by generating a multiworld
with a different game, then making your client temporarily pretend to be that other game.
- Next, make a "trivial" APWorld, i.e. an APWorld that always generates the same items and locations
- If you've never done this before, likely the fastest approach is to copy-paste [APQuest](<../worlds/apquest>), and read the many
comments in there until you understand how to edit the items and locations.
- Then you can do your first "end-to-end test": generate a multiworld using your APWorld, [run a local server](<running%20from%20source.md>)
to host it, connect to that local server from your game client, actually check a location in the game,
and finally make sure the client successfully sent that location check to the AP server
as well as received an item from it.
That's about where general recommendations end. What you should do next will depend entirely on your game
(e.g. implement more items, write down logic rules, add client features, prototype a tracker, etc).
If you're not sure, then this would be a good time to re-read [Adding Games](<adding%20games.md>), and [World API](<world%20api.md>).
There are a few assumptions in this recommendation worth stating explicitly, namely:
- If something you want to do is infeasible, you want to find out that it's infeasible as soon as possible, before
you write a bunch of code assuming it could be done. That's why we recommend starting with the game client.
- Getting an APWorld to generate whatever items/locations you want is always feasible, since items/locations are
little more than id numbers and name strings during generation.
- You generally want to get to an "end-to-end playable" prototype quickly. On top of all the technical challenges these
docs describe, it's also important to check that a randomizer is *fun to play*, and figure out what features would be
essential for a public release.
- A first-time world developer may or may not be deeply familiar with Archipelago, but they're almost certainly familiar
with the game they want to randomize. So judging whether your game client is working correctly might be significantly
easier than judging if your APWorld is working.
---
### My game has a restrictive start that leads to fill errors
A "restrictive start" here means having a combination of very few sphere 1 locations and potentially requiring more