Reading a nine-million-object world

Summary

What this is

ComfyStewardView parses Valheim world saves for high-player-count community servers and serves the result as a REST API and a browser dashboard. Server stewards use it for the questions that a game console cannot answer: who owns this chest, where did the coins accumulate, which portals are orphaned, whose tombstone is that, which zones are dense enough to lag.

The world it was built against holds 9,155,594 objects in a 1.27 GB file. At that scale the interesting engineering is not the dashboard — it is the parse, and specifically one detail of it.

The problem

Names are not in the file

A Valheim ZDO — the network-replicated object record that everything in the world is made of — stores its prefab as a 32-bit hash of the prefab's name. The name itself is never written to the save. It exists only inside the running game's object registry.

So a parser reading the file cold sees 538325542 and has no way to know it is a grausten wall. Without a hash-to-name dictionary the system substitutes the literal string hash:538325542, and that string then travels everywhere: into the API, into the map, into five separate classifiers that each check for the prefix and give up.

A dictionary had solved this once before, offline. It lived on a drive that no longer exists. A full-depth search of the working tree found exactly one surviving prefab dictionary — freshly extracted from the game assembly by a sibling toolchain, 3,458 entries, generated the same week.

Finding

The evidence did not survive contact with its own data

Wiring the dictionary in was straightforward. Reconciling it against what the codebase already believed was not.

Eight hand-written names contradicted it. Six of those were load-bearing — they were not just labels, they drove classification through hash sets, so a wrong name meant a wrong category for every object of that type. Two of the six were recorded in the project's own handoff notes as confirmed, verified by inspecting object properties.

Those confirmations were re-measured with the shipping parser, reporting the fraction of each hash's objects that actually carried the property in question:

What each hash actually carries corroborates the dictionary instead. Four of the six show health and support on 96–99.9% of their objects — the signature of a building piece. One shows scaleScalar on 98.5%: a scaled world prop, and the dictionary names it a cliff.

The lesson is narrow and worth stating plainly: a property observed without a denominator identifies nothing. Twelve occurrences out of 40,889 is noise wearing the costume of proof. Every identity claim in the system now reports a fraction.

What it cost

Roughly 573,000 objects were misclassified in the deployed application. Item stands were inflated by a factor of four, signs by 40%, and the world appeared to contain 41,651 ballistae. It contains 400.

Removals and reassignments balance exactly — every object dropped from one category was found in another, none lost or double-counted. Signs were the only category with no content-based fallback, so they gained one: the component atlas records exactly one writer for the text field and one for author, nothing else in the game writes either. That rule recovered 577 genuine signs the system had never detected.

Finding

A delta that compared array slots

The system retains a history of ingested saves and reports what changed between them. The comparison keyed on zdo_index — which is the parser's loop counter, the object's ordinal position in the file.

Because the save contains no persistent object identifier, that column is not identity. Comparing it compares array slots. If one snapshot holds N objects and another holds M, “present in B but absent from A” evaluates to exactly the index range N to M − 1: the difference in row counts, attributed to whichever objects happen to occupy the tail of the larger file. One of the two figures is always zero.

Identity is now prefab hash plus position quantised to one centimetre. Two objects cannot occupy the same coordinates, and a placed object keeps its position across saves. The engine also carries a self-check — added minus removed must equal the change in total rows — because about 0.8% of position keys are shared by more than one object, and a change in how many sit at one spot is invisible to a presence-based comparison.

Architecture

Split by cost, not by tier

The obvious reason to move parsing off the serving host would be CPU time. That reason turned out to be wrong, and measuring it produced the more interesting result.

So the split is not about the 47 seconds. It is about keeping gigabytes of disk churn away from the machine running a live game server, and keeping the snapshot history — which grows by 1–2 GB per retained save and gets progressively more expensive to extend — on the workstation, while the server receives only what it serves.

The serving host still parses a save at startup, in about four seconds: roughly twenty endpoints read the in-memory store rather than the database. Only the expensive batch build moved.

One world, several copies

Every save in this environment is a copy of the same world with slight testing drift. They therefore share one world identifier and differ by source and backup id, rather than being modelled as separate worlds. That distinction is not pedantry: splitting them would scatter one world's history into parallel timelines and make the comparison view unable to diff them, which is the only interesting question to ask of two copies.

Operations

Two lanes, and an ordering constraint

Code and data ship separately. The code lane tars a whitelist, builds the image on the target, and polls for readiness. The data lane builds artifacts on the workstation, gates them, and installs them into the serving host's volume.

Both gates fail closed. The publish gate refuses unless the cache was built from the exact bytes the serving host will read — otherwise the database view and the in-memory view would describe different saves. It also refuses a snapshot with no rows, or one with no dictionary version recorded.

The lanes are not commutative. Published data carries corrected names, but the in-memory endpoints come from the serving host's own parse with whatever build it is running. Publishing onto an older build yields a viewer whose map and database disagree — right names in one, wrong in the other. Deploy, verify, then publish.

Reference

Measurements

Everything quantified in this paper, with the world it was measured against.

Limits

What this does not claim

• There is no test suite. No unit tests, no test framework in the build. Verification is a 21-check smoke test against a running daemon plus measured before/after parses. Two of those checks fail on this world because they assert findings specific to an older one.
• Coverage is not total. 129 hashes covering 49,385 objects remain unnamed — modded content and a location namespace the dictionary does not span. An endpoint lists them, so the residue stays visible rather than reading as completeness.
• Deltas are a lower bound on churn. About 0.8% of position keys hold more than one object; a change in multiplicity at those keys is invisible to a presence-based comparison. The engine reports when its own arithmetic fails to reconcile.
• Archived history loses object-level diffing only if pruned. Parquet archives are lossless; the limitation would come from choosing to keep aggregates instead, which this system does not currently do.
• The dictionary is a snapshot of one game version. It names what shipped in 0.221.12. A game update makes it stale, and the symptom is a coverage percentage that drops — which is why coverage is reported on every parse and exposed on the summary endpoint.