Migrations that change settings (including type of setting)

[swni]

I'm writing my first real migration script and was looking for some guidance on what I'm doing; I've already looked at e.g. https://lua-api.factorio.com/latest/Migrations.html , but it doesn't say much by way of specifics.

I'm moving some settings from startup settings to runtime-global settings. There are a few different cases I want to handle depending on the previous values of these settings.

1. What is the right syntax for reading / writing these settings from a migration script? Will I even be able to read the old value of the old settings when migrating to a new version that no longer has those settings? What if I reuse the internal names for these settings while changing them from startup to runtime (and what if I change their data type, or allowed range of values)?

2. Are settings stored per-save file, globally, or what? My assumption is that startup settings are global and runtime settings are per-save file, so how does that interact with a migration script which alters their values?

Any tips for handling this situation would be appreciated.

[eradicator]

2) Yes, startup settings are stored "globally", for runtime settings it depends on the setting of "use different mod settings per save".

othersettings.png (19.09 KiB) Viewed 1929 times

1) I don't know. Looking at the doc it looks like there's no explicit support for settings, and json is only for changing names anyway. So if you're lucky then keeping the name of the setting will "just work", unless you also change the type or allowed_values of the settings, in which case you're probably out of luck. lua migrations work at runtime where the old settings would already not exist anymore, so you definetly can't read them from there.

If my speculations above are correct you could try a "transitional" release where both the old and new settings still exist (maybe with a localized "deprecated" suffix for the old ones), but the old settings don't do anything anymore. You could then set the new settings based on the old ones, except for new startup settings because these can not be written by mods. Then a few weeks/month later you can remove the old settings and anyone who doesn't upgrade in time will have to change them manually after that. Hm... nope dammit. As the state of "use different settings per save" is unknown it'd be a mess where the new settings are constantly overwritten even if the user changes them willingly.

[swni]

Maybe a dev knows the answers?

A transitional release was my backup plan if it's not possible to transition directly, but it sounds like even that may not be feasible.

[Rseding91]

You realistically don't/can't migrate the values. Just change your settings and let them be what they are. The game will clamp/fix anything which it loads to be within the new settings valid range.

[swni]

Ok, I guess if I don't migrate the values I don't need to worry about the questions I had. I'll try to come up with some way to print a warning message to the chat console so that users can verify their settings are as desired.

(Because the mod changes terrain generation, it can have effects that are not visible to the user for many hours after they happen, at which point it is infeasible for a user to go back to an earlier save and fix their settings, so I want to be very careful about messing up people's saves in this way.)

[eradicator]

While a transitional release with automatic fixing isn't possible you could still try to have one with manual fixing. I.e. once per savegame you display a small gui and ask the user if he wants to accept/reject what you think should be the correct new values. Then just store a flag in global that this map has been migrated. It's a lot of work for possibly very small gain. In MP the admin you're asking might not even be the one who originally decided the settings.