Archipelago

An Archipelago plugin for GTFO! Allows players to use the Archipelago software to randomize items across the multiworld.

The source for this mod can currently be found in my ReTFO repository, which contains all my GTFO mods: https://github.com/RoboRyGuy/ReTFO

The AP World source (and releases) can be found in a different repository: https://github.com/RoboRyGuy/Archipelago-GTFO

Issues and feedback can be submitted on the APWorld GitHub's issues page: https://github.com/RoboRyGuy/Archipelago-GTFO/issues

Getting Started

Multiplayer Support

As of version 0.0.4, there is now official support for multiplayer. Multiplayer aims to support 3 different models:

• Parallel Play: Two or more players each play their own copy of GTFO. Both connect to the Archipelago server and are able to send/receive items and checks, but they are not in the same lobby.
• Multi-Connected: One player connects to the Archipelago server and hosts a GTFO lobby. One or more clients connect to the Archipelago server and join the lobby. All connected players use the same slot - ie, the GTFO game as a whole is considered one player as far as the Archipelago server is concerned.
• Proxy-Connected: One player connects to Archipelago and hosts a GTFO lobby. One or more clients then connect to only the GTFO lobby. These players are automatically connected to the Archipelago server using the Host as a proxy; they are able to send and receive checks normally, but have no ability to execute commands or request hints.

These three models can be mixed and matched as needed. Multi-Connected is preferred over Proxy-Connected; it will be more stable and act more predictably. Moreso, it will support host migration and other behaviours that require other players who can act as the host.

To use multiplayer, first have everyone who can put in their server details and press the purple "Connect to Archipelago" button. Then, have one person host a lobby and have everyone else connect using a lobby code. Connecting via code appears to be more stable than via a steam invite.

Standard Setup

Here are the steps required to get started with a vanilla world:

1. Create a new profile in your preferred mod client. Include Archipelago and its dependencies in your mod list.
   • I recommend using R2modman for modding GTFO.
   • If you wish to play with any other mods, install them now and see the Modded Support section for details below.
2. Download and add the APWorld file to your Archipelago installation.
3. Using your preferred method, create a YAML options file. Help for this can be found below in the YAML section.
4. Generate and host your multiworld.
5. Start GTFO using the modded profile you created and enter the Network Settings menu from the start menu.
6. Set your server details as needed.
7. Return to the main menu (using the Rundown button at the top) and connect!

Known Issues

• There are still a handful of logic errors in the game which are known but not fixed at this time.
  • Specific expeditions, such as R8B2 and R7D1, have unique features which are not currently supported.
  • Some other expeditions, such as R8D2, have unintuitive checks - in R8D2, the dual scan at the end has two different checks depending on what order you complete the scans in.
  • If you find logic errors, I'd appreciate if you report them on the GitHub issues page for the AP World: https://github.com/RoboRyGuy/Archipelago-GTFO/issues
• There is no difficulty balancing at this time, nor is any difficulty balancing planned - GTFO is intentionally a hard game, it is left up to players to determine what risks they're willing to take.
  • Some liberties have been taken to reduce the amount of "replay" required, such as the ability to skip reactor waves under certain conditions. This should not be seen as difficulty balancing, even if it can make expeditions easier.
• Certain objectives, such as "survival" objectives (R5B4, R8E1, etc), are prone to being much harder than in vanilla due to them introducing checks which are technically possible to get, even if not practically feasible.
• Certain new softlocks are possible; for example, you can accidentally bring necessary items (ie cells) to another dimension and leave them there, which is generally impossible in vanilla. These simply force you to restart the expedition.

YAML Help

GTFO uses a tagging system for all its Regions, Locations (Checks), and Items. You do not need to know or use the tagging system to set up Archipelago; you can learn/use it to perform fine-grained customization.

More information on tagging. This is optional to read, intended for advanced users.

Each Region, Location, and Item is assigned a unique tag, identifiable by name (and ID, though IDs are not used in the YAML). Each tag can have any number of parent tags (which in turn can have their own parent tags). When working with options that support tags, you can instead specify a parent tag to target all children of that tag.

Tags can be exported from the settings same menu as MID data; they can be exported in either JSON or CSV format, whichever you prefer for your data-intense reading pleasure.

Options supporting tags are most commonly found in the GTFO Item & Location Options category. Note that this category is "Advanced", as it has the most direct control over how GTFO behaves. Internally, most other options simply modify options in this group.

A few notes and examples about/using tags:

