Updating Mods

As with any piece of software, mods are going to have bugs and will require updates. Updating them, however, is quite complicated, if you want saves from previous versions compatible. That’s because of how the game handles game saves.

Loading process

Whenever you load the game, it is first reset by loading so-called “new game save”. It is a save of game state just after the main level was loaded, before any game systems are updated. This save is shipped inside level.pak (if your mod modifies level, use the appropriate tag in mod manifest, which will cause the game to generate newgamesave when started).

This reset is important mostly for game patches, as it resets stuff that wasn’t in previous versions of the game, and therefore is not in the old save. It is however not a bulletproof solution, and care needs to be taken when it comes to some special saved stuff (If you are loading for the first time from main menu, newgamesave is not used. That’s because in the main menu, the game is in the same state as if you just loaded newgamesave. That’s why we had some bugs that only manifested after loading during gameplay).

When the newgamesave is loaded, the selected game save starts loading

First, all streaming profiles, that were streamed in during save, are loaded. They are read from source data every time (this is possible because they are usually very small), so all stuff in them is already in its default state.

Then, all saved stuff is loaded. Most issues with the save/load process comes from two sources: Entities (NPCs, items on ground, interactive objects) and items (in inventories).

Entities

Entities are identified, for the purposes of game save, with their GUIDs. The GUID needs to be unique, and it absolutely needs to be consistent between different mod versions.

<Entity Name=... EntityGuid="443D2CD62B607C24" ...> 

There are two main types of entites, from the perspective of game save:

• Static
  • Defined in level.pak/objects_mission0.xml
  • Always present in game
• Streamed
  • Either spawned entities (random events, forest animals)
    • All parameters are specified by script during spawn
  • OR entities from streaming layers
    • Defined in (level.pak/layers/*.xml), just like static entities

During entity load, one of the three following scenarios can happen:

1. An entity is in level, but not in game save

• This is a new entity added by a patch (otherwise it would be in game save)
• As there is nothing to load, it will remain in its current state (this is why newgamesave is necessary)

2. An entity is in level, and it is in game save

• All saved data is loaded into this entity (e.g. world position)

3. An entity is NOT in level, but it is in game save

• Depending on type of entity
  • A static entity is ignored (if it isn’t present, it was probably deleted during game save)
  • A dynamic entity is spawned (it’s assumed to be spawned entity)

As is evident from 3, if you have an entity in a streamed profile, delete it in new mod version, and then load save from old mod version, the deleted entity will appear in game. The correct way of removing an entity from streamed profile is to move it to new streamed profile, that is marked as “auto-loaded”, and then unload this profile just as the game starts.

Items

Even though items become entities when dropped, they are still saved separately in “Item manager”, along with all items in inventories.

The game fills all inventories when it first loads, and then saves all of these items. If you change any of these inventories with a mod, it won’t manifest in game. There are three exceptions: streamed entities generate their inventories when they are loaded in, “trash” NPCs generate their inventories every time they respawn, and spawned entities generate their inventories when they are spawned. Therefore, unless your mod will require the user to start a new game, you should add items to game with scripts instead of editing the database.

Removing an item in new mod version won’t work for the same reason: it’s already saved in the game, and the saved state takes precedence.