Builder Guide

Upgrading an Existing Project

Add current project metadata safely, preserve save identity, and validate an older game before continuing development.

2 min read First Steps upgrade saves compatibility migration

An Ichiloto save screen showing multiple save slots in the terminal. — Upgrade metadata protects the relationship between a changing game and the saves players already own.

Older Ichiloto projects may be missing metadata needed to protect current saves. Preview the required changes from the project directory:

ichiloto upgrade --dry-run

If the report looks correct, apply them and validate the result:

ichiloto upgrade
ichiloto validate

The upgrade command adds missing mandatory metadata. It does not rewrite the game's maps, actors, dialogue, or other authored content.

Keep the project identity stable

The id in ichiloto.json permanently identifies the game that owns a save. Once production saves exist, do not change it. A save from one game should never be accepted as though it belonged to another.

If an older project needs an explicit identity, supply the permanent vendor/project value during the upgrade:

ichiloto upgrade --id=my-studio/my-rpg

Choose that value deliberately. It should remain stable even when the game's display name or release version changes.

Commit the compatibility manifest

Keep assets/Data/save-compatibility.php in source control. The manifest gives the project an explicit place to describe its content version, sequential migrations, aliases for renamed content, and tombstones for content that no longer exists.

Do not reuse a retired actor, item, quest, map, or other persistent identity for new content. Use an alias when an identity was renamed, and a tombstone when the old content has no replacement.

Run ichiloto validate after changing compatibility metadata. It checks that versions are reachable in sequence and that aliases, tombstones, and saved content references form a coherent upgrade path.