Stored data and versions

If you change the format of the data your mod saves, you must convert old data in already saved worlds to the new format. Poly Mod Loader provides the same kind of versions and migrations (DataMigration) for three kinds of stored data.

Stored data	How to set the version
World storage (world.storage)	StorageOptions.DEFAULT.withVersion(version, migration)
Block entity data	BlockEntityDefinition.builder().dataVersion(version, migration)
Entity data (entityData)	EntityDataOptions.DEFAULT.withVersion(version, migration)

World storage

/** In version 2, message is renamed to motd. */
static final StorageOptions WORLD_INFO_OPTIONS = StorageOptions.DEFAULT
        .withVersion(2, (data, fromVersion) -> {        // once, when old-version data is loaded
            if (fromVersion < 2 && data.has("message")) {
                data.putString("motd", data.getString("message", ""));
                data.remove("message");
            }
        })
        .syncedToClients();

StoredData info = world.storage(ResourceId.of("my_mod", "world_info"), WORLD_INFO_OPTIONS);

• Poly Mod Loader records the version in the stored data under poly_version (a reserved key).
• If the data is from an older version, Poly Mod Loader runs the migration.
• If the data is from a newer version (for example, you rolled the mod back to a lower version), Poly Mod Loader leaves the data as it is and logs POLY-STORAGE-001.
• Opening the same storage ID with different options throws IllegalArgumentException. Keep the options in a constant and use the same one.

Block entity data

BlockEntityDefinition.builder()
        .dataVersion(2, (data, from) -> { /* convert old saved data */ })
        .build();

It works exactly like world storage.

Entity data

EntityDataKey MOOD = mod.content().entityData("golem_mood", EntityDataOptions.DEFAULT
        .syncedToTrackers()
        .withVersion(2, (data, fromVersion) -> {
            if (fromVersion < 2 && data.has("feeling")) {
                data.putString("mood", data.getString("feeling", ""));
                data.remove("feeling");
            }
        }));

• For each key, Poly Mod Loader records the version in the saved tree under the reserved key poly_version.
• Data added with /data merge goes through the same conversion.

How to write migrations

Compare with fromVersion and convert step by step (if (fromVersion < 2) …, if (fromVersion < 3) …). Then even very old data becomes the latest format in order. You can verify migrations with game tests.

World backup

Poly Mod Loader automatically backs up a world before loading it if mods were removed or their versions changed. See Operations.