From 5932160f152dac3d9bead3545d39322807e269f6 Mon Sep 17 00:00:00 2001 From: Ixrec Date: Tue, 20 Jan 2026 19:14:43 +0000 Subject: [PATCH] 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 --- docs/adding games.md | 3 ++- docs/apworld_dev_faq.md | 43 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/adding games.md b/docs/adding games.md index 762a908fc8..7360ac2b7e 100644 --- a/docs/adding games.md +++ b/docs/adding games.md @@ -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 diff --git a/docs/apworld_dev_faq.md b/docs/apworld_dev_faq.md index 6e1c102c6a..17657a9f52 100644 --- a/docs/apworld_dev_faq.md +++ b/docs/apworld_dev_faq.md @@ -6,6 +6,49 @@ including [Contributing](contributing.md), [Adding Games](), 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](). + 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]() + 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](), and [World API](). + +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