Description

[version 1.8.12 is required] SaveLoad built-in controller prevents new rows, added to default database, from removal while loading data with SaveLoad addon for tables with "Remove orphaned" parameter on. If your game is not publicly available, there is no problem (just yet), cause there are no saved games, but if you want to be able to add new rows to default database after public release for the tables with "Remove orphaned" parameter on, please, read this article

Problem description

When table has "Remove orphaned" parameter on, it's not possible to add new rows to the default database, cause these rows are deleted after game loading.

Here is an example from our 3d example project, Collectables nested table has "Add missing" and "Remove orphaned" parameters on,

meaning after loading all rows from default database are replaced with previously saved rows

So, on the screenshot below our initial default database on the top and modified database after some game playing at the bottom. Modified database is saved with SaveLoad addon.

Now let's say we want to add a new scene and add some collectables to it, but unfortunately, after game loading these collectables are removed

This is because the collectables were saved when NewScene did not exist, so how can we prevent NewScene's collectables from removing while game loading? Prior to v.1.8.12, preventing new rows from removal was possible with custom C# row controller, now SaveLoad addon has a builtin controller to address this problem

How to set up built-in controller

1. Create SYS_PROPERTY table, add value field with string type and add a row with name=dbVersion and value=1. We assume, that at this point your game is already publicly available and users already have the saved games, so the initial dbVersion=0 and now we increase it by 1. if your game is not publicly available yet, and you want to simply test this feature, do not forget to revert all dbVersion values to zero after testing (including SYS_PROPERTY.dbVersion)
   
2. Include SYS_PROPERTY.value field to merge settings as shown on the screenshot below
   
3. Now you need to add dbVersion int field to every table with "Add missing" "Remove orphaned" parameters turned on. In our case we have only one Collectables table with these parameters, so we need to add this field to Collectables table. Also, if the table is a nested table, we can also add this field to the parent table, in our case it's a Scene table. Keep in mind, that adding dbVersion to the parent table will affect all nested tables (if they have "Remove orphaned" parameter on), in our case there is only one nested table, so we can safely do this.

   To make sure, the setup is correct, click on the "Check status" button and make sure the builtin controller status is ok and the number of affected tables matches the number of tables with dbVersion field.

   
   For the rows, we want to preserve, we need to set the same dbVersion value as SYS_PROPERTY.dbVersion value, which is currently 1 (it's very important to use the same value)
   
   Now, if you load previously saved game, the new collectables will be preserved
   
4. The 3 steps above is actually enough, but it's worth mentioning, that the same trick will work for all future updates as well. Let's say you released the game update with 3 scenes, and now you want to add 2 more scenes. All you need to do is to increase SYS_PROPERTY.dbVersion by 1, from 1 to 2, and add new scenes with dbVersion=2
   

How built-in controller works

The controller has 2 functions:

1. It prevents SYS_PROPERTY.dbVersion value update while saved data loading. It's a very important step, so SYS_PROPERTY.dbVersion should always be the latest value from default database, so when you save the data, this latest value should be saved.
2. During removal phase of saved data loading, the controller prevents a row removal if the row's dbVersion value is greater than SYS_PROPERTY.dbVersion value from saved data.

This page contains C# code for custom row controller, which uses the same approach