Data Model Guide

Data-Model Guidelines

Essentials

• One central model - Route tool/editor state through a single typed object store, not scattered structs, see references/object-model.md
• Make mutation observable - Edits go through the model so it can notify, undo, and persist, see references/change-notification.md

Object model

• Typed objects - Describe each type by a runtime schema, not a hand-written C struct, see references/object-model.md
• Property set per type - bool/int/float/string/reference/sub-object/buffer/array properties, see references/object-model.md
• Data-driven types - Add a type or property at runtime without recompiling, see references/object-model.md
• Separate metadata from instances - Type/schema lives once; instance data is just values, see references/object-model.md

References & ownership

• Strong = owning sub-object - A parent owns its sub-objects; deleting the parent deletes them, see references/references-and-ownership.md
• Local vs global ids - Local ids inside a file, GUIDs for cross-file/cross-session links, see references/references-and-ownership.md
• Identity vs role - A GUID names a fixed identity; a name/path names a role that late-binds: default to GUIDs, see references/references-and-ownership.md

Prototypes & overrides

• Per-property override bitmask - One bit per property marks local-vs-inherited; sub-object sets track inherited / instantiated / removed children, see references/prototypes.md

Mutation

• Pull vs push - Poll a version number, or register callbacks; avoid notification storms, see references/change-notification.md
• Undo/redo - Record inverse ops or before/after snapshots into an undo journal, see references/undo-redo.md

Persistence

• References serialize by id - Persist ids/GUIDs, re-resolve on load, see references/serialization.md
• Deterministic output - Stable ordering for diff/version control; choose text vs binary, see references/serialization.md
• Save changes or re-spawn from assets - Persist member-level deltas for runtime state, asset references for content; POD serializes by default, see references/serialization.md
• ABI-stable struct evolution - Append fields at the end, add a leading size, never reorder/retype; semantic-version the API, see references/serialization.md
• Snapshots & threading - Publish immutable/copy-on-write versions for readers, see references/snapshots-and-threading.md

Gotchas

• An undo entry that captured a pointer/index breaks once storage moves: capture ids and values, not addresses.
• External side effects (file writes, network) are not undoable; keep them out of the transactional journal.
• A loader that rejects unknown fields cannot open older OR newer files: migrate forward and ignore-or-preserve unknowns.
• Overriding a sub-object in an instance gives it a new id, so references to the prototype's original silently miss: resolve references through the override, don't store the new id everywhere.
• Allowing computed overrides (a property defined as an expression over the prototype's value) drags evaluation order and cycles into the data model: keep overrides concrete values.

Progressive Disclosure

• Read references/object-model.md - Load when defining typed objects, property kinds, or data-driven schemas
• Read references/references-and-ownership.md - Load when linking objects by id, modeling ownership, or handling deletes
• Read references/prototypes.md - Load when adding prefabs/templates/presets: prototype-instance inheritance, per-property overrides, override propagation
• Read references/change-notification.md - Load when making edits observable, batching, or recomputing derived data
• Read references/undo-redo.md - Load when adding transactional edits, undo journals, or redo stacks
• Read references/serialization.md - Load when saving/loading, versioning the format, or migrating old files
• Read references/snapshots-and-threading.md - Load when giving reader threads a consistent view while writers mutate