Validate compatibility against Project Zomboid Build 42.20 Stable

[geromet]

Problem

PZTools' public README still says it is updated for Build 42(.14.0) Unstable, while Project Zomboid 42.20 is now Stable (and the official site currently reports 42.20.4). That makes the compatibility claim stale and leaves it unclear which parser/classifier/serializer assumptions have actually been verified against the current game data.

This is not a request to blindly change the version string. First prove compatibility against current Build 42.20 data, then update the claim to match the evidence.

Official current release context:

• https://projectzomboid.com/blog/news/2026/07/project-zomboid-build-42-20-released/
• https://projectzomboid.com/blog/features-overview-build-42-20/

Scope

Run a compatibility pass over current vanilla Build 42.20 distribution inputs:

• Distributions.lua
• ProceduralDistributions.lua
• relevant Distribution_*.lua reference files
• current room/container/distribution forms exercised by the item-picker data

Parser / model

• Parse the full current vanilla corpus without fatal errors.
• Catalogue any new keys/shapes/types that fall through to unknown/default handling.
• Tie specific classification gaps to existing issues where possible (for example Add new Bags/Items that are now defaulted as Room #37 if current bags/items still default incorrectly) rather than duplicating tickets.

Serializer / round trip

• Feed representative Build 42.20 fixtures into Improve Lua serialization — edge cases #36's round-trip matrix.
• Distinguish intentional formatting normalization from semantic/reference/comment loss.
• Do not use a destructive save against the installed game as verification; copy fixtures to isolated test/temp data.

Build-42 mod layout / identifier boundary

Build 42's official migration guidance introduced two compatibility surfaces that should be checked explicitly during the 42.20 pass rather than assumed irrelevant:

1. Versioned mod roots. Build-42 mods use version-specific directories plus common; current engine/runtime reports enumerate paths such as common, 42, 42.13, 42.15 and 42.20. When PZTools discovers or opens mod-owned distribution/reference data, verify which physical root won and retain enough source identity to avoid reading an obsolete sibling version or writing to the wrong tree.
2. Registry/string identifiers. The official 42.13 migration guide introduced the identifier/registry system. Inspect the actual 42.20 loot/distribution corpus for registry-backed or newly namespaced identifiers crossing PZTools' parser/model/classifier/reference-resolution boundaries. Do not invent registry support merely because the migration guide exists: record a smallest real 42.20 fixture first, then route any demonstrated parser/reference gap into the existing canonical seam (Improve Lua serialization — edge cases #36/Add new Bags/Items that are now defaulted as Room #37/Add semantic validation diagnostics for unresolved/unsafe distribution data #67/Add support for creating projects #54 as appropriate).

For mod/project workflows, keep this compatibility evidence separate from project-creation/import ownership: if the required change is choosing/versioning a mod root rather than parsing distribution semantics, feed the evidence into #54/#51 instead of duplicating project-discovery logic here.

Authoritative migration signal:

• https://theindiestone.com/forums/topic/88499-modding-migration-guide-4213/

UI / UX

• Open representative current distributions and confirm labels/types/containers/proc lists remain meaningful rather than merely parseable.
• Surface unsupported/new fields explicitly where dropping them would make an edit unsafe.
• For versioned mod fixtures, make the effective source/version visible enough that a user cannot silently edit an older sibling tree while believing they are editing the active Build-42.20 data.

External comparison signal

The current Build-42.20 PZ mapping-tools loot editor documents additional effective-data concepts such as RoomDef/container mappings, project overrides, selector constraints and unresolved-reference diagnostics. Use it as a comparison checklist, not as a mandate to clone its architecture:
https://github.com/Unjammer/PZ_Mapping_Tools/blob/main/docs/PZ-B42.20-Procedural-Loot-Editor.md

Verification artifact

Record:

• exact tested PZ build/version;
• fixture/file counts and, for mod fixtures, the selected physical version root;
• parser warnings/errors by category;
• any unsupported keys/forms or demonstrated registry/identifier shapes discovered;
• round-trip failures with smallest reproducible fixture;
• version-root resolution checks proving stale sibling roots are not silently selected;
• manual UI checks that cannot yet be automated.

Prefer turning reproducible gaps into existing canonical issues or small new issues rather than leaving a giant undifferentiated compatibility checklist.

Done when

• Current Build 42.20 vanilla distribution data has been parsed and inspected with reproducible evidence.
• A representative Build-42.20 mod/version-root fixture proves the effective common/versioned-source selection behavior relevant to PZTools, or the artifact explicitly demonstrates that this repo never performs that selection.
• Actual 42.20 data has been checked for registry/identifier effects at PZTools' distribution/reference boundaries; any demonstrated gap has a canonical owner rather than speculative duplicate architecture.
• Known unsupported/new structures have canonical issues or documented safe handling.
• Representative serialization round trips are covered under Improve Lua serialization — edge cases #36.
• PZTools' README compatibility statement is updated to the exact build range actually verified, not an assumption.

[geromet]

2026-09-05 authoritative evidence refinement

Bounded external check against current primary/official sources sharpens this package without creating a sibling issue:

• Project Zomboid's live version endpoint and download page currently report Stable 42.20.4 (and Unstable 42.20.4): https://projectzomboid.com/version_announce/ and https://projectzomboid.com/blog/buy-download/
• The Indie Stone's 29 July 2026 release post explicitly says 42.20 moved to the public Stable branch: https://projectzomboid.com/blog/news/2026/07/project-zomboid-build-42-20-released/
• The official Build-42 design description confirms the versioned-mod-root model is real product behavior, not community folklore: a mod may contain roots such as 42, 42.21, 43, etc.; the running build selects the most recent compatible version, while common is shared across versions. Source: https://projectzomboid.com/blog/news/2024/08/tidy-up-time/
• The official 42.13 migration topic explicitly describes the new identifier and registry system introduced in 42.13 and supplies migration/test artifacts: https://theindiestone.com/forums/topic/88499-modding-migration-guide-4213/
• Build 42.20's official feature overview also confirms an in-game mod manager with load-order/dependency/incompatibility concepts, reinforcing that PZTools should call its persisted ordering an editor preview order unless runtime-authoritative ordering evidence is obtained: https://projectzomboid.com/blog/features-overview-build-42-20/

Implementation consequence / routing: keep #65 evidence-first. Do not add speculative registry abstractions merely from the migration guide. First capture a smallest actual 42.20 distribution/reference fixture that crosses PZTools' parser/reference/classifier boundary. If the demonstrated gap is semantic preservation, route it to #36/#37/#67; if it is selecting/retaining the effective versioned physical mod root or preview-order provenance, route it into canonical #51 rather than creating another project/import model.

Negative-control proof worth adding to the eventual fixture harness: construct sibling mod roots whose names imply older/newer compatible versions and prove PZTools either (a) deliberately receives an already-resolved effective root, or (b) selects one according to an explicitly documented algorithm; in either case verify an obsolete sibling cannot silently become the editable/reference source. Pair that with an identifier-containing real fixture and a legacy/plain-identifier control so any parser change is driven by observed 42.20 syntax rather than by the existence of the registry system itself.

No repository code/default/PR mutation in this research pass.