# Element ids and the CultLib pin (abd1a92e) CultLib 3.0 (unreleased; headless pin `abd1a92e`, `Directory.Build.props`) gives every element of an object list an identity. Every element type reachable through a list of a `[CultDocument]` type carries one string member with `[Key(n)]` and `[CultElementId]`; the registry refuses to open otherwise, naming the type and list. - **Where the slot goes.** A union base takes the member above its subclasses' highest key. `BehaviorData.Id` is key 37, so an array-format behavior is 38 slots on the wire (`PaintModeTests`, `ShipRigTests` pin it). A new `BehaviorData` subclass must keep its keys below 37 or move the slot, which is a wire change. - **Derived ids.** `ShipJoint` and `ShipAnchor` already had a readable `Id`; CultLib refuses a readable id inside a marked member, so each gained a trailing `ElementId` marked `[CultElementId(nameof(Id))]`. - **Minting.** A writer mints random ids for elements that have none. A store written before ids (every file under `GameData/`) loads with ids minted in memory and persists them on its next write; `CultCache.MintElementIds()` does that in one pass. `ElementIdUpgradeTests` opens a copy of the shipped catalog, mints, flushes and reopens it. - **Comparing content.** Random ids differ between two writes of the same content. Tests that compare bytes use `ElementIdBlind`. - **One list element is one object.** The same instance twice in a list is refused (`CultElementIdException`). - **Retyping.** Writing a different type onto a held key is refused unless the record is removed first (`EconomyAuthor.Write` does). ## The bump is one-way A store holding element ids is format v3 (single file) or v5 (directory). The previous pin, `b8fc5eb0`, refuses a v3 store loudly (`NotSupportedException: Store format cultcache.store.v3 is not readable`; checked by Soul on PR 12). CultLib #98 (`7002c252`) records that some intermediate pins read a single-file v3 store silently and drop the ids on the next write. So: upgrade readers before writers, keep a pre-upgrade copy of any real store (`GameData/Aetheria.cc` and the mod packages are tracked in git; player saves and run stores are not), and do not roll the pin back after a store has been written under the new one. Shipped mod packages (`GameData/Mods/*/ship.cc`) hold values in retired `HullData` slots 21 and 22. They read, but the new CultLib refuses to write over them (`CultSchemaConflictException`), so an in-place rewrite of those two files fails until their schema ids are declared compatible or the files are regenerated. A rewritten catalog is about 15% larger: every behavior row is 38 slots, mostly nil. The Unity manifest (`Packages/manifest.json`) still pins `caching-unity-v2.0.0` / `cultlib-unity-v2.0.1`; those move when CultLib tags a Unity release of 3.0. Until then the Unity editor cannot compile `[CultElementId]` (the plugin DLLs at those tags lack the attribute): this branch is headless-only and must not merge to master before a Unity-consumable CultLib exists.