Update Your Config Without Losing Player Settings

Understanding Config Versioning

When you add, remove, or change configuration options, increment your config file's version number. This tells VanillaConfig that a migration is needed.

Writing Migration Steps

1. Define a migration function that receives the old configuration data.

2. In the migration, handle key renames by reading old keys and writing to new ones.

3. Provide sensible defaults for any new options players didn't have before.

4. Transform existing values if their format or meaning has changed.

5. Register this migration step with your config builder, specifying which version it applies to.

When a player loads your mod with an outdated config file, VanillaConfig runs all migrations in order until the file matches your current version. This ensures players never lose their settings and the transition is seamless. Test migrations thoroughly by using old config files during development.