Outworld Station save parser (GVAS) — ErpForFactoryGames.OutworldStation.Saves

[ChrisonSimtian]

Per the #309 spike, this is the unblocked path and should go first — the catalogue is stuck behind a .usmap (#318), the saves need nothing.

Outworld Station saves are plain GVAS with tagged properties: field names, type names (StrProperty, StructProperty, ArrayProperty, EnumProperty, …) and full struct/enum paths are all inline. No mappings file, no game-specific container tricks — materially simpler than the Satisfactory v1.2 TOC/Data-Blob work that produced ADR-0014.

Ships as ErpForFactoryGames.OutworldStation.Saves from a standalone repo, per ADR-0029 — blocked on #315 for the actual publish, but development doesn't have to wait.

What's in the file

Verified against a live session (Auto_Save_0097, 17 MB, saved mid-play 2026-08-09):

• Header: GVAS, engine ++UE5+Release-5.4, internal project SpaceSalvageStation
• Per-machine production state: CurrentRecipe, IsProcessing, Process_Progress, Process_Time, EModuleMaxFactoryAmount::Recipe_X_{5,10,25}
• Resource nodes: BP_Asteroid_{Ice,Gold,Titanium,Tungsten,GasPlant}, BP_EnvironmentObject_{Gasplant_Node,..._OreNode}
• Progression ids: 07_ALLOY_PRODUCTION, 10_URANIUM_PROCESSING, 13_NEUTRONIUM_PROCESSING, …

Scope

• Generic GVAS reader: header, then the tagged-property stream. Cover Str/Name/Text, Int/Int64/Float/Double/Bool/Byte, Enum, Struct, Array, Map, Object/SoftObject.
• Strip Blueprint GUID suffixes from property names — fields serialise as GameName_3_0E6C2502453… (_<index>_<32 hex>). The stable key is the prefix.
• Handle the save-set layout: <Session>###<SaveName>.sav (world state), <Session>#DATA.sav (session metadata), and global Blueprints.sav / Progression.sav / Settings.sav.
• Resilience posture from the SatisfactorySaveNet v60 fix: one unparseable value must not abort the whole save. Surface unknown types as warnings and keep going.
• Map into the game-agnostic IFactoryStateProvider port (ADR-0010, ADR-0014) rather than inventing a parallel contract.
• Save-path resolution per ADR-0011: ERP_OUTWORLD_STATION_SAVE_PATH → user setting → appsettings → autodetect %LocalAppData%\OutworldStation\Saved\SaveGames\.
• Round-trip test fixture from a real save, with counts verified against the in-game production overview.

Bonus: this partially unblocks the catalogue

The save names every recipe id actually in use, plus machine and resource-node classes. That's a derived partial catalogue — not authoritative, but enough to prove planner integration while DT_ProcessRecipes stays locked behind #318.

Out of scope

