A cross-platform .NET 10 console tool that reads Pathfinder: Kingmaker save files (.zks) and exports character builds, equipment, spellbooks, inventory, kingdom statistics, settlements and explored locations as human-readable text and structured JSON.
This project is complete. Version 1.17.1 is the final release and no further development is planned. It is published as-is under the MIT License; feel free to fork it.
- Latest release with prebuilt binaries: GitHub Releases
- Version history: CHANGELOG.md
- Blueprint database built from game version 2.1.4 (the last Kingmaker release)
- Name, race, alignment and classes with archetypes and levels (custom names shown alongside the blueprint name)
- Base attributes (Str, Dex, Con, Int, Wis, Cha): character creation values plus level-up increases
- Skills: allocated ranks for all 11 skills (Mobility, Athletics, Stealth, Thievery, Knowledge Arcana/World, Lore Nature/Religion, Perception, Persuasion, Use Magic Device)
- Level-by-level build history: feats, class features and selections taken at each level, with parameters (e.g.
Weapon Focus (Fauchard),Metamagic (Extend Spell)) - Equipment
- Active weapon set (or all 4 weapon sets with
IncludeAllWeaponSets) - Body, head, neck, belt, cloak, rings, bracers, gloves, boots
- Quick slots (potions, scrolls, wands, rods)
- Equipment types in brackets (
[Fauchard],[Fullplate],[Tower Shield],[Ring],[Belt]) - Enchantments inline (
Enhancement +3, Corrosive, Destructive) - Optional full item descriptions
- Active weapon set (or all 4 weapon sets with
- Spellcasting for every spellbook a character has
- Caster level and spell slots per day, including cleric domain slots (
2 slots + 1 domain slot) - Known spells by level and domain spells listed separately
- Spontaneous casters (Bard, Sorcerer), prepared casters (Wizard, Cleric, Paladin, Ranger, Druid, Alchemist)
- Caster level and spell slots per day, including cleric domain slots (
Note on values. The save file stores base values only. Attributes and skills are shown as base + level-up points, without racial, size, class, item or buff modifiers. The game recomputes final values on load, so the in-game character sheet will show higher numbers.
- Kingdom name, alignment, days since founding, gold, build points, unrest level
- All 10 kingdom stats (Community, Loyalty, Military, Economy, Relations, Divine, Arcane, Stability, Culture, Espionage) with value and rank
- All 10 advisor positions with the assigned advisor,
(Vacant)or(Locked) - Optional
BPPerTurnoverride, because the save only stores base BP income
- Personal chest (shared stash) and shared party inventory in one report
- Items categorised as Weapons, Armor & Shields, Accessories, Usables, Other
- Equipment type, enchantments, stack counts (
x17) and optional descriptions - Alphabetical within each category; equipped items are excluded
- Every settlement with region, level (Village/Town/City), claimed status and finished buildings
- Artisans per claimed settlement: building unlocked, tiers unlocked (of 6), help-project events, production timeline, current and previous crafted items
- List of all explored world-map locations
- Six text reports and six JSON files (see Output), plus one combined
CurrentState.txt/CurrentState.json - Character ordering and exclusion by name pattern
- Every section can be switched off in
appsettings.json
- Download the archive for your platform from Releases and extract it.
- Run it:
- Windows: double-click
PathfinderSaveParser.exe - Linux / macOS:
chmod +x PathfinderSaveParser && ./PathfinderSaveParser
- Windows: double-click
- Reports are written to the
Output/folder next to the executable and echoed to the console.
dotnet run --project PathfinderSaveParserRequires the .NET 10 SDK.
- If
player.jsonandparty.jsonexist inSavedGame/, they are used directly. - Otherwise, if a
.zksarchive is inSavedGame/, it is extracted and used. - Otherwise, the parser looks in the game's save directory (
PathfinderSaveLocation) and extracts the most recent save, or the one named inDefaultSaveFile.
You can also pass a folder explicitly:
PathfinderSaveParser "C:\Path\To\Folder\With\Saves"Default game save directories:
| Platform | Path |
|---|---|
| Windows | %USERPROFILE%\AppData\LocalLow\Owlcat Games\Pathfinder Kingmaker\Saved Games |
| Linux | ~/.config/unity3d/Owlcat Games/Pathfinder Kingmaker/Saved Games |
| macOS | ~/Library/Application Support/unity3d/Owlcat Games/Pathfinder Kingmaker/Saved Games |
Everything is controlled by appsettings.json next to the executable. The shipped file is:
{
"PathfinderSaveLocation": "%USERPROFILE%\\AppData\\LocalLow\\Owlcat Games\\Pathfinder Kingmaker\\Saved Games",
"DefaultSaveFile": "",
"BPPerTurn": null,
"CleanSavedGameFolder": true,
"ReportOptions": {
"IncludeStats": true,
"IncludeSkills": true,
"IncludeRace": true,
"IncludeClass": true,
"IncludeEquipment": true,
"IncludeSpellcasting": true,
"IncludeLevelHistory": true,
"IncludeKingdomStats": true,
"IncludeKingdomAdvisors": true,
"IncludeInventory": true,
"IncludeUnclaimedSettlements": false,
"IncludeActiveWeaponSet": true,
"IncludeAllWeaponSets": false,
"IncludeArmor": true,
"IncludeAccessories": true,
"ShowEmptySlots": true,
"ShowEnchantments": true,
"ShowFeatParameters": true,
"ShowItemDescriptions": true
},
"CharacterDisplayOrder": [],
"ExcludeCharacters": []
}| Setting | Meaning |
|---|---|
PathfinderSaveLocation |
Game save directory used when SavedGame/ has nothing to parse. Environment variables such as %USERPROFILE% are expanded. |
DefaultSaveFile |
A specific save to use, e.g. "Auto_1.zks" or "Manual_3.zks". If it does not exist, or is empty, the most recently modified save is used. |
BPPerTurn |
Build Points per turn to display. The save stores only base income (no buildings or trade agreements), so null prints Unknown; set a number to print your real value. |
CleanSavedGameFolder |
When true, previously extracted files in SavedGame/ are deleted on every run so the newest save is always re-extracted. .zks archives you placed there are kept. Set to false if you copy player.json / party.json into SavedGame/ by hand. |
| Option | Controls |
|---|---|
IncludeStats |
Ability scores |
IncludeSkills |
Skill ranks |
IncludeRace |
Race line |
IncludeClass |
Classes, archetypes and levels |
IncludeEquipment |
The whole equipment section |
IncludeSpellcasting |
Spell slots, known spells, domain spells |
IncludeLevelHistory |
Level-by-level build history |
IncludeKingdomStats |
Kingdom report and JSON |
IncludeKingdomAdvisors |
Advisor table inside the kingdom report |
IncludeInventory |
Inventory report and JSON |
IncludeUnclaimedSettlements |
Also list regions you have not claimed |
IncludeActiveWeaponSet |
Show the active weapon set |
IncludeAllWeaponSets |
Show all 4 weapon sets, marking the active one |
IncludeArmor |
Body armor slot |
IncludeAccessories |
Head, neck, belt, cloak, rings, bracers, gloves, boots |
ShowEmptySlots |
Print (empty) slots instead of hiding them |
ShowEnchantments |
Enchantments in parentheses after item names |
ShowFeatParameters |
Feat parameters such as weapon type or spell school |
ShowItemDescriptions |
Full in-game item descriptions in equipment and inventory |
Examples:
- Classes only: set
IncludeStats,IncludeSkills,IncludeEquipment,IncludeSpellcasting,IncludeLevelHistorytofalse - Compact equipment view: set
ShowEmptySlots,ShowEnchantments,ShowItemDescriptionstofalse
"CharacterDisplayOrder": ["Melaku", "Regongar", "Harrim", "Tristian", "Jubilost", "Amiri", "Smilodon"],
"ExcludeCharacters": ["Tartuccio"]CharacterDisplayOrder: characters whose name starts with or contains a pattern (case-insensitive) come first, in this order. Everyone else follows alphabetically."Smilodon"matches"Animal Companion Unit Smilodon".ExcludeCharacters: characters matching a pattern are dropped from both text and JSON output.
All files are written to Output/ next to the executable.
| Text | JSON | Content |
|---|---|---|
kingdom_stats.txt |
kingdom_stats.json |
Kingdom name, alignment, days, gold, BP, unrest, stats with ranks, advisors |
inventory.txt |
inventory.json |
Personal chest and shared party inventory, categorised |
all_characters.txt |
all_characters.json |
Every playable character: main hero, companions, animal companions |
explored_locations.txt |
explored_locations.json |
Explored world-map locations |
settlements.txt |
settlements.json |
Settlements, buildings and artisans by region |
CurrentState.txt |
CurrentState.json |
All of the above combined |
JSON output mirrors the text reports and adds type information (weapon and armor types, blueprint categories), so it is suitable for spreadsheets, scripts or other tools.
Note: mercenaries (custom hired characters) have not been tested and may not parse correctly.
=== KINGDOM STATISTICS ===
Kingdom Name: Ушлые земли
Alignment: LawfulGood
Kingdom Days: 1132
Gold: 309 210
Build Points: 1225
Build Points Per Turn: Unknown
Unrest Level: Stable
Kingdom Stats:
Community Value: 156 Rank: 4
Loyalty Value: 221 Rank: 6
Military Value: 249 Rank: 5
Economy Value: 343 Rank: 6
Relations Value: 147 Rank: 5
Divine Value: 119 Rank: 4
Arcane Value: 138 Rank: 5
Stability Value: 174 Rank: 5
Culture Value: 168 Rank: 6
Espionage Value: 85 Rank: 2
Advisors:
Regent Valerie
Counsilor Tristian
General Regongar
Treasurer Jubilost
Grand Diplomat Linzi
High Priest Harrim
Magister Octavia
Warden Capital Kesten
Curator Capital Collector
Minister Ekun
=== CHARACTER BUILD ANALYSIS ===
Character Name: Linzi
BUILD SUMMARY
================================================================================
Stats (base values + level-up allocated points, without racial/class/item/size modifiers): Str 10, Dex 14, Con 14, Int 14, Wis 10, Cha 18
Skills (allocated points, without racial/class/item/size modifiers):
Mobility: 3
Stealth: 8
Thievery: 17
Knowledge (Arcana): 11
Knowledge (World): 10
Lore (Religion): 1
Perception: 17
Persuasion: 2
Use Magic Device: 16
Race - Halfling Race
Alignment - Chaotic Good
Class - Bard Class 17
LEVEL-BY-LEVEL BUILD HISTORY
================================================================================
Level 1: Extra Performance
Level 2: Canny Observer
Level 3: Lingering Performance
Level 5: Skill Focus Selection, Skill Focus — Trickery
Level 6: Weapon Focus (LightCrossbow)
Level 7: Point-Blank Shot
Level 9: Spell Penetration
Level 10: Combat Trick, Precise Shot
...
EQUIPMENT
================================================================================
Active Weapon Set (Set 1):
Main Hand: Escapist's Crossbow [Light Crossbow] (Shock, Enhancement +3, Speed)
This +3 speed shock light crossbow grants its wielder the ability to cast dimension door spell once per day as a 8th level wizard.
Off Hand: (empty)
Armor & Accessories:
Body : Chainshirt +3 [Chainshirt] (Enhancement +3)
Head : Headband of Alluring Charisma +6 (Charisma 6)
Neck : Clockwork Pendant (Clockwork Pendant Enchantment)
Belt : Belt of Physical Form +4 (Dexterity 4, Constitution 4)
Cloak : Cloak of Resistance +4 (Resistance 4)
Ring 1 : Shelyn's Embrace
Ring 2 : Ring of Protection +5 (Deflection 5)
Bracers : (empty)
Gloves : Trapspringer's Gloves (Thievery 5)
Boots : Boots of Elvenkind (Mobility 5)
Quick Slots (Potions, Scrolls, Rods, Wands):
Slot 1: Wand Of Dominate Animal 50
Slot 2: Potion Of Cure Moderate Wounds
Slot 3: Extend Metamagic Rod
Slot 4: Potion Of Cure Moderate Wounds
SPELLCASTING
================================================================================
Bard Spellbook (Caster Level 17)
------------------------------------------------------------
Spell Slots per Day:
Level 1: 8 slots
Level 2: 7 slots
Level 3: 7 slots
Level 4: 6 slots
Level 5: 6 slots
Level 6: 3 slots
Known Spells:
Level 0: Daze, Resistance, Light, Flare
Level 1: Ear-Piercing Scream, Cure Light Wounds, Hideous Laughter, Summon Monster I, Grease, Feather Step
Level 2: Hold Person, Heroism, Cure Moderate Wounds, Glitterdust, Blur, Rage
...
A cleric spellbook additionally shows Level 9: 2 slots + 1 domain slot and a separate Domain Spells: list.
{
"Name": "Ушлые земли",
"Alignment": "LawfulGood",
"KingdomDays": 1132,
"Gold": 309210,
"BuildPoints": 1225,
"UnrestLevel": "Stable",
"Stats": [
{ "Type": "Community", "Value": 156, "Rank": 4 },
{ "Type": "Loyalty", "Value": 221, "Rank": 6 }
],
"Advisors": [
{ "Position": "Regent", "Advisor": "Valerie", "Status": "Assigned" }
]
}PathfinderKingmakerSaveBuildParser/
├── PathfinderSaveParser.sln
├── README.md / CHANGELOG.md / LICENSE
├── scripts/
│ └── build-releases.ps1 # Self-contained builds for win-x64, linux-x64, osx-x64, osx-arm64
├── PathfinderSaveParser/ # Main console application
│ ├── PathfinderSaveParser.csproj # Version is maintained here
│ ├── Program.cs # Entry point: save discovery, orchestration, filtering/ordering
│ ├── appsettings.json # Runtime configuration (copied to output)
│ ├── blueprint_database.json # Generated GUID → name/type/description database (copied to output)
│ ├── README.txt # End-user instructions shipped with releases
│ ├── Models/
│ │ ├── SaveFileModels.cs # player.json models (PlayerSaveFile, Kingdom, Region, InventoryItem…)
│ │ ├── CharacterModels.cs # Character/progression models
│ │ ├── JsonOutputModels.cs # Output DTOs (*Json: CurrentStateJson, CharacterJson, EquipmentJson…)
│ │ └── ReportOptions.cs # ReportOptions flags and CharacterReport
│ └── Services/
│ ├── RefResolver.cs # Indexes $id and resolves $ref pointers
│ ├── BlueprintLookupService.cs # GUID → name / equipment type / blueprint type / description
│ ├── ItemCategorizationService.cs # Weapons / Armor / Accessories / Usables / Other
│ ├── SaveFileExtractor.cs # Finds and extracts .zks archives
│ ├── SaveFileInspector.cs # File metadata for the console header
│ ├── CharacterParser.cs # EnhancedCharacterParser: builds, stats, skills, level history, formatting
│ ├── EquipmentParser.cs # Weapon sets, armor, accessories, quick slots
│ ├── SpellbookParser.cs # Spellbooks, slots, known and domain spells
│ ├── InventoryParser.cs # Personal chest and shared inventory
│ ├── KingdomStatsParser.cs # Kingdom stats and advisors
│ ├── JsonOutputBuilder.cs # Parsed data → *Json models
│ ├── JsonFileGenerator.cs # Writes the JSON files
│ └── TextFileGenerator.cs # Writes the text reports
├── PathfinderSaveParser.Tests/ # xUnit tests (102 tests)
│ ├── README.md
│ ├── Models/JsonOutputModelsTests.cs
│ ├── Services/
│ │ ├── BlueprintLookupTests.cs
│ │ ├── CharacterParserTests.cs
│ │ ├── ItemCategorizationTests.cs
│ │ ├── JsonOutputBuilderEnchantmentTests.cs
│ │ └── TextFileGeneratorTests.cs
│ └── Integration/CompleteWorkflowTests.cs
├── BlueprintBuilder/ # Regenerates blueprint_database.json from a game blueprint dump
│ └── Program.cs
└── Blueprints2.1.4/ # Blueprint dump (not in the repository)
At runtime the application creates SavedGame/ (extracted saves) and Output/ (reports) next to the executable.
- .NET 10 SDK (Visual Studio 2022 17.14+, VS Code or Rider optional)
dotnet build PathfinderSaveParser.sln
dotnet run --project PathfinderSaveParser
dotnet test PathfinderSaveParser.TestsThe test suite has 102 tests across models, services and integration scenarios. See PathfinderSaveParser.Tests/README.md.
.\scripts\build-releases.ps1 # version read from PathfinderSaveParser.csproj
.\scripts\build-releases.ps1 -Version 1.17.1This publishes self-contained single-file builds for win-x64, linux-x64, osx-x64 and osx-arm64 into releases/ (about 30 MB each; no .NET installation required on the target machine).
blueprint_database.json maps game GUIDs to readable data and is loaded at startup:
| Section | Entries | Content |
|---|---|---|
Names |
47,022 | Blueprint names; includes 2,362 item names, 3,720 spell/ability names, 212 enchantment names and 244 location names taken from the in-game display text |
EquipmentTypes |
2,406 | Weapon, armor and shield types (Longsword, Fullplate, Tower Shield) |
BlueprintTypes |
4,134 | Blueprint class names (BlueprintItemWeapon, BlueprintItemArmor, …) |
Descriptions |
771 | Item descriptions |
Unknown GUIDs are printed as Blueprint_<guid> so they can be looked up by hand.
The current database was built from the game 2.1.4 blueprint dump published in the ArcemiPathfinderKingmakerTools repository.
- Create a folder whose name starts with
Blueprintsin the solution root (e.g.Blueprints2.1.4/). - Put
Blueprints.txtand the blueprint JSON subfolders (Kingmaker.Blueprints.Items.Weapons.BlueprintItemWeapon/etc.) inside it. - Run
dotnet run --project BlueprintBuilderfrom the solution root.
The builder filters out dialog, cutscene, AI and debug entries, normalises names (PowerAttackFeature → Power Attack), extracts equipment types from the weapon/armor/shield JSON, and pulls display names and descriptions from m_DisplayNameText, m_DisplayName, m_EnchantName, Name and m_DescriptionText. The result is written to PathfinderSaveParser/blueprint_database.json.
Save File (.zks) → SaveFileExtractor → player.json + party.json
↓
RefResolver (indexes $id / $ref)
↓
Character / Equipment / Spellbook / Inventory / Kingdom parsers
↓
JsonOutputBuilder (*Json models)
↙ ↘
TextFileGenerator JsonFileGenerator
$id/$refresolution. Save files reference objects by pointer everywhere (companions, stats, items).RefResolverindexes all$idvalues once and every parser resolves through it. Never read nested save data without resolving first.- Parse once, format twice. Parsers produce
*Jsonmodels; the text and JSON generators only format them. - Resilience. Each character and item is parsed in its own try/catch so one corrupt entry does not abort the whole report.
- Enchantments appear in three shapes in the save:
null, a plain string, or an array of objects; shared inventory usesm_Enchantments.m_Facts[]. All three are handled. - Item categorisation uses, in order: blueprint type from the database,
$typefrom the save, equipment type from the database, then name heuristics.
- Newtonsoft.Json 13.0.4
- Microsoft.Extensions.Configuration (+ Binder, Json) 10.0.1
- System.IO.Compression (built in) for
.zksextraction - Tests: xUnit 2.5.3, Moq 4.20.72
.zksis a ZIP archive containingplayer.json(kingdom, ~1–2 MB),party.json(characters and items, ~5–11 MB), per-area JSON files and fog-of-war PNGs.party.jsonm_EntityData[]holds every entity; only entries with aDescriptor.Progressionare playable characters.- Character names come from blueprints (
Descriptor.BlueprintGUID), withCustomNamefor renamed characters.
No save files found
- Check
PathfinderSaveLocationinappsettings.json, or copy a.zksfile intoSavedGame/. - With
CleanSavedGameFolder: true, manually copiedplayer.json/party.jsonare deleted on start. Set it tofalsefor that workflow. - The console prints where it searched and why extraction failed.
Missing characters
- All companions are found, including those not in the active party. Mercenaries are untested.
- Check the console for per-character parsing errors.
Blueprint_<guid> in the output
- The GUID is not in the database (different game version or DLC content). Regenerate the database from a matching blueprint dump.
Stats look too low
- Expected. See the note under Character Builds: the parser reports base values, not the in-game computed ones.
MIT License. See LICENSE.
This is an unofficial fan tool. Pathfinder: Kingmaker is owned by Owlcat Games and Paizo Inc. This project is not affiliated with, endorsed by, or sponsored by either.
- Owlcat Games for Pathfinder: Kingmaker
- ArcemiPathfinderKingmakerTools for the blueprint dumps
The save structure is specific to Pathfinder: Kingmaker. Pathfinder: Wrath of the Righteous saves are different and are not supported.