Migration scripts: a guide?

[dingbat91]

Hey there again! starting to feel rather the idiot putting two posts up within around 10 minutes

I was wondering if someone could give me information on writing a migration script so I can reload recipies into peoples save games?

I can find scraps of information but nothing concise enough to follow to create one.

[slay_mithos]

The most concrete answer I could find was this:
https://forums.factorio.com/forum/vie ... 797#p21711

[dingbat91]

that's great, I've managed to figure it out through reverse engineering another mods.

but now I've got no idea how to get the script to trigger on loading a saved game? I can't seem to find any calls for the script within the mods code. :S

[slay_mithos]

Edit by kovarex: This is actually misleading and in the next post it is described correctly.

It' actually pretty easy, in your control.lua

Code: Select all

game.onload(function()
YOUR CODE HERE, WITH THE CHECKS?
end
)

An other way to do it is to provide a function for a console call instead of doing it at every single load, still in your control.lua

Code: Select all

remote.addinterface("YOUR_MOD_NAME", {
	checkunlocks = function(){
		YOUR MIGRATION CODE HERE
	}
	
})

And ingame, the people that need it just need to type the following to trigger it.

Code: Select all

remote.call("YOUR_MOD_NAME", "checkunlocks")

[FreeER]

Migration scripts, from my understanding, are 'marked' (word choice?) in the save after they've been applied, and when a save is loaded Factorio checks if there are any existing migration scripts that are have not yet been 'marked' in the save, if so they are applied and marked during the loading of the save (or prior, not entirely sure which but it doesn't really matter to us lol). All migration scripts are placed in a folder in the mod called "migrations".

There are two different types of migration scripts, defined by whether it's file extension (the letters following the (last) '.' in the file name, usually only 3 or 4 letters), are 'json' or 'lua'. You can not run lua commands (ie. game.reloadscript(), game.player.force.resetrecipes(), etc.) from a json script, though you can have a json and a lua migration with the same 'name' (if you do not think of the extension as part of the name ).

json migration scripts: are used when items or entities have been renamed and you want any of the old-named entities/items in a player's save to be replaced with the new-named ones (without a migration script they simply disappear, I think...don't quote me on this part lol)
the json migration format is

Code: Select all

{
  "first-type": --as far as I know the types are "entity", "item", and "tile"
  [
    ["first-old-name", "first-new-name"],
    ... (other migrations here)
    ["last-old-name", "last-new-name"]
  ],
  ... --other type(s) here
  "last-type":
  [
    ["first-old-name", "first-new-name"],
    ... (other migrations here)
    ["last-old-name", "last-new-name"]
  ]
}

Also note, I do not think that '--' actually counts as a comment in json files (if you know of a way to leave comments in a json file please let me know )

lua migration scripts: are used for any lua commands such as reloading the script (game.reloadscript()), resetting recipes and technologies (game.player.force.resetrecipes() and game.player.force.resettechnologies()) as well as enabling newly added technologies (and recipes) that are 'between' the technologies in the last release (such as the passive logistic provider chests in 0.9.4).
I believe (but I am not 100% certain) that lua migration scripts can also access and modify the glob table (so if you previously had a glob.whatever variable that stored an integer and you needed to change it to be a table of integers you could use 'if glob.whatever then glob.whatever={new_index=glob.whatever} else glob.whatever={new_index=default_value} end'.
the lua migration format is exactly the same as the control.lua.

@Devs/modders, if you can add/correct anything I've stated let me know and then I'll post this up on the wiki, because if this post is our best resource for information on migrations then we've been forgetting/ignoring it for far too long

[Reygan]

Migration scripts, from my understanding, are 'marked' (word choice?) in the save after they've been applied, and when a save is loaded Factorio checks if there are any existing migration scripts that are have not yet been 'marked' in the save, if so they are applied and marked during the loading of the save (or prior, not entirely sure which but it doesn't really matter to us lol).

...

Ok, cool. Is that mean, if i just rename migration file instead of creating new one, game will execute it anyway?

[FreeER]

Ok, cool. Is that mean, if i just rename migration file instead of creating new one, game will execute it anyway?

