Quick Start

Get started in minutes

Foolproof, copy-pasteable walkthroughs for every project in the workspace. Pick the one you need below — each guide lists its prerequisites and the exact commands to run.

Which order should I follow?

To play the game: on an Apple Silicon Mac, start with the Installer to get a 1.0 client, then the Client to launch it, pointed at a Server you run yourself. (Already have a 1.x install, or on Linux/Windows? Skip straight to the Client.)

To contribute to the reverse-engineering effort: set up meteor-decomp (the client decompilation), then optionally decomp-agents to grind through it automatically.

Garlemald Server Garlemald Client meteor-decomp decomp-agents XIV 1.0 Apple Silicon Installer

Garlemald Server

FFXIV 1.23b server emulator, rebuilt from scratch in Rust.

View on GitHub

Server

Rust

AGPL-3.0-or-later

Build and launch a private FINAL FANTASY XIV v1.23b server on your own machine. One script compiles the four-binary Cargo workspace, seeds a SQLite database, and boots the full lobby / world / map / web stack on localhost.

Before you start

Git, to clone the repository.
Rust 1.95 — rustup installs the pinned toolchain automatically on the first build (pinned in rust-toolchain.toml).
A C toolchain for native crates: Xcode Command Line Tools (macOS), build-essential + pkg-config (Linux), or the MSVC C++ Build Tools (Windows).
No external database: SQLite is embedded and seeded on first run — there is no MySQL/PHP/WAMP to provision.

Walkthrough

Install Rust

Install Rust with winget (or download rustup-init.exe from rustup.rs). You also need the MSVC C++ Build Tools — the “Desktop development with C++” workload from the Visual Studio Build Tools.

winget install Rustlang.Rustup

Clone the repository

git clone https://github.com/swstegall/Garlemald-Server.git
cd Garlemald-Server

Build and launch the whole stack

Every helper script has a .cmd equivalent in the scripts/ directory.

scripts\run-all.cmd

Let the first run seed the database

The first launch creates ./data/garlemald.db, applies the bundled schema, seeds every reference table from the 40 bundled SQL files, and boots on localhost. This only happens once.

Know where configuration lives

