How to use

General information

Database consists of 4 main parts:
  1. Table (meta)
  2. Table field
  3. Table row (entity)
  4. Database addon
Every table, field and entity has unique id (based on Guid generation) and name (table and field has unique name, 32 char max)

How it works?

Database works just like Unity does- it reverts all runtime changes. So it basically represent the world at the beginning of the game. You can save/load runtime changes with save/load add-on.


Use Export/import

You can edit database data in external tools (Excel/GoogleSheets). Use json export/import to create database backup.

Read more about Export/import

Data binders

Data binder components let you inject values from database to Unity's components (including your own ones, inherited from MonoBehaviour).

Read more about data binders

Accessing the database at runtime

  1. With C# code using basic API (not recommended, use #2 instead)
  2. With C# code using generated classes (highly recommended over basic API)
  3. By adding BGEntityGo component to any GameObject and choosing table and row. (not recommended, use #4 instead)
  4. Instead of using BGEntityGo component, you can use generated components. (highly recommended over using BGEntityGo)
  5. By using custom actions/units/nodes for visual scripting tools (visit this page for the full list of supported tools)

Let's take a closer look at these methods.

1) Accessing the database using basic API (not recommended)

Here is minimalistic example about how you can access database without code generation:

 //get reference to database
var repo = BGRepo.I;
//get reference to table(called meta) MyTable by name
var meta = repo["MyTable"];
//get entity by id
var entity = meta[new BGId("some-id-here")];
//get int field value
var fieldValue = entity.Get<int>("myField");
//set int field value
entity.Set("myField", fieldValue + 1);
  1. Read more about basic C# API
  2. View code examples
2) Accessing the database using generated classes (recommended)

You can remove all boilerplate code by using generated classes. Here is the same example but written with help of generated classes.

    //the same example with code generation
var entity = BGE_MyTable.GetEntity(new BGId("some-id-here"));
entity.myField = entity.myField + 1;

As you can see, using generated classes removes all boilerplate code and also adds compile time check in case the database structure is changed. E.g. for example, if you remove field myField or change its name and regenerate the classes - you'll get compile-time errors, that myField property is not found.

So using generated classes is highly recommended.

Read more about Code Generation for extension classes
3) Accessing database by adding BGEntityGo component (not recommended)

You can easily hook up any GameObject to a database row by adding BGEntityGo component to it. Just add the component, select table (meta) and then select a row (entity) After that all fields will be immediately available for reading and writing.

However, in this scenario you'll have to use basic API, which has a lot of boilerplate code.

So, instead of this method, we highly recommend to use method 4, described below.

4) Instead of using BGEntityGo component, use generated classes (recommended)

Apart from CodeGeneration, described in method 2, there is another type of CodeGeneration, which generates classes, inherited from Unity's MonoBehaviour class. These classes can be added to Unity's GameObject, just like BGEntityGo component, but all of them have additional properties for each table field, so you can use them instead of basic API. We highly recommend to use this method instead of method 3.

Read more about Code Generation for MonoBehaviour classes