• The "Enabled Expeditions" option simply copies the tags you pick to the Region Whitelist. Besides the fact it supports randomization, it is identical to simply putting the list of expeditions in the Region Whitelist.
• Most regions are organized as such: Expedition > Layer > Zone > Terminal
  • A layer is a dimension or sector, ie "(Main)" or "(Dim #1)"
• Many settings, ie "Scan Randomization", allow you to pick whitelist, blacklist, or none. These simply put the relevant tag into the relevant white or blacklist for you.
• The "Progression Style" option works by intelligently moving specific tags into specific lists. For example, for the "FREE" progression style, it does the following:
  • Add the tag "Floating Expedition Unlock Items" to Start Vouchers with a count of -1 (match all)
  • Add the tag "Floating Expedition Unlock Items" to the Item Whitelist
  • Add the tag "Floating Expedition Paths" to the Region Whitelist. This tag adds a region with paths connecting it to the menu and each expedition, each requiring the relevant expedition unlock item to traverse.

Creating a YAML

When randomizing GTFO, it's recommended you generate a YAML template using the Generate Templates action in the Archipelago Launcher. The YAML template file will fully list out options and explanations, and allows for full customization. The Options Creator works, but is harder to use for GTFO.

Multi-Choice Options

Some of GTFO's options are "multi-choice". These choices allow you to choose as many or as few options as you want.

Multi-Choice options contain one special field, random. This determines how many choices are picked from the multi-choice, and how they are picked.

• If random is 0, no items will be selected.
• If random is -1, all items with a weight greater than 0 will be picked from the list.
• If random is a number greater than 0, that many items will be selected. For example, if it's set to random: 5, 5 items will be picked from the list. This will pick items based on their weight; items with a weight of 0 or lower will not be picked. If there are not enough items available, this will throw an error.

For example, the Enabled Expeditions option is a multi-choice option, and can be set up in these ways.

Pick Expeditions: This will select two expeditions with a weight greater than zero; this means it'll pick two of R3A1, R3A2, or R3A3. Note that expeditions which are not listed will have a weight of 0.

Enabled Expeditions:
    random: 2
    R3A1: 50
    R3A2: 50
    R3A3: 50
    R3B1: 0
    R3B2: 0
    R3C1: 0
    R3D1: 0

Pick 3-5 Expeditions: This will select 3-5 expeditions with a weight greater than zero; additionally, we set it so R1A1 and R6AX are both 10x as likely to be picked as any other expedition.

Enabled Expeditions:
    random: 3-5
    R1A1: 500
    R2A1: 50
    R3A1: 50
    R4A1: 50
    R5A1: 50
    R6A1: 50
    R6AX: 500

Pick Specific Expeditions: This will select all expeditions with a weight greater than zero; this effectively allows you to pick exactly which expeditions you'd like to play. Note that all unlisted expeditions are assumed to have a weight of zero, and as such will not be picked.

Enabled Expeditions:
    random: -1
    R1A1: 50
    R1B1: 50
    R1B2: 50
    R1C1: 50
    R1C2: 50
    R1D1: 50
    R8E2: 0

Game Options

These settings control some overarching parts of the generation.

• accessibility is the default Archipelago accessibility option. It controls whether you're guaranteed able to reach all checks or not.
• progression_balancing is also a default archipelago option. Higher values make it easier to find progression items early on.
• Root Seed controls many parts of randomization. You may leave it at 0 for a random root seed. Due to technical limitations, the root seed, when randomized, ignores the multiworld seed; if you're trying to share/recreate a seed, make sure you also share the GTFO root seed.
• Fail If Insufficient Empty Locations will ensure an error is thrown if there is not enough space in the world to generate. If you disable this, any items which could not be distributed into empty spaces will be placed into your starting inventory, for better or worse.
• Fail During Sampling will throw an error if something goes wrong while sampling items. Generally, you want this left on, as it'll ensure your random starting items and such are not simply omitted out due to an unforseen issue. However, the option to turn it off is available.

Goal

The goal options are fairly straightforward; they control what is required to beat the world. Most of the settings control which sectors must be cleared. For each enabled expedition you have (see below), if it has one of the goal sectors, that will be added as a separate "Goal item".

For example, if your expeditions are R4A1 and R4A2, and you set Main, Overload, and PE as required, your goal count would be 4:

• R4A1 Main
• R4A2 Main
• R4A2 Overload
• R4A2 PE

Note that, for this example, while secondary isn't required, you'd still have to complete it in R4A2 in order to get the PE clear item.

Also note that disabling a sector as a goal does not prevent items from being randomized into or out of that sector.