Garlemald Server is configured with TOML files, not a .env. Each service reads its own file under configs/ — configs/lobby.toml, configs/world.toml, configs/map.toml, and configs/web.toml — and all four share one SQLite database. The localhost defaults boot straight into a playable single-user server; override any path with --config <path> on the matching binary, and see the comments inside each configs/*.toml for the env knobs (packet logging, Lua script root, etc.).

Connect a client and sign up

Point Garlemald Client (or a patched 1.23b client reporting 2012.09.19.0001) at the lobby on 127.0.0.1:54994, then sign up through the web endpoint on 127.0.0.1:54993 to mint a playable session.

Run individual services for debugging (optional)

Use the .cmd variants when iterating on a single service.

scripts\run-web.cmd
scripts\run-lobby.cmd
scripts\run-world.cmd
scripts\run-map.cmd

Windows: Use the `.cmd` variant of every `scripts/run-*` helper — the bash scripts are for macOS and Linux — and install the MSVC C++ Build Tools so the native crates link.

Where to next

Need a client? Set up Garlemald Client to patch and launch a 1.x install against this server.
Grab a prebuilt server binary from the Downloads page.
Questions or bug reports? Join the Discord.

Garlemald Client

Cross-platform Rust launcher for FFXIV 1.23b private servers.

View on GitHub

Client

Rust

AGPL-3.0-or-later

Build the cross-platform launcher that detects your installed FFXIV 1.x client, patches it forward to 2012.09.19.0001, and launches the game against a private server. On macOS and Linux it manages its own Wine runtime, so there is nothing else to install.

Before you start

Git and Rust 1.95.0 — rustup installs the pinned toolchain on the first build.
An existing FINAL FANTASY XIV 1.x install (CrossOver bottle, Whisky prefix, or manual Wine install — all auto-detected). On Apple Silicon, the XIV 1.0 Apple Silicon Installer can produce one.
Linux only: the GTK 3 + WebKit2GTK 4.1 runtime libraries for the login WebView.
Windows only: the MSVC C++ x86 build tools (the launcher must build 32-bit).

Walkthrough

Install Rust

Install Rust with winget (or rustup-init.exe), plus the MSVC C++ build tools — you specifically need the x86 (32-bit) target support.

winget install Rustlang.Rustup

Clone the repository

git clone https://github.com/swstegall/Garlemald-Client.git
cd Garlemald-Client

Build and run (32-bit)

On Windows the launcher must be built as 32-bit (i686) so it can read the suspended thread context of the 32-bit ffxivgame.exe and patch it at launch.

rustup target add i686-pc-windows-msvc
cargo build --release --target i686-pc-windows-msvc
cargo run   --release --target i686-pc-windows-msvc

Launch, log in, and play

On first run the launcher detects your 1.x install, CRC32-verifies and applies the patch chain (2010.09.18.0000 → 2012.09.19.0001), then shows the WebView login. The lobby hostname is injected into the PE at launch, so the same binary can target any private server.

Windows: Build for the `i686-pc-windows-msvc` target — a 64-bit build cannot patch the 32-bit game process.

Where to next

Point the client at a Garlemald Server instance (default lobby 127.0.0.1:54994).
On Apple Silicon and don't have a 1.x install yet? Run the XIV 1.0 Apple Silicon Installer first.
Grab a prebuilt launcher from the Downloads page.

meteor-decomp

Clean-room decompilation of the FFXIV 1.23b client binaries.

View on GitHub

Research

C++ / Python

AGPL-3.0-or-later

Stand up the decompilation pipeline for the FFXIV 1.23b client binaries. The static-analysis track runs under Ghidra and emits per-function assembly, a work pool, and validated wire-protocol reports; the optional matching track recompiles individual functions byte-identically. The toolchain targets macOS and Linux.

Before you start

Git, Python 3, and make.
Ghidra 12 + JDK 21 for the static-analysis track.
Your own copy of the Square Enix 1.23b binaries — they are copyright SE and are NEVER committed to this repo. make bootstrap symlinks them from your local install.
Optional byte-matching track: the VS 2005 RTM + Platform SDK 2003 R2 toolchain running under CrossOver Wine.

Walkthrough

Clone the repository

git clone https://github.com/swstegall/meteor-decomp.git
cd meteor-decomp

Install Ghidra 12 + JDK 21

Homebrew pulls openjdk@21 along with Ghidra.

brew install ghidra

Bootstrap

Symlinks the original binaries from your local install (it does not copy them) and dumps the PE structure as a sanity check.

make bootstrap

Run the static-analysis split

Requires Ghidra 12 + JDK 21. Start with a small binary to confirm the toolchain, then run the big one. ffxivlogin.exe takes ~30s; ffxivgame.exe takes 30–60 min on Apple Silicon.

make split BINARY=ffxivlogin.exe   # ~30s — sanity check
make split BINARY=ffxivgame.exe    # 30–60 min

Inspect the work pool

After a split you get per-function asm under asm/<binary>/, a config/<binary>.symbols.json function list, recovered RTTI, and the config/<binary>.yaml work pool (one row per function).

make progress

Run the Phase 3 extraction / validation pipeline

These targets emit the ground-truth wire reports under build/wire/ and the validated headers under include/net/ that pin field offsets against the binary.

make extract-net          # net-class vtable → fn_rva map
make extract-gam          # GAM property registry
make extract-paramnames   # PARAMNAME dispatchers (192/192)
make extract-opcodes      # Down opcode → vtable-slot
make validate-murmur2     # MurmurHash2 vectors

Configure the matching toolchain via its env file (optional)

Only needed for the byte-identical recompilation track. The build reads a small env file at ~/.config/meteor-decomp.env that points it at your MSVC-2005-under-Wine install via MSVC_TOOLCHAIN_DIR. Set it once, then verify cl.exe + PSDK + objdiff are reachable.

echo 'export MSVC_TOOLCHAIN_DIR="$HOME/sdk/msvc-2005"' \
    > ~/.config/meteor-decomp.env
make setup-msvc

Attempt a byte-identical match (optional)

Compiles the _rosetta/*.cpp sources and diffs each against the binary slice. make diff FUNC=... grades a single function OK / PARTIAL / MISMATCH.

make rosetta        # compile + diff all _rosetta/*.cpp
make diff FUNC=...  # grade one function

macOS: `brew install ghidra` brings JDK 21 with it. The MSVC matching toolchain runs under CrossOver Wine 9.

Where to next

Read the Plan, scope & roadmap and the matching workflow before attempting a match.
Want to grind functions automatically? Pair this with decomp-agents.
The original .exe files belong only in your local install — never git add them.

decomp-agents

Parallel autonomous Claude agents that grind the decomp.

View on GitHub

Tooling

Python

AGPL-3.0-or-later

Spawn 1–8 parallel Claude agents that grind through meteor-decomp's per-function matching loop. Each worker runs in its own git worktree, claims functions from a shared SQLite queue, and merges completed branches back automatically.

Before you start

Python ≥ 3.11 (with uv or plain pip).
A working meteor-decomp checkout at ../meteor-decomp/ that has already run make split BINARY=<X>.exe for your target binary.
The meteor-decomp build toolchain (Wine + MSVC 2005) working, so make diff can grade matches.
Claude authentication: either a Pro/Max subscription via the Claude Code CLI, or a metered ANTHROPIC_API_KEY.

Walkthrough

Clone and install

Uses uv or plain pip — either works. The cp .env.example .env gives you the config file the orchestrator reads on startup.

cd server-workspace/decomp-agents
uv venv && source .venv/bin/activate
uv pip install -e .          # or:  pip install -e .
cp .env.example .env

Configure your .env

The orchestrator is driven entirely by environment variables read from .env. Open the file you just copied and set the handful that matter most — the full table is in the project Overview.

# Auth path: "subscription" (Claude CLI OAuth) or "api_key" (metered)
DECOMP_AUTH_MODE=subscription
# ANTHROPIC_API_KEY=sk-ant-...   # only when DECOMP_AUTH_MODE=api_key
DECOMP_AGENT_WORKERS=5           # parallel workers, 1–8
DECOMP_REPO=../meteor-decomp     # path to your meteor-decomp checkout
DECOMP_BINARY=ffxivgame          # which binary to grind

Authenticate Claude — subscription (no per-token billing)

One-time OAuth via the Claude Code CLI. Credentials land in the macOS Keychain and every worker subprocess picks them up automatically.

claude              # opens browser; sign in once
claude /status      # confirm "Logged in via subscription"
unset ANTHROPIC_API_KEY    # make sure no key shadows OAuth

…or authenticate with a metered API key

Pay-as-you-go alternative — roughly $0.10–0.50 per attempted function. Get a key from the Anthropic console, set DECOMP_AUTH_MODE=api_key, then:

echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Prime meteor-decomp for the agents (recommended)

Run this inside your meteor-decomp checkout to dump Ghidra's pseudo-C so workers get a structural hint per function. Without it they work from raw asm only and the match rate drops.

make decompile-headless BINARY=<X>.exe

Dry-run to provision worktrees and the queue

Sets up the per-agent worktrees and the SQLite claim database without spawning any agents.

python orchestrator.py --dry-run

Run the orchestrator for real

Spawns the workers using the settings from your .env.

python orchestrator.py
# or via the installed console script:
decomp-agents

Inspect what happened

The coordination SQLite DB records every claim, outcome, and merge.

sqlite3 output/coordination.sqlite "
  SELECT outcome, COUNT(*) FROM claims
  WHERE released_at IS NOT NULL
  GROUP BY outcome;"

macOS: Subscription OAuth credentials are stored in the macOS Keychain and inherited by every worker subprocess.

Where to next

This tool drives meteor-decomp — set that up first and confirm make split ran.
Ctrl-C cleanly stops every worker and flushes a final merge pass.
Read the full Overview for distributed (fork + GitHub claim) mode and every DECOMP_* env var.

XIV 1.0 Apple Silicon Installer

One-command FFXIV 1.0 install for Apple Silicon Macs.

View on GitHub

Installer

Shell

MIT

Bring the original FINAL FANTASY XIV 1.0 up on an Apple Silicon Mac with a single command. Given your retail install disc or ISO, install.sh provisions a self-contained Wine runtime and drives the stock installer through to a playable ffxivboot.exe.

Before you start

An Apple Silicon Mac running macOS.
Your own FINAL FANTASY XIV 1.0 install disc, or its ISO mounted under /Volumes/, with ffxivsetup.exe at the root. The client is NOT redistributed — you must supply it.
Rosetta 2 — installed automatically by the script if missing (the bundled Wine engine is x86_64).
Internet access on the first run, for the wrapper template and Wine engine downloads.

Walkthrough

Clone the repository

git clone https://github.com/swstegall/XIV-1.0-Apple-Silicon-Installer.git
cd XIV-1.0-Apple-Silicon-Installer

Mount your 1.0 disc or ISO

Double-click the 1.0 .iso in Finder (or insert the disc). The script scans /Volumes/*/ for ffxivsetup.exe, so there are no path arguments to pass.

