Concepts
Config versions
Immutable snapshots of every rule, skill, coin payout, and item. Buddies pin to a snapshot so their world never shifts unexpectedly.
Drafts are your working copy. Publishing freezes them. Each buddy carries a
config_version_id that the rule engine loads
on every event. Migration is explicit — you decide when a buddy moves to a
newer version.
Why versions exist
Without versioning, tweaking a coin payout silently changes every live buddy's behaviour. With it, you can always explain exactly why a buddy did what it did.
Example
Bump
lesson_completedfrom +10 → +25 coins in the draft. Publish. New eggs hatch pinned to v12. Existing buddies stay on v11 until you migrate them.
How to work with drafts
- Make changes freely — they land on the draft.
- Review the diff under Publish before flipping it live.
- Migrate buddies in bulk or individually when you're ready.
Lifecycle
- Draft — your working copy, mutable.
- Published — immutable; new buddies pin to it.
- Archived — old snapshot still valid for pinned buddies, no longer available for new pins.
Gotchas
- Migration swaps the rulebook, never the state. Coins, badges, streak counters all carry over when a buddy moves to a new version.
- Archiving a version doesn't migrate its buddies; they keep running under the old snapshot until you explicitly move them.
- Preset changes from Hatched itself land as a new version for your customer — they never silently modify your draft.