Setting up your YAML

Your YAML describes one world

A YAML is a text configuration for a world the generator will create. It names the game and slot and records how that world should be randomized. A normal multiworld uses one YAML for each generated world. Most players bring one world, but one person can bring several.

You normally start from an options page, a template generated by Archipelago, a template supplied by the maintainer, or the Archipelago Pie builder. The quick path comes first; the rest is a deep dive for when you want to understand or hand-edit the file.

Getting a template

For officially supported games, the website is the easiest route. Open the supported games list, pick your game, click its Options Page, set everything with normal form controls, and click Export Options to download a ready YAML.

Community games are not on those options pages. Install the exact .apworld version requested by your host, restart Archipelago Launcher, and use Generate Template Options. This writes templates for installed games into Players/Templates. Some maintainers also include a template in their release.

You can also use the Archipelago Pie YAML builder. When AP-Pie can read the selected APWorld version's options, it turns them into a form and emits the finished YAML. A game may still appear in the APWorld catalog without being buildable, so use the maintainer's template route when Create YAML is unavailable.

The quick version

The fastest route is the builder on this site, where you choose a game and version, enter your slot name, review the documented options, and download the result. Working from a current template is just as valid. Start close to the maintainer's documented defaults when you are learning, but read the setup guide and option descriptions because independently maintained APWorlds do not share one universal default policy.

Check the file with the official validator or submit it to a collector that performs early checks. These checks catch many structural and option problems, but final compatibility is decided when the host generates with the intended Archipelago and APWorld versions.

Everything below this point is the deep dive for your second seed and onward.

What this file is not

Several different files can appear in the same workflow:

• An .apworld installs a community game integration into Archipelago.
• A YAML describes one world and its options before generation.
• A generated player file is a patch, mod, or other slot-specific output made for a particular seed when that game needs one.
• A client or connector links the running game to the Archipelago server.

Creating a YAML does not install the game client. Downloading an APWorld does not replace a seed-specific player file. Setting up an Archipelago game client covers the post-generation side.

Reading the options

Open the file in a text editor, where a code editor like VS Code gives you nicer coloring, and plain Notepad works completely fine too. You will see the same few shapes repeated. A toggle takes true or false. A choice option lists its allowed values in the comment above it, and you pick one of them. A range takes a number between the bounds the comment gives you. The comments are the real documentation, and they sit right next to the thing they explain.

Two fields deserve extra care before anything else. Your name is your slot name, and it has to match exactly what you type when your game client connects. And if your host pinned specific apworld versions for the room, generate your template from that same version so the options line up.

How weights actually work

This is the part of the format that confuses the most people, so it deserves a proper explanation. In a template, most options do not look like mode: standard. They look like this instead:

mode:
  standard: 50
  inverted: 0

Those numbers are weights, and the best way to think about them is raffle tickets. Every value with a number above zero has that many tickets in a draw, and when your seed generates, the generator draws one ticket and that value wins. In the example above, standard holds all fifty tickets and inverted holds none, so standard wins every time, and the file behaves exactly as if you had written mode: standard.

The interesting part starts when you spread the tickets. Give standard a weight of 3 and inverted a weight of 1, and three out of four seeds will roll standard while the fourth surprises you. The absolute numbers do not matter, only the proportions, so 3 and 1 behaves the same as 75 and 25. This is how players who have done a hundred seeds keep things fresh, because the file itself rolls the dice for them.

If you find weights confusing in practice, you can ignore them entirely. Put any number on the one value you want, leave everything else at zero, and every option becomes a fixed choice. That is how the templates ship, and it is a perfectly good way to play.

Letting the generator pick numbers

Range options accept a few special values besides plain numbers. Writing random picks any allowed value, random-low leans toward small numbers, random-high leans toward large ones, and random-middle clusters around the center. You can also bound the roll with random-range-40-60, which picks something between 40 and 60. These combine with weights like any other value, so a range option can hold tickets for a fixed number and a random roll at the same time.

The options every game has

A few settings appear in every Archipelago template regardless of the game, and they shape the multiworld experience more than most game-specific options do.

Progression balancing helps reduce long stretches where one world has no useful locations left while progression waits elsewhere. Higher values ask the generator to intervene more strongly; 0 turns the feature off. The exact placement behavior is more nuanced than a fixed promise about how far behind a player may fall, so keep the documented default unless your group understands the tradeoff.

Accessibility decides how much of your world the generator must keep reachable. The default of full guarantees every location in your world can be reached, items only guarantees you can obtain every logically relevant item, and minimal promises nothing beyond the seed being beatable, which can leave whole areas of your game permanently locked. Minimal makes for faster and more chaotic seeds, and it is a deliberate choice rather than a beginner's one.

Shaping where the items go

The template ends with a block of item and location options that are empty by default, and they are worth knowing even if you never touch them. start_inventory hands you chosen items at the start of the game, which is how people play with a weapon from minute one. local_items forces chosen items to stay in your own world, and non_local_items pushes them into other worlds. start_hints gives you free server hints for chosen items from the start, and start_location_hints does the same for locations. exclude_locations marks locations that must not hold anything important, which is the polite way to opt out of a check you hate, and priority_locations does the opposite by forcing something important onto a location. item_links lets several players pool a chosen item so that when one of them finds it, everyone in the link receives it.

There is also a triggers block for conditional logic, where one option can change other options when it rolls a certain way. It is genuinely advanced, and the official advanced guide covers it when you get there.

One file, several games

The game field at the top accepts weights just like any other option, so a single file can hold tickets for several games, with an options block for each. Every seed then rolls which game you are playing that time. It is a favorite of players who genuinely cannot decide, and it works in any room that allows those games.

Checking your work

The validator at archipelago.gg/check catches many structural and option mistakes before generation. Archipelago Pie also performs early checks when a YAML is submitted. Neither check can prove that a full multiworld will generate against every custom fork, meta setting, interaction, or different APWorld version.

Handing it in

You do not need to manage a file on your phone. In the Builder, choose Sign in and save or Save to my YAMLs on the review step. Your setup is then available in My YAMLs after signing in on your computer. Browser-tab drafts are different: they stay in that tab until you save them to your account.

If your host uses an Archipelago Pie collection room, start from its invitation. Choose Use a saved YAML or build one for the room, review the requested version, and submit directly. A successful account save does not submit to a room. After submitting, return to the room to check validation and edit your YAML if something needs attention.

When a saved setup has an older APWorld version, Keep this version reopens it as saved. Review changes lets you inspect a newer version and prepare a separate copy, leaving the original intact. A newer release is not automatically the version your host needs.

Send the file to whoever hosts your game. If they use this site, they will give you a collection-room link where you submit it in the browser. Hosting an Archipelago multiworld shows what happens on the host's side. After generation, use the maintained setup guide and game-client guide to get connected.