Basically, though you will have to restart Factorio before it will be seen. Be aware however that if you were sharing a mod you'd really want to create new ones so that even if people didn't update for two or three mod versions they'd have the needed migration files when they did

[Reygan]

Ok, cool. Is that mean, if i just rename migration file instead of creating new one, game will execute it anyway?

Basically, though you will have to restart Factorio before it will be seen. Be aware however that if you were sharing a mod you'd really want to create new ones so that even if people didn't update for two or three mod versions they'd have the needed migration files when they did

Of course, but at the first i have to post at least the first version of my mod

[Reygan]

Ok, cool. Is that mean, if i just rename migration file instead of creating new one, game will execute it anyway?

Basically, though you will have to restart Factorio before it will be seen. Be aware however that if you were sharing a mod you'd really want to create new ones so that even if people didn't update for two or three mod versions they'd have the needed migration files when they did

Well, then if mod have more then one migration script, which one will execute? Or in which order, if alltogether?

[FreeER]

Well, then if mod have more then one migration script, which one will execute? Or in which order, if alltogether?

All of the migrations that have not already been marked in the save will run (sequentially I believe)...as for the order, I'm not 100% sure right now, but I would assume based on the creation date of the script.

[Reygan]

Well, then if mod have more then one migration script, which one will execute? Or in which order, if alltogether?

All of the migrations that have not already been marked in the save will run (sequentially I believe)...as for the order, I'm not 100% sure right now, but I would assume based on the creation date of the script.

Or in aphabet order, may be.

[SpeedyBrain]

What can I do when an entity type was replaced with another type.
E.g.
Old:
type=container
name=example
New:
type=cargo-wagon
name=example

If you try to load a map where an entity {container,example} is placed on the map the game will say that the map is corrupted.
I couldn't find a way to delete this entity or tell the game that the type changed....

[SpeedyBrain]

What can I do when an entity type was replaced with another type.
E.g.
Old:
type=container
name=example
New:
type=cargo-wagon
name=example

If you try to load a map where an entity {container,example} is placed on the map the game will say that the map is corrupted.
I couldn't find a way to delete this entity or tell the game that the type changed....

still a big issue for me
Anyone got a solution?

[L0771]

still a big issue for me
Anyone got a solution?

sorry, see my mod, v 0.3.0

Code: Select all

{
  "entity":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ],
  "item":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ]
}

cursed-exchange-1 is the old entity and old item.

[SpeedyBrain]

still a big issue for me
Anyone got a solution?

sorry, see my mod, v 0.3.0

Code: Select all

{
  "entity":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ],
  "item":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ]
}

cursed-exchange-1 is the old entity and old item.

Doesn't work for me because I'm not changing the name! I am changing the entity type!

[ratchetfreak]

still a big issue for me
Anyone got a solution?

sorry, see my mod, v 0.3.0

Code: Select all

{
  "entity":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ],
  "item":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ]
}

cursed-exchange-1 is the old entity and old item.

Doesn't work for me because I'm not changing the name! I am changing the entity type!

you can change the name and let localization make it seem the same name

[SpeedyBrain]

still a big issue for me
Anyone got a solution?

sorry, see my mod, v 0.3.0

Code: Select all

{
  "entity":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ],
  "item":
  [
    ["cursed-exchange-1", "cursed-exchange"]
  ]
}

cursed-exchange-1 is the old entity and old item.

Doesn't work for me because I'm not changing the name! I am changing the entity type!

you can change the name and let localization make it seem the same name

that would remove the old entities and I don't want that. (they are quite expensive to make )

[L0771]

Doesn't work for me because I'm not changing the name! I am changing the entity type!

The code don't uses the type of entity, is only "entity", isn't important if are a radar, pipe, boiler... is a entity...
But i don't know if it's true

[SpeedyBrain]

Doesn't work for me because I'm not changing the name! I am changing the entity type!

The code don't uses the type of entity, is only "entity", isn't important if are a radar, pipe, boiler... is a entity...
But i don't know if it's true

I'm going to do some testing in the next days...

[HeilTec]

Let's use the wiki - https://forums.factorio.com/wiki/inde ... on_scripts

If we work on this together that will become the guide.

(Just added "Enable recipes")