• Reading the DataTables (Decide how to obtain a .usmap for Outworld Station (blocks the catalogue) #318 territory).
• Map / station-topology visualisation.

[ChrisonSimtian]

Landed — erp-for-factory-games/OutworldStation

Working GVAS reader, verified against a live 15 MB late-game save.

Top-level properties	21
Total values	150,901
Warnings	0
Parse time	~740 ms
Trailing bytes	4

It surfaces exactly the planner domain: 965 modules each with CurrentRecipe / IsProcessing / Process_Progress / Power_Stored / MaxEfficiency, plus 7,364 Material+Amount pairs, 4,756 storage slots, and 1,392 FromStorage/ToStorage/ToModule conveyor links.

The format work

UE 5.4 changed the tagged-property layout in two ways that break every UE4-era GVAS reader. Neither is guesswork — both were derived from the bytes and are now covered by tests.

1. FPropertyTypeName is recursive. The flat type string became a name plus a parameter list, where parameters are themselves type names:

ArrayProperty
  └─ StructProperty
       ├─ S_Saved_Player
       │    └─ /Game/Save/S_Saved_Player
       └─ <struct guid>

2. One EPropertyTagFlags byte replaced the separate bool and GUID bytes. A bool's value is the BoolTrue flag (0x10), not a body byte. Reading it as the property-GUID flag put every subsequent property in the list one byte out — that single bug accounted for most of the desyncs during development. The same byte's HasBinaryOrNativeSerialize flag is how the reader identifies natively-serialised structs (FTransform, FVector), so their layouts don't need hardcoding.

There's also an undocumented zero byte between the save-game class name and the first property tag, present in all six save files on disk. The reader detects it rather than skipping blindly: a property name's FString length is an int32 whose low byte can't be zero for any name under 256 characters.

Resilience

Delivered as scoped. Every property declares its body size, so the reader seeks to bodyStart + size whether or not the value parsed. An unrecognised type costs that one property and is recorded in GvasDiagnostics as a GvasUnparsed holding the raw bytes — one bad property never costs the file. There's a test asserting exactly that.

Scope status

Done: GVAS reader across all common property types; Blueprint GUID-suffix stripping; save-set layout (### / #DATA / globals); SaveGameLocator with the ADR-0011 precedence chain; resilience posture; 21 tests.

Not done, deliberately:

• IFactoryStateProvider mapping — belongs in the ERP repo, not the library, and wants the catalogue (Decide how to obtain a .usmap for Outworld Station (blocks the catalogue) #318) to name what the recipe ids mean.
• Fixture-based round-trip test — save files are personal data and 15 MB, so none is committed. The real-save test runs when the game is installed and skips otherwise.
• nuget.org publish — blocked on nuget.org account setup: reserve ErpForFactoryGames.* prefix + push API key #315.

[ChrisonSimtian]

Restructured to the ADR-0030 shape, and now produces a real snapshot

The library previously returned a GVAS property tree — a faithful mirror of the save's internals, which is right for a parser and wrong for a consumer: every caller would have to understand Unreal's shapes. It now projects into a StationSnapshot: the small, stable subset the planner reasons about.

Onion-layered per ADR-0030, with the GVAS reader demoted to Infrastructure/Gvas as the binary-format detail it is. The whole CaptureSnapshot use case is unit-tested against fakes — no save file, no parser.

Against a live late-game save

╭───────────┬──────────────┬─────────┬─────────┬───────────╮
│ Zone      │ Location     │ Modules │ Running │ Asteroids │
├───────────┼──────────────┼─────────┼─────────┼───────────┤
│ Alpha     │ AsteroidBelt │     931 │      70 │       290 │
│ BETA      │ GasGiant     │      91 │       0 │        78 │
│ Glacialis │ IcePlanet    │       1 │       0 │       151 │
│ GAMMA     │ AsteroidBelt │      53 │       0 │       527 │
╰───────────┴──────────────┴─────────┴─────────┴───────────╯

1,076 modules, zero parse warnings, and real inventory totals — 39,711 Silica, 34,555 Titanium, and so on. 36/36 tests across the three layers.

Domain modelling decisions

• CurrentRecipe = -1 is the game's idle sentinel; it becomes a null RecipeIndex so the sentinel never reaches the domain.
• Module class is shortened from its package path — /Game/Station/Modules/BP_Module_Hub.BP_Module_Hub_C → BP_Module_Hub.
• Empty storage slots serialise as None/0 and are dropped rather than recorded as zero-quantity entries.

Each is asserted against the real save, so a projection regression fails loudly.

CLI

Ships as the erp-outworld global tool — saves, snapshot, show --materials, show --running, all with --json.

Known gap, and it's the interesting one

CurrentRecipe is an index, not a name. The snapshot can say a module is running recipe 3; naming recipe 3 needs the game catalogue, which is stuck behind the .usmap in #318. So the two halves of this milestone are genuinely coupled — the save parser alone tells you what your station is doing, not what it should be doing.