What is Archipelago?
Archipelago is a free, open-source multiworld randomizer. It shuffles the items of one game into the world of another — so when you level up in Path of Exile, you might unlock a power-up for your friend playing Super Mario 64, and vice versa.
You can also play completely solo: your Path of Exile progression gets shuffled with itself, so you earn your skills, gems, and gear slots as rewards instead of starting with them.
No. The client only reads your Client.txt log file and the public PoE API, then writes to your
local item filter. It uses one-button-one-action macros and nothing else. Everything it does is something
a regular player could feasibly do manually.
How It Works in PoE
The Archipelago client runs alongside Path of Exile. It never touches the game's files directly — it watches what you do and reacts:
Your item filter highlights what matters.
The client modifies your local loot filter to highlight items that would send a check, and stops highlighting items you've already checked. Optional audio cues announce incoming unlocks — and their magnitude too, so you know at a glance whether something important just arrived.
You pick up an item or level up.
The client watches your inventory, through GGG's API, when you change zones. Qualifying items (specific base types) count as "checks" and send items to other players.
You receive unlocks from the multiworld.
When you (or a teammate) checks a location, you might receive a skill gem, a gear slot upgrade, passive points, or a new character class. The client tells you what arrived.
You can only use what you've unlocked.
Equipping something you haven't unlocked puts you "out of logic" and blocks further check
sends until you correct it. Whisper yourself !gear or !gems to see
what's allowed.
Checks are only sent when you change zones. If you pick something up and nothing happens right away, don't panic — just walk through a waypoint or door.
What Gets Shuffled?
Locations (things you do to send checks)
Items (things you can receive as unlocks)
In a normal PoE run you pick up any gem and equip any item you find. Here, you start with almost nothing — you'll earn the right to use gems, wear better gear, and spend passive points as rewards for exploring the world. Think of it like starting a run with a locked skill tree that you gradually unlock by playing.
Highly Configurable
Almost every aspect of your run can be tuned in your .yaml settings file before generating. You don't
have to accept the defaults — tailor the experience to your group's preferred difficulty and play style.
How Much Setup Do You Want?
The mod is flexible about where you start. At one extreme you can drop straight into an existing endgame character — just refund all your passive points with Orbs of Regret, unequip your gear, and the client will treat you as starting from scratch. At the other extreme you can create a brand-new character in an SSF league for a completely clean slate with no shared stash or trade to fall back on. Everything in between works too.
Goal
Choose what ends your run. Options range from simply completing the campaign to killing specific pinnacle bosses like Shaper, Elder, or Maven. You can also set a custom kill count or boss checklist.
Starting Conditions
Control how much you begin with. starting_character sets your class (or leaves it random).
usable_starting_gear lets you keep your starting weapon and flasks so the very early game isn't completely blind.
Item Pool
Toggle whether passive skill points, level milestones, and specific gem categories are included in the shuffle. A larger pool means more checks to send and receive — the run itself isn't necessarily longer, but there's more going on and more items flowing between players. A smaller pool is tighter and more focused.
Progression Balancing
Archipelago can weight the item pool so that key unlocks — like your needed skill gems, gear unlocks, or ascendancies —
tend to arrive early rather than being buried in late checks. Adjust the progression_balancing
slider in your .yaml to control how aggressively it front-loads important items.
You can configure everything visually (no YAML editing required) at
ap.stripesoo7.org
or multiworld.gg.
Generate the file there and drop it straight into your Players/ folder.
Before You Begin
Path of Exile — installed and playable. Free download here.
Python 3.12 — required by Archipelago. Download Python 3.12.
Python 3.13 will NOT work. Use 3.12 specifically.
Know the path to your PoE Client.txt log file — usually somewhere like
C:\Program Files (x86)\Grinding Gear Games\Path of Exile\logs\Client.txt
Optional: Have a local item filter file saved on your PC — not a subscribed one.
Usually in C:\Users\YOU\Documents\My Games\Path of Exile\.
Any NeverSink variant works fine as a base. If you skip this, the client won't apply your normal gameplay filter,
but everything else still works.
Step 1 · Install Archipelago
Download the latest Archipelago installer from github.com/ArchipelagoMW/Archipelago/releases.
Get the .exe installer, not the source code archives.
Run the installer and choose a convenient folder (e.g. C:\Games\Archipelago).
Launch ArchipelagoLauncher.exe from that folder to confirm it works.
Consider making a desktop shortcut — you'll use this often.
Step 2 · Add the Path of Exile .apworld
Download the latest poe.apworld file from
github.com/stubobis1/Archipelago/releases.
Again, grab the .apworld file — not the source code.
Copy that file into the custom_worlds folder inside your Archipelago installation.
(e.g. C:\Games\Archipelago\custom_worlds\poe.apworld)
Do not extract or rename it — just drop the file in.
Step 3 · Generate or Join a Game
You need a .yaml settings file that tells Archipelago what kind of run you want.
Creating your settings file — recommended
Open the visual options editor at ap.stripesoo7.org or multiworld.gg. No installation required — everything is point-and-click.
Set your slot name, goal, starting class, and any other options you want to tweak.
Download the generated .yaml and place it in your Archipelago/Players/ folder.
Creating your settings file — manual
In ArchipelagoLauncher.exe, click Generate Template Options (near the bottom of the list).
Open Archipelago/Players/Templates/Path of Exile.yaml in any text editor.
Edit to taste. Key settings:
name— your player slot name (e.g.ChrisWilsonsBeard)goal— what ends your run (campaign, bosses, etc.)starting_character— which class you begin with (orrandom)usable_starting_gear— how much starter gear you keepadd_passive_skill_points_to_item_pool— locks and unlocks passive points
Save your edited file to Archipelago/Players/ (not the Templates subfolder).
If you are hosting (solo or with friends)
Make sure all players' .yaml files are in the Players/ folder.
Click Generate in the Launcher. This creates an archive in the output/ folder.
Upload the archive to archipelago.gg or multiworld.gg to host online without port-forwarding — just share the room link
Alternatively, Click Host in the Launcher and select that archive. The server runs on port 38281 by default.
Share your IP and port with teammates.
If someone else is hosting
Send the host your .yaml file and make sure they have the same poe.apworld version.
Get the server address and use the slot name from your .yaml file when connecting.
Step 4 · Start the Client & Play
In ArchipelagoLauncher.exe, find and click Path of Exile in the client list to open the PoE client window.
In the Server bar at the top, enter your slot name, password, and server address in the format SlotName:password@host:port then click Connect.
If hosting yourself, it will be 127.0.0.1:38281 for the host and port.
The log path should be automatically set when loading, but if it isn't working, set your log path using something like: /client "C:\...\logs\Client.txt" (replace with your path, and include the quotes)
Set your item filter: /filter MyFilter.filter
This should be a local filter file in your Path of Exile documents folder. This is an optional step, but one that can enhance your gameplay experience.
Launch Path of Exile and log in.
Set your character in the client console: /char YourCharacterName
You can also type !apchar in the in-game chat after step 7.
Type /start and enter the game. The item filter will load and you'll see highlighted items immediately.
Enter a zone to trigger your first check. Welcome to the randomizer!
Step 5 · Open the Web Tracker (Optional but Recommended)
The web tracker gives you a live dashboard of your received gems, gear unlocks, equipment slots, locations, and hints — no install required.
Open stubobis1.github.io/pathofexile_ap/ in any browser.
Enter your server address and slot name in the connection panel at the top, then click Connect.
The tracker updates in real time as you receive items and check locations. Use the tabs to switch between Items, Locations, Equipment, and Hints.
Hover over any gem in the Items tab to see a full tooltip — level requirements, stat text, and description — pulled live from the Path of Exile wiki.
DeathLink (Optional)
DeathLink is an optional Archipelago feature that links deaths across the entire multiworld. When you die in Path of Exile, a death signal is sent to every other DeathLink-enabled player — and when anyone else dies, you all die.
In Path of Exile specifically, receiving a DeathLink signal does not kill your character — instead the client logs you out to the character select screen. You re-enter the game at your last town or checkpoint, avoiding any XP loss or Hardcore consequences from other players' deaths.
It's entirely opt-in per player. Enable it in your .yaml before the run starts, or toggle it
mid-run with !deathlink whispered to yourself in PoE.
!deathlink to yourself or use /deathlink in the client console to flip it on or off without restarting.In-Game Chat Commands
Whisper these commands to your own character in PoE chat.
For example: @YourCharName !gems
Client console commands (typed in the Archipelago client, not in PoE):
F11 — restart the client if something goes wrong.
F12 — force the client to re-check your current state (useful if a check didn't send).
Tips & Troubleshooting
- Keep the Archipelago client open the entire time you play. It shows item sends, receives, and player names in real time.
- Checks only fire on zone change. Nothing happening after a pickup is normal — just move to a new area.
- If you're using a gem or gear piece you haven't unlocked, you're "out of logic" and checks won't send until you fix it. Whisper yourself
!gearor!gemsto verify what's allowed. - If your item filter isn't updating, check that the path is correct and that OneDrive sync isn't locking the file. Try disabling OneDrive if you see write errors.
- Make sure the
/clientpath points to the correctClient.txt. The client reads this file to detect zone changes and chat whispers. - Town Portals are your friend — drop items off at the stash to check them without needing to reach a full transition zone.
- The early levels before your first few gems arrive can be rough. There's no shame in starting with your class weapon, starter gem, and flasks unlocked in your yaml settings.
- Many "bad" endgame skills are perfectly fine for clearing the campaign. Use whatever you've been given!
- F12 forces a re-check if you think something got missed — helpful when
Client.txtis temporarily unreadable. - Report bugs in the GitHub issue tracker or ask in the Path of Exile Archipelago Discord channel.