Once you have your goal count, you can use Skippable Goal Count to decrease it. Using the same example above, with a skippable goal count of 1, you could skip any 1 sector, which could be the entirety of R4A1, or the R4A2 PE clear. (It's not physically possible to skip any other sectors in that particular example, but if you found a way it would work)

Expeditions

These settings control several things related to expeditions:

Enabled Expeditions

This option controls which expeditions are available when you play; any expedition not listed will be inaccessible, and no items will randomize in or out of it (barring you edit edit the Region Whitelist or Blacklist).

Each expedition listed here will be required to meet the goal. Depending on the other settings you've enabled, you will be required to clear the main, secondary, and PE of these expeditions. However, even if you have it set to main only, items will still randomize into/out of secondary and overload on these expeditions; plan accordingly.

Progression Style

This option controls how expeditions are unlocked, if at all. There are two main progression styles:

• Item unlocks expeditions by finding randomly placed items in the multiworld.
• Progressive unlocks an additional expedition each time you clear an expedition

All other options are variants of these, described accordingly in its description. The only variant warranting more detail is the SEMI variant. SEMI only allows Archipelago to recognize the Progressive style, but still places Item-style unlocks in the multiworld. This guarantees that you can clear the expeditions in order (without entering a future expedition) but still allows you to break order and do other stuff if you're stuck waiting for something in your "current" expedition.

Starting Expeditions (ITEM), Random Starting Expeditions (ITEM), and Number of Unlocked Expeditions (PROGRESSIVE) do as advertised. Each only operates when its relevant progression style is selected. Random Starting Expeditions should be used when you've randomized your enabled expeditions because Starting Expeditions does not cross-reference the enabled expedition list.

Progressive Ordering, Starting Expeditions (Progressive), and Ending Expeditions (Progressive) controls the order expeditions must be cleared for a progressive-style game. Progressive Ordering can be used to set the general pattern, and the starting and ending expedition lists can be used to override part or all of that ordering for a more customized and intentional experience.

Lobby Slots

There are four lobby slots; one host slot and 3 locked slots. The host slot will always be unlocked. If you have Number of Unlocked Lobby Slots: 1, you will start with two total slots: the host slot plus 1 more. A mod such as Lobby Expansion can be used to increaes the number of lobby slots.

The AP Command

On each and every terminal is a new command called AP. This command will be essential for using items and completing checks. It is strongly recommended you take a look at the command in-game using the AP HELP sub-command; this should give you enough information to get started.

Items and Locations

A wide collection of items and locations are currently supported. You have the option to enable or disable randomization of each individual location and item in the game. The below describes the behaviour of some locations and items when they are enabled.

Locations (Checks):

• Picking up progression pickups, such as keys or IDs, as well as most big pickups, including cells, fog turbines, the MWP, etc will check a location and despawn the item. Note that if events are tied to picking up an item, they will not trigger when you attempt to pick it up.
• When certain events trigger (for example, by opening a door or completing special scans), the event is cancelled and a location is checked instead. This includes events which unlock or open doors, warp the team to a different dimension, start scans, or immediately clear the expedition.
• On each terminal is up to 3 location checks which can be completed using the AP EXTRACT and AP RELEASE sub-commands. These are added to account for items which are not normally collectibles, for example expedition unlocks, gear unlocks, and lobby slot unlocks. The more of these items you enable (and the fewer terminals you have access too), the more the terminals will be filled up.
• Any time you would learn a reactor code (checking a log or seeing it on-screen), you instead get a location check.
• Learning a terminal's password or password part is also a check in the same manner.
• Certain progression scans (Gen Cluster ending scans, HSU scans, and Dimension Portal scans) are checks; the trigger which would normally start the scan instead checks a location.
• Entering certain zones / "regions" will check locations. Most of these checks are for control locations used by logic to ensure beatability; however, some of these are randomized. Most notably, during a GatherSmallItems objective (for example, R1B1) you will automatically get checks for entering a Zone with fewer than the max count of objective items in it (in R1B1, this would be 3).

Some of the randomized items:

• Most progression-related pickups, such as keys, objective pickups (IDs, data cubes), and big pickups such as cells, fog turbines, and MWPs are supported. These items will be received into the terminal system and can be spawned in using a terminal.
• Certain events, including door unlock events, custom scan events, warp events, and win events. For most events, they must be manually triggered from a terminal; door unlock events will automatically unlock the relevant door when received or when the expedition is started.
  • Some events force doors open. As these events are often intended to hurt the player, these events have all been replaced with "unlock" events, so that they don't trigger early.
• Reactor codes and terminal passwords received from other players will show up in custom UI in the top left once you enter the zone containing the reactor or terminal. They can also be viewed at the terminal.
• Certain progression scans (Gen Cluster ending scans, HSU scans, and Dimension Portal scans, and "event" scans). Once obtained, these scans can be started from a terminal.

An additional set of "floating" or "optional" items:

• Expedition unlocks, if randomized, grant access to a locked expedition when found.
• Gear items can be locked, preventing them from being equipped. If a gear item is received while in an expedition, exactly one copy is sent the terminal, allowing up to one player to equip it mid-expedition.
• Lobby slots, if randomized, become unusable until the corresponding unlock item is found.
• If randomized, a free checkpoint can be found for every enabled expedition. Once obtained, you can activate the checkpoint at any terminal while in the level, once per attempt at the level. This works the same as any other checkpoint, but does not require a team scan to activate.

Logic Notes

The logic is set to only consider checks reachable if you are guaranteed able to reach it. This is opposed to things you might be able to reach with a bit of luck.

For example, in R5D1 there is a colored key card which can spawn in two zones. The logic will only consider this check reachable if you can reach both zones, even though it is possible to reach the keycard sooner as long as you can reach one of its spawn zones AND you are lucky enough to have it spawn in that zone.

As part of choice processing, checks are considered reachable if, for every possible spawn for that check, there exists at least one choice state in which it is reachable. For example, in R4A2 Secondary, the HSU can spawn behind 3 different doors, each requiring a cell to unlock. The HSU is considered reachable if you only have 1 cell (as opposed to 3) because you can choose to consume that cell on any of three doors, therefore ensuring whichever zone the HSU spawned in is reachable. IE, it only takes one cell to guarantee that the HSU is reachable.

Death Link

This integration supports Death Link. The settings for Death Link are not tied to the YAML config and can be changed at any time in the mod settings in-game. Punishments are highly customizable and range from spawning a tank to instantly killing the whole team, so you should be able to find a middleground that works for you.

Energy Link

This integration uses Energy Link. Picking up a Warden Artifact will add energy to your team; equipping a Booster costs energy.

Modded Support

This integrations aims to be compatible with modded rundowns. Full modded support will be added in the final release (with expansion mods to help improve compatibility with rundowns created based on demand). At present, if you're lucky enough that it works out of the box then enjoy it full-heartedly, otherwise support will be limited.

To create a modded game, you will need a file called the MID file. This is a file with the name "GTFO-abcdefhij.ini" which contains a list of everything Archipelago needs to generate a game for the world. To create this file, start the game with all your mods enabled and go to the Server Settings. There will be a button which allows you to export the MID file; after a noticable processing delay, this will output the file to your Downloads folder.

Take the MID file and place it in your Players folder, then restart the Archipelago Launcher. This adds your modded world as a new APWorld, and it can be treated the same. If you are having someone else perform the generation of your game, send them both the MID file and your YAML; both go in the Players folder.

MID files are uniquely named to represent the set of mods in your game. If two sets of players generate a MID file with the same name, there is a 1/(2^60) chance that the games are incompatible. In other words, it is extremely likely they can share the file with no issues.

More Details

When the game generates MID data (which it does at startup), it will output logs around errors, issues, etc. These include some common errors (like how R8E1 has no extraction point) and some assumptions being made in order to aid generation. It will also output logs with the name of the game and its hash. The name of the game is purely aesthetic - two modded games are considered compatible if and only if their hashes and identical.

If you'd like to see these logs (as well as other logs output by Archipelago), I recommend going into BepInEx.cfg and disabling Unity Log Listening. This will significantly reduce the number of logs sent to the console, leaving only logs from mods visible.

When you export MID data, the mod performs choice processing in which it computes all possible relevant choice states and compresses them.

• A choice is an action which improves reachability of one or more regions at some cost, typically by consuming an item. The most common examples are using bulkhead keys and inserting cells into generators.
• A choice state is the set of unique choices that have been taken. It identifies a state of the game in which one or more regions are reachable because of the choices which have been made. Choice states are only created if it is possible for that combination of choices to improve the reachability of any region/location.

When choice state processing concludes, the mod will use the newly-computed choice states and region graph to attempt to beat the game. It will dump to the log which expeditions and sectors it was able to clear, and which it was not. As a rule of thumb, if Archipelago is able to find a route to clear a sector, you most likely can play that sector in Archipelago with minimal issues. If it cannot, then it is guaranteed impossible to play that expedition in Archipelago (internally, it will be unable to process it - attempting to play that expedition will most likely result in only portions which Archipelago considers reachable being randomized)