❓ FAQ¶
Frequently asked questions for new contributors and modders.
Is This An Official Pioneers Of Pagonia Repository?¶
No.
This is an unofficial community research and documentation project. Pioneers of Pagonia is a trademark of Envision Entertainment GmbH.
The Pagonia Editor that ships with the game lets you author all of it — maps, scenarios, GameDatabase changes — and publish it as a .pak mod; the community wiki on wiki.gg covers using it. This repository complements that editor — a structured GameDatabase reference plus the text / CI / automation and install / deploy / rollback tooling around it.
How Do I Get A Local Copy Of This Repository?¶
Two ways:
- Clone with git:
git clone https://github.com/pagonia-land/Pagonia-Land.git - Download as ZIP: from the GitHub page, click the green Code button → Download ZIP.
Cloning is recommended if you want to pull updates later (git pull). The ZIP is fine if you just want to read along or do a one-off experiment.
Just installing mods? You don't need the repository at all — see Download for the standalone pagonia-manager binary.
Does This Repository Contain The Game Database XMLs?¶
No.
The repository contains documentation and tooling. Extracted game database XMLs stay local under:
Only game-gdb/README.md is committed.
Why Is The game-gdb/ Folder Empty On GitHub?¶
Because the extracted XML files come from the game's .pak files. They are not original project content and should not be published in this repository without permission from the rights holder.
You need your own local game installation and local extraction workflow.
Why Are Generated Files Not Committed?¶
Files under generated/ are derived from locally extracted game data.
That includes:
generated/entities.json
generated/references.json
generated/analysis-summary.json
generated/catalog/
Even though these are generated by our scripts, they still contain structured information from the game database. Keeping them local is the cleaner legal and project-maintenance approach.
How Do I Extract The XML Files?¶
Use the bundled pagonia-paker CLI under tools/pagonia-paker/ — see CLI.md for the exact commands.
Copy the extracted XML files into the matching local package folders:
core.pak -> game-gdb/core/gdb/
decorations1.pak -> game-gdb/decorations1/gdb/
dlc1.pak -> game-gdb/dlc1/gdb/
tools.pak -> game-gdb/tools/gdb/
Known exception (preserve the subfolder):
See Local Setup for details.
What Should I Read First?¶
Start with:
- Local Setup (the Quick Path section at the top is the 10-minute speedrun)
- Glossary
- First Modding Experiments
- Safe Edits
- Worked Examples
- Troubleshooting
What Is A Good First Mod?¶
Good first experiments:
- change one building construction cost amount
- change one unit recruitment cost amount
- trace a production chain without editing
- change build menu sort order
Avoid GUID changes, objective triggers, component deletion, and asset path changes at first.
See Safe Edits.
What Does Validation Do?¶
Validation checks:
- XML parsing
- duplicate entity GUIDs
- unresolved non-null GUID references
- building production recipe links
- recipe resource references
- construction cost resource references
- employment unit references
- unit recruitment cost references
- generated JSON validity, if present
Run:
Why Does Validation Show Warnings?¶
The current local database has known warnings:
- 30 unresolved non-null GUID references (12 references from 2 stable magic-token GUIDs + 18 references from 4 GUIDs left over from the 1.3.1
NoMVP.*cleanup) - 43 production recipes without non-null input/output resources
The exact counts and the reasoning behind each are documented in Validation Baseline — refer to it as the source of truth rather than memorising the numbers, since they shift with each game update. If the counts change after your edit, investigate before assuming the change is safe.
Are Validation Warnings Always Bad?¶
No.
Some warnings can be valid database patterns, templates, deprecated data, map-specific data, or references handled outside the extracted XML set.
Warnings mean "review this", not always "the database is broken".
Can I Publish My Generated Catalog?¶
Be careful.
The generated catalog is derived from extracted game data. The clean default for this repository is not to publish generated data unless permission from the rights holder is granted.
You can use the catalog locally for analysis and modding.
Do I Need The DLC Files?¶
Not always.
For base game research, core is the most important package. However, this repository's current analysis expects all available packages:
If a package is missing, validation may warn about the missing local folder and some package-specific docs or catalogs will be incomplete.
This is about the local extraction for research. Whether you own a DLC is a separate question that matters when you deploy a DLC-targeting mod: the game ships every pak to everyone, but DLC content only takes effect for a player who owns it. If you deploy with pagonia-manager, declare ownership with pagonia-manager expansions set — see Present vs Owned vs Effective.
What Is The Difference Between docs/ And generated/?¶
docs/ contains human-written documentation that can be published.
generated/ contains local machine-generated data derived from extracted game files and is ignored by Git.
What Is The Difference Between REFERENCE.md And generated/catalog/?¶
REFERENCE.md explains how the generated catalog works.
generated/catalog/ is the actual local generated catalog output.
Can I Edit XML Files In game-gdb/?¶
You can edit them locally for experiments, but they are ignored by Git and should not be committed.
Keep backups. Validate after every small change.
Can I Contribute Without Modding The Game?¶
Yes.
Useful contributions include:
- typo fixes
- clearer explanations
- glossary entries
- testing worked examples
- improving scripts
- improving validation
- reporting confusing docs
- suggesting safer first mod examples
See Contributing.
What Should I Include In A Bug Report?¶
Include:
- what you were trying to do
- which doc or script you used
- validation output if relevant
- expected result
- actual result
- game version if known
Do not attach extracted XML files, .pak files, assets, or generated data dumps.
What Happens After A Game Update?¶
The intended process is:
- Replace local XMLs under
game-gdb/. - Run validation.
- Regenerate indexes and catalog.
- Compare counts against Validation Baseline.
- Update docs if structure or behavior changed.