Pedantic double-check: on_configuration_changed() always fires when game version changes?

Place to get help with not working mods / modding interface.
aaron311
Inserter
Inserter
Posts: 21
Joined: Sun Mar 22, 2020 2:30 am
Contact:

Pedantic double-check: on_configuration_changed() always fires when game version changes?

Post by aaron311 »

The (fantastic and very helpful) "Data lifecycle" documentation page says the following about on_configuration_changed():
[5] on_configuration_changed()

This step runs for all mods if the save's mod configuration has changed. The configuration is considered to be different when the major game version or any mod version changed, when any mod was added or removed, when a startup setting has changed, or when any prototypes have been added or removed.
(Emphasis added in bold)

The documentation says "major game version" but I *think* based on pure logic as well as reading of a bunch of old forum threads, any version string change in the 'base' mod (i.e. Factorio itself) will probably trigger the event? Is this correct? In other words, upgrading from 1.1.69 -> 1.1.70 (which most devs would call a 'patch version change') would also trigger the event?

If so, maybe queue up a change to tweak "when the major game version" to "when the game version" (strike the word 'major')?

Thanks for the help! <3
User avatar
boskid
Factorio Staff
Factorio Staff
Posts: 3052
Joined: Thu Dec 14, 2017 6:56 pm
Contact:

Re: Pedantic double-check: on_configuration_changed() always fires when game version changes?

Post by boskid »

From the internal logic of loading save files, on_configuration_changed will be raised for all mods any time any part of the game version is changed, this includes main, major, minor and developer part of the save file format version field. This is because on_configuration_changed will raise every time the save file is being loaded in a "prototypeChangedMode" (using internal names). In a prototypeChangedMode we are allowed to do any non save-load stable changes to the game state because we are guaranteed to have at most one instance of the game at that point in time, replays are invalidated in this case and there are no clients in multiplayer yet. There are multiple reasons when a loading of a save file would go into the prototypeChangedMode:

1/ Save file format is different than current version (MapVersion)
2/ List of active mods (name+version+crc) sorted by dependencies order is different (Mods)
3/ Startup settings are different (ModsStartupSettings)
4/ It is forced by a user (holding Control key while pressing the "Load" button in the Load game gui) (ForcedByUser)
5/ There were migrations applied to a save file since they were not yet applied to it (MigrationApplied)

I do not care about the exact documentation here because it goes into too many details (like what is dependencies order). Only part that is important is that it is not raised when loading without a "prototypeChangedMode" when a save-load stability is expected, which includes cases of a client joining to a multiplayer server (it is assumed client has the same version of everything as the server to be able to keep determinism of simulation) or a replay happening (it is assumed a client playing a replay has the same version of everything as the client that was recording the replay to keep determinism of simulation). By extent this also applies to locally loading a save file without any changes to data so the save file will seamlessly continue without any non save-load stable changes happening during save-load cycle which is required to be able to continue recording replay after save-load.
User avatar
DaveMcW
Smart Inserter
Smart Inserter
Posts: 3717
Joined: Tue May 13, 2014 11:06 am
Contact:

Re: Pedantic double-check: on_configuration_changed() always fires when game version changes?

Post by DaveMcW »

You can use this thread for documentation requests.
aaron311
Inserter
Inserter
Posts: 21
Joined: Sun Mar 22, 2020 2:30 am
Contact:

Re: Pedantic double-check: on_configuration_changed() always fires when game version changes?

Post by aaron311 »

Super helpful, thank you!

@boskid if it's all right with you I might try to distill your detailed answer into a small set of enhancements to be added to the Data Lifecycle documentation page.
Post Reply

Return to “Modding help”