Extending the System Safely

When adding a mechanic, preserve the system's ownership model before adding new detail. Read the target file type, its schema, layout, and representative examples. Then identify the canonical owner, the player-facing choice, the mutable state, the reusable definition, and any value that should be computed rather than stored.

A safe extension process

1. Define the outcome. State what new choice, pressure, or story opportunity the mechanic creates.
2. Choose the owner. Settlement state belongs on the HUD; personal state on Character; templates on Blueprint; permanent geography on Map Area; reusable rules on their definition files.
3. Prefer references. Link to existing types instead of duplicating names, descriptions, and state in several records.
4. Use structured data for rules. Costs, durations, resources, statuses, effects, and progression rows should be typed values where the system needs to read or apply them.
5. Keep prose for meaning. Descriptions explain intent, fiction, tells, limitations, and consequences. They are not a hidden database.
6. Make repetition safe. Any daily, completion, reward, or unlock effect needs a stable event or effect key and an idempotence check.
7. Preserve agency. Mark the point where the player must choose and leave the choice pending until confirmed.
8. Test the edges. Check missing references, empty collections, shortages, repeated ticks, paused projects, failed actions, travel, rank offers, and partial updates.

Computed values and references

Never write a computed field back into a data file. Do not create a second stored copy of HP maximum, settlement income, rank title, research table, housing summary, or another value already derived from canonical inputs. When a definition is referenced, read its content through the platform's reference loading mechanism; a reference identity is not the target file itself.

Use stable keys for rules and conditions. A display name can change, but a key such as an effect or event identifier must remain stable enough to prevent duplicate application. If a mechanic needs a new expression, keep it typed, top-level, and free of presentation strings such as badges, dot glyphs, or prose labels.

Compatibility and migration

Do not casually rename fields, change enum values, or alter the meaning of an existing reference. Existing files are content, not disposable examples. If a schema change is necessary, count affected files, define how stored choices map to the new shape, migrate them deliberately, and verify representative cases. A layout change should bind to the canonical field and make mutable values easy to edit; it should not recreate deleted aliases.

Final review

A finished extension should answer: who owns this state, what is the player allowed to decide, what happens on failure, how does it interact with the daily tick, how is it protected against repetition, and how does it appear at the table? If those answers are unclear, the mechanic is not ready for play. The system is strongest when a small number of reliable records produce many different stories.