Run the installer

The script runs unattended — downloading the Sikarugir Frameworks and CrossOver Wine engine into target/runtime/, staging the disc into target/iso/disc1/, and provisioning the Wine prefix — until the InstallShield GUI appears.

./install.sh

Click through the InstallShield GUI

When the graphical installer appears, accept all defaults. In particular leave the install path at C:\Program Files (x86)\SquareEnix\FINAL FANTASY XIV so the verification step can find the expected file layout. Re-running install.sh skips any step whose output already exists, so a failed run resumes cleanly.

Wait for "Install verified."

The script confirms ffxivboot.exe, ffxivupdater.exe, ffxivconfig.exe, and the expected data/ / client/ archive layout before declaring success.

Launch the game

The install ships an env file, wine-env.sh, that you source to activate the local Wine — it exports WINEPREFIX, WINE, WINESERVER, and the library paths the bundled engine expects. Source it from any shell, then run the boot binary.

cd target
source ./wine-env.sh
"$WINE" "$WINEPREFIX/drive_c/Program Files (x86)/SquareEnix/FINAL FANTASY XIV/ffxivboot.exe"

macOS: Everything installs under `./target/` next to the script — no Homebrew, no `/usr/local`, no admin rights. Deleting the repository removes the install.

Where to next

Install done? Drive it against a private server with Garlemald Client, which auto-detects this install.
Stuck? The project Overview has a troubleshooting table for the common disc-discovery and Rosetta errors.
Questions? Join the Discord.

Stuck on a step?

The community is the fastest way to get unblocked. Ask questions, share progress, or report a bug on the Discord.

Join the Discord