Description

"Modding" addon let you modify default database at runtime after it's loaded (BGDatabase version >= 1.5.5 is required). The main objective is to add support for mods. Localization addon is not supported.

Available methods for modifying database

1. By creating and applying "delta" files (recommended)
2. By changing database using C# API (see examples below)

"Delta" files general concept

The database, shipped with a game/app, is readonly and represents the world state at the beginning of the game. Modders can not change this database directly, but they can create a "delta" files, which modifies this database after it was loaded at runtime. All operations are supported (adding/modifying/deleting)

"Delta" files creation guide

Modders can create delta files using our free BGDatabaseLite package. How to create:

1. Make sure the current database is the database you want to modify (Settings->Main)
2. Enable "delta" mode in Settings->Delta mode
   
3. Once you enabled delta mode, you'll see "Delta mode on" indicator at the toolbar. From now on, all changes you do to the database will be saved to "delta" file and default database will remain readonly. Also, there will be visual feedback which rows was changed/added and additional filter will be added to the toolbar
   
4. You can remove rows from default database and use delta filter's "D"(deleted) button to review them and "Revert" button to restore them. Be very cautious while removing rows from default database, cause game's code may assume the rows exists and may breaks with errors if you remove them.
   
5. Note, the delta mode is on only when play mode is off. Once you press Play in Editor default database will be loaded and delta mode will be off. This is done to simulate real behaviour during runtime. Read next section to learn how to load "delta" files at runtime.

Applying changes to database at runtime

To apply changes at runtime you need to enable Modding addon and create C# class, extending from BGAddonModding.ModdingSourceDefault class. Override Deltas property to provide your own delta files content.

Here is an example:

using UnityEngine;
using BansheeGz.BGDatabase;

    //you can modify database after loading by creating a class,
    //which extends from BGAddonModding.ModdingSourceDefault class
    public class ModdingSource : BGAddonModding.ModdingSourceDefault
    {
        //Override Deltas property to provide Delta files.
        //In our case, we read delta file from bgdatabase_delta.bytes file,
        //located at Resources folder
        public override BGRepoDelta[] Deltas
        {
            get { return new[] {new BGRepoDelta(Resources.Load<TextAsset>("bgdatabase_delta").bytes),}; }
        }
    }

Another example, which scans StreamingAssets folder recursively and returns every single file, which name is bgdatabase_delta.bytes:

using System.IO;
using System.Linq;
using BansheeGz.BGDatabase;
using UnityEngine;

public class ModdingSource : BGAddonModding.ModdingSourceDefault
{
    public override BGRepoDelta[] Deltas
    {
        get
        {
            var files = Directory.GetFiles(Application.streamingAssetsPath, "bgdatabase_delta.bytes", SearchOption.AllDirectories);
            return files.Select(file => new BGRepoDelta(File.ReadAllBytes(file))).ToArray();
        }
    }
}

Data protection

Data protection is a declarative way to mark the data you do not want to be modified. Turn "Data protection" parameter on to enable it. Table/field/row/cell level rules are available. These rules take effect when "Delta mode" is on

Meta-level rules

These rules can be assigned at addon page. They affect the whole table, but they have the lowest priority and can be overridden (except Add disabled rule)

Field-level rules

These rules can be assigned at addon page. They affect single field and determine if this field can be edited. "high" suffix means, the rules have higher priority than rows rules

Rows-level rules

Rows-level rules can be assigned under "Database" tab (you need to turn on Data protection mode) You can define which rows can be edited and which rows can be deleted.

Cell-level rules

Cell-level rules can be assigned under "Database" tab (you need to turn on Data protection mode) These rules have the highest priority and affect single cells. Choose paint brush type (enabled/disabled/clear) and click over a cell to assign/clear rule

How rules are applied

1. In Editor when delta mode is on.
2. At runtime when delta files are merged with main database

Parameters