Dwarf Fortress — Archipelago Setup Guide

Required Software

Dwarf Fortress (Steam 2022+ or Classic)
DFHack — install via Steam alongside DF
Archipelago 0.6.7

Upgrading from 1.3.x? 2.0 changed locations, items and logic, and added new raws. Both halves have to be redone: generate a new multiworld seed (old seeds are refused rather than allowed to fail mid-run) and generate a new DF world (raws only enter a save at world-gen). Existing forts cannot be carried over.

Installation

1. Install the AP World

Download dwarfipelago.apworld from the Releases section and double-click it. Archipelago will automatically copy it into your custom worlds folder.

The AP client is bundled inside the world package — there is no separate client file to copy anywhere.

2. Install the DFHack Mod

Copy the mods folder from this repository into your Dwarf Fortress installation:

<SteamLibrary>\steamapps\common\Dwarf Fortress\mods\

%AppData%\Roaming\Bay 12 Games\Dwarf Fortress\mods\ works too — the client writes to whichever copies it finds. Just don't keep one in both, or you will be guessing which one DF's mod manager is showing you.

This creates mods\dwarfipelago\. The final layout should look like:

mods\dwarfipelago\
  info.txt
  objects\            <- raws: the Archipelago civilization and the shop materials
  graphics\           <- raws: the AP item sprite
  scripts_modinstalled\
    dwarfipelago.lua
    internal\
      dwarfipelago\
        apcaravan.lua
        checks.lua
        items.lua
        log.lua
        state.lua

The objects\ and graphics\ folders are not optional. They carry the ARCHIPELAGO civilization and the Merchant's Shop materials, and raws only enter a save at world generation — a world generated without them can never have the shop, no matter what you install afterwards.

installed_mods snapshot: when DF enables a mod it copies it to a snapshot directory, and that copy is what world-gen actually reads. The client keeps this in sync for you — on connect it wipes any stale dwarfipelago* snapshots and reinstalls a fresh one, so you no longer have to disable/re-enable the mod by hand after an update. The snapshot lives at:
%AppData%\Roaming\Bay 12 Games\Dwarf Fortress\data\installed_mods\dwarfipelago (15)\

3. Install the World Gen Preset

Dwarfipelago works best with a specific world generation profile. The client installs this for you whenever it connects, so in the normal flow you can skip straight to step 4.

If you want to install it without connecting — or something went wrong — run this in the Dwarf Fortress Client from the Archipelago launcher:

/dfinstall

It adds the preset to your world gen list and reinstalls the mod snapshot. /dfuninstall reverses both, leaving your mods\dwarfipelago\ copy and your saves untouched.

Back up your world_gen.txt first if you have custom presets you care about:
%AppData%\Roaming\Bay 12 Games\Dwarf Fortress\prefs\world_gen.txt
The command appends the Dwarfipelago preset without touching your existing entries, but a backup is good practice.

After running the command, restart DF and the DwarfipelagoWorld preset will appear in the world generation preset list. Select it when creating a new world.

If /dfinstall can't find your world_gen.txt (e.g. a non-Steam install), set game_path in host.yaml to your Dwarf Fortress.exe, or copy prefs/world_gen.txt from this repo into your DF prefs/ folder by hand.

Verifying your world

After generating a world (and before embarking), run this command in the DFHack console to confirm the world meets Archipelago requirements:

dwarfipelago test worldcheck

This checks world size, history length, the presence of Dwarf/Human/Elf/Goblin and gorlak (Archipelago) civilizations, and active volcano count. If any check fails, consider rerolling — a world missing a key civilization will make certain AP goals impossible, and a world with no gorlak civ has no Merchant's Shop at all.

worldcheck can only tell you the gorlaks exist somewhere in the world. Whether they will actually trade with you depends on their being a neighbor of your embark, which is a site-selection decision — see "Choosing an embark site" below.

4. Generate Your Archipelago Session

Create a DwarfFortress.yaml options file and generate your session through the Archipelago launcher or CLI:

name: YourName
game: Dwarf Fortress

Dwarf Fortress:
  goal: population_boom             # population_boom | legendary_wealth | slay_megabeast | mountainhome
  wealth_goal_amount: 100000        # target treasury value in minted coins + cut gems (legendary_wealth goal only)
  population_goal_amount: 300       # target population (population_boom goal only, range 20–500)
  trap_item_weight: 20              # 0–100, percentage of filler slots that are traps
  deathlink: false                  # enable DeathLink
  deathlink_threshold: 5            # dwarf deaths per outgoing DeathLink (1–20)

  # Craftsanity — optional crafting milestone checks
  craftsanity: off                  # off | on | storage
  craftsanity_difficulty: medium    # easy | medium | hard | craftsanity | choose
  craftsanity_enable_materials: false  # split checks by material type (Stone Blocks vs Metal Blocks)
  craftsanity_max_amount: 15        # total items to produce per check group
  craftsanity_threshold: 5          # items crafted per individual check
  # craftsanity_items:              # only used when craftsanity_difficulty is 'choose'
  #   - Beds
  #   - Blocks
  #   - Cloth

5. Launch and Connect

Connect the client before you open Dwarf Fortress. On connect it installs the world gen preset, reinstalls the mod snapshot so world-gen reads current files, and then launches DF itself. If DF is already running it read its mod list at startup and will not see any of that.

Click Dwarf Fortress Client in the Archipelago launcher and connect to your server.

