🛠️ Local Setup¶

This guide gets you from a fresh checkout to a validated, browseable local copy of the Pioneers of Pagonia game database — everything you need to analyse the data or build your own mods.

First time here? Get a local copy of the repository

The instructions below assume you have this repository on disk.

Clone with git (recommended if you'll update later): git clone https://github.com/pagonia-land/Pagonia-Land.git
Download as ZIP (no git needed): on github.com/pagonia-land/Pagonia-Land click the green Code button → Download ZIP → unzip anywhere.

Just want to install mods? You don't need to clone anything — grab the pagonia-manager binary from the Download page.

Quick Path¶

For readers who want the speedrun, here's the whole flow as a checklist. Each step links to the section below with the full command and explanation.

Check prerequisites — game install, PowerShell, optionally git + ripgrep.
Extract the game database XMLs into game-gdb/.
Run validation — baseline is 0 errors / 2 warnings.
Generate local indexes — JSON index files under generated/.
Generate the local catalog — browseable Markdown.
Read one example — sawmill trace or a small first edit.

The whole loop is repeatable: after a game update or a local edit, run validate → analyze → catalog again.

Scope¶

The Pagonia Editor that ships with the game lets you author all of it — maps, scenarios, and GameDatabase changes (buildings, units, recipes, costs, objectives) — published as .pak mods; the community wiki on wiki.gg covers using it. This repository complements that editor — the GameDatabase reference and the text / CI / automation + install / deploy / rollback tooling around those mods.

The repository contains documentation, scripts, local analysis workflows, and modding examples. It does not publish extracted game database XMLs — you bring your own from your own Pioneers of Pagonia installation. Only game-gdb/README.md is committed; the package folders below it stay local.

Prerequisites¶

A local installation of Pioneers of Pagonia.
Access to the relevant .pak files. They ship inside the install under a pak/ subfolder. On a default Steam install that is C:\Program Files (x86)\Steam\steamapps\common\Pioneers of Pagonia\pak\. (In Steam: right-click the game → Manage → Browse local files, then open pak/.)
PowerShell. The local analysis, validation, and catalog scripts below are written for Windows PowerShell (powershell / winget); on Linux/macOS run them with pwsh. The tool binaries themselves are cross-platform — see Downloads.
git, if you want to contribute documentation or scripts.
rg/ripgrep for fast text searches. On Windows:

winget install BurntSushi.ripgrep.MSVC

Repository Layout¶

.
├── docs/
├── game-gdb/
├── generated/
├── scripts/
├── README.md
├── DATABASE_OVERVIEW.md
└── UPDATE_PLAYBOOK.md

The local game database files belong under game-gdb/:

game-gdb/
├── core/
├── decorations1/
├── dlc1/
└── tools/

Extract The Game Database XMLs¶

Extract the XMLs with the pagonia-paker CLI — a single-file binary that lists, unpacks, packs, patches, and classifies .pak archives. Get it either from the Downloads page (a prebuilt binary) or by running it from source with the .NET SDK:

dotnet run --project tools/pagonia-paker/src/PagoniaLand.Paker.Cli -- unpack <pak> <output-dir>

The tools/pagonia-paker/ folder in this repository holds the source, not a ready-to-run binary. See tools/pagonia-paker/CLI.md for the full command reference.

Unpack each .pak into its package folder below game-gdb/. unpack preserves the archive's internal paths, so each pak's own gdb/ folder (and dlc1.pak's maps/ folder) lands in exactly the right place — adjust the install path to yours:

$pak = 'C:\Program Files (x86)\Steam\steamapps\common\Pioneers of Pagonia\pak'
pagonia-paker unpack "$pak\core.pak"         game-gdb\core
pagonia-paker unpack "$pak\decorations1.pak" game-gdb\decorations1
pagonia-paker unpack "$pak\dlc1.pak"         game-gdb\dlc1
pagonia-paker unpack "$pak\tools.pak"        game-gdb\tools

This produces the canonical layout:

Pak file	Local target folder
`core.pak`	`game-gdb/core/gdb/`
`decorations1.pak`	`game-gdb/decorations1/gdb/`
`dlc1.pak`	`game-gdb/dlc1/gdb/`
`tools.pak`	`game-gdb/tools/gdb/`

General rule: every file from the gdb/ folder inside each .pak ends up in the matching folder below game-gdb/. Relative paths are preserved exactly — file names contain spaces and that's intentional.

Known exception: dlc1.pak carries meadowsong map database.gd.xml under a maps/ subfolder rather than gdb/. The unpack step above preserves that automatically — the file ends up at:

dlc1.pak maps/meadowsong map database.gd.xml -> game-gdb/dlc1/maps/meadowsong map database.gd.xml

This is the only XML file in the shipped database that lives outside the canonical <pak>/gdb/ layout. Future Meadowsong-style DLCs are likely to keep using <pak>/maps/ for scenario databases — see Quirks And Anomalies → Only one file lives outside <pak>/gdb/.

Validate The Local Database¶

From the repository root:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\validate_database.ps1

Baseline is 0 errors / 2 warnings — see Validation Baseline for the expected warning samples. If validate prints more than that, a recent edit or extraction introduced something new.

The validation script checks:

required local package folders
XML parse errors
duplicate entity GUIDs
unresolved non-null GUID references
building production recipe links
recipe input/output resource references
building construction cost resource references
employment unit references
unit recruitment cost resource references
source recruitable unit references
generated JSON validity, if those files exist

Null GUIDs such as 00000000-0000-0000-0000-000000000000 are treated as empty/default references, not as broken links.

Generate Local Indexes¶

After placing the XML files under game-gdb/, run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\analyze_database.ps1

This creates local JSON files under generated/:

generated/entities.json
generated/references.json
generated/analysis-summary.json

All ignored by Git because they're derived from local game data.

Generate The Local Catalog¶

To create Markdown / CSV / Mermaid overviews for buildings, production recipes, units, construction costs, workers, timing hints, and relationship graphs:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\generate_catalog.ps1

This creates browseable files under generated/catalog/:

generated/catalog/README.md
generated/catalog/buildings.md
generated/catalog/building-dependency-matrix.md
generated/catalog/building-production.md
generated/catalog/recipes.md
generated/catalog/units.md
generated/catalog/unit-equipment-matrix.md
generated/catalog/localization-index.md
generated/catalog/objective-flow.md
generated/catalog/filters/package-summary.md

This is the fastest way to browse buildings, units, recipes, costs, workers, production links, text/localization keys, and objective flow rows. See Generated Database Reference for the full catalog layout.

Read One Example¶

Once the catalog is generated, try one of these to get a feel for the data:

Trace The Sawmill Production Chain — read-only walkthrough across multiple files.
Change A Building Construction Cost — small, safe first edit.

Recommended Workflow¶

The same loop applies to game updates, modding experiments, and re-syncing after a pull:

Update or replace XML files under game-gdb/.
Run scripts\validate_database.ps1.
Run scripts\analyze_database.ps1.
Run scripts\generate_catalog.ps1.
Read generated/analysis-summary.json and the files under generated/catalog/.
Update documentation if structure, counts, or behavior changed.
Commit only documentation and scripts, not extracted game files.

Don't Commit Local Game Data¶

Before committing anything, check:

git status --short --ignored

It is normal to see ignored folders like:

!! game-gdb/core/gdb/
!! generated/catalog/

Do not force-add them. The following are ignored by .gitignore and should stay that way:

game-gdb/core/gdb/
game-gdb/decorations1/gdb/
game-gdb/dlc1/gdb/
game-gdb/tools/gdb/
generated/*.json
generated/catalog/

Useful Commands¶

The game-gdb/ folder is ignored by Git, and ripgrep respects ignore rules by default. Use --no-ignore when searching local game files from this repository.

List XML files:

rg --no-ignore --files .\game-gdb -g "*.xml"

Count XML files:

(Get-ChildItem -LiteralPath .\game-gdb -Recurse -File -Filter *.xml).Count

Find an entity or component by text:

rg --no-ignore "FirewoodFromSoftwoodRecipe|AspectProduction|ResourceDescription" .\game-gdb

Find a GUID:

rg --no-ignore "f01e0070-4661-4c00-8b74-e240f8bd5c3f" .\game-gdb

Different Goal: Installing Mods Instead?¶

The flow above prepares the repository for analysing the game database and building your own mods.

If your goal is to install mods (yours or someone else's) into a real game install, see tools/pagonia-manager/. The manager handles mod stores, profiles, planning, deploys, and rollbacks. Run it with no arguments for an interactive menu, or pass --help for the scripted CLI surface.

Next Reading¶

If this worked, continue with: