Modding

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.

  1. Override Deltas property to provide your own delta (method #1)
  2. Override void OnLoad(BGRepo repo) method to make changes using C# API (method #2)

Here is an example for both 2 methods:

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
    {
        //Method #1 : 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),}; }
        }

        //Method #2 : Override OnLoad method if you want to modify database using C# API.
        //In our case we modify entity name from "test" table using provided ID
        public override void OnLoad(BGRepo repo)
        {
            repo["test"][new BGId("2y2PI1012ka/kjXBhiXlDg")].Name = "Updated name";
        }
    }

Parameters

Parameter name Description
In builds only Modding addon will be ignored if application is running inside Unity Editor