Watch the client log for the install lines:

World gen preset installed to: ...
Installed dwarfipelago (raws + scripts) for world-gen to: ...
Native caravan: baked 50 shop good(s), prices <lo>-<hi>, into: ...

DF then opens on its own — you do not need the launcher's Dwarf Fortress button.

In DF choose Create New World, and in the world gen screen:
- select the DwarfipelagoWorld preset, and
- tick Dwarfipelago in the mod list. This is the step people miss. Enabling the mod here is what writes its raws into the save; a world generated without it has no Archipelago civilization and no Merchant's Shop, permanently.
Generate the world.
Pick an embark site with the gorlaks as neighbors — see below — then embark.

The mod starts automatically once a fortress loads — no DFHack console commands needed.

Choosing an embark site

Dwarf Fortress only sends you caravans from civilizations whose territory borders your embark. The Merchant's Shop rides on a caravan from the Archipelago civilization, a gorlak trading people, so if they are not your neighbor they will never visit and the entire shop is unreachable — all 50 slots, for the whole fortress.

On the embark site-selection screen, check the Neighbors panel and confirm gorlaks are listed alongside the usual dwarves/humans/elves/goblins. If they are missing, move the embark rectangle elsewhere on the map until they appear.

The gorlaks settle grassland, savanna and shrubland and build cities, so embarking within reach of open temperate land is the reliable way to get them as a neighbor. A remote glacier or a deep mountain range is the usual way to lose them.

If you got it wrong

The two failure modes are not equally bad, and it is worth knowing which one you have before you throw anything away:

Problem	Recoverable?	What to do
The gorlaks exist in the world, but are not a neighbor of your embark	Yes	Retire or abandon the fortress and re-embark elsewhere in the same world, somewhere the Neighbors panel lists gorlaks. Your run is unaffected: the seed is stored against the world, not the site, so it still matches, and the mod re-delivers everything you had already received.
The world has no gorlak civilization at all	No	A new world is required. The client refuses to bind your run to such a world, so the multiworld seed is unspent — generate a world with the mod ticked and reconnect with the same seed.

To tell them apart, run dwarfipelago test worldcheck: it reports whether the Archipelago civ exists in the world. Existing but never visiting is the neighbor problem; missing entirely is the world-gen problem.

A world with no gorlak civilization makes the client refuse to bind your run and keep saying so, while the mod raises a popup and repeating warnings in game. That is deliberate — it costs you only the time already spent, and nothing done inside that fortress can fix it.

Receiving your first Merchant's Coffer asks the game to summon a gorlak caravan immediately. That request can fail silently: if the gorlaks are not a neighbor the caravan may be spawned off-map and never arrive, and if the civilization does not exist at all nothing is summoned. Either way you get no caravan and no shop, so do not count on the forced visit to rescue a bad site. The mod now says so in game rather than only in the log, and retries on each later coffer. Within a few ticks you should see the trade depot announcement below.

Merchant's Shop goods are named and priced by the mod while your fortress runs, so any world generated with Dwarfipelago enabled shows them correctly no matter when you connected. The client additionally bakes them into the raws before world gen as a fallback. What the shop does require is that the world was generated with a mod build that includes the shop materials — an older one leaves the goods unnamed at a flat price, and the mod says so in <Dwarf Fortress>/dwarfipelago.log. The fix is to generate a new world with the current mod enabled.

Trade Depot

On the first poll tick after your fortress loads, the mod automatically places a Trade Depot near your starting wagon. You will see the announcement:

[AP] A Trading Post has been established near your starting wagon!

The depot is placed 7 tiles west of the wagon and instantly completed (no dwarves or materials required)
If that spot is obstructed the mod tries the remaining three cardinal directions
If you already have a Trade Depot built, it is adopted as the delivery point instead
All AP location checks and item deliveries are held until the depot is established — nothing is sent or received before it exists

If the depot does not appear

Build a Trade Depot manually — the mod will detect and adopt it on the next poll tick
To force a retry, run in the DFHack console:
```
lua dfhack.persistent.saveWorldDataString("dwarfipelago/depot_built", "0")
```
Then save and reload your fortress

Troubleshooting

Symptom	Fix
"Dwarf Fortress not found"	Set `game_path` in `host.yaml` to point to your `Dwarf Fortress.exe` (Steam) or `dfhack.exe`
"Dwarf Fortress Client" missing from launcher	Confirm `dwarfipelago.apworld` is installed and restart the launcher
Client can't connect to DFHack	Ensure DFHack is running; its remote API listens on `127.0.0.1:5000` by default
Mod doesn't start automatically	Load a fortress and wait ~5 seconds; you can also run `dwarfipelago start` in the DFHack console
Trade depot not appearing	See the Trade Depot section above
Items not arriving	Check the client log window; items are delivered via DFHack RPC once the depot is established
Checks fire immediately on world load	Ensure you are running Archipelago 0.6.7 and the latest mod version
Shop goods have no names / all cost the same	That world was generated with a mod build older than the shop materials. Check `dwarfipelago.log`, then generate a new world with the current mod enabled (see step 5)

Where to find errors

AP client window — client, RPC, and network errors, with full tracebacks.
<Dwarf Fortress>/dwarfipelago.log — in-game mod errors (item spawn failures, trade depot placement, etc.). The path is printed to the DFHack console on start; print it any time with lua print(reqscript("internal/dwarfipelago/log").path()).