General information

Database consists of:

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 (tables and fields has unique names, 32 characters maximum)

How it works?

The database functions similarly to Unity: it reverts all runtime changes. Essentially, it represents the world at the beginning of the game. You can save and load runtime changes using the save/load add-on.

Video

Use Export/import

You can edit database data using external tools (Excel/GoogleSheets). CSV, JSON and scriptable objects are also supported.

Data binders

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

Accessing the database at runtime

1. With C# code using the basic API (not recommended, use #2 instead)
2. With C# code using generated classes (highly recommended over the basic API)
3. By adding a BGEntityGo component to any GameObject and selecting a table and row. (not recommended, use #4 instead)
4. Instead of using a BGEntityGo component, you can use either generated components or reference classes, generated by CodeGen add-on (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 explore these methods in more detail.

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

Here’s a minimal example of how you can access the 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);

2) Accessing the database using generated classes (recommended)

You can eliminate all boilerplate code by using generated classes. Here's the same example, rewritten with the assistance of these 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.

3) Accessing database by adding BGEntityGo component (not recommended)

You can easily connect 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. Instead of this method, we highly recommend using method #4, described below.

4) Using Generated Components (recommended)

Apart from Code Generation, described in method 2, there’s another type of Code Generation that generates classes inherited from Unity’s MonoBehaviour class. These classes can be added to Unity’s GameObject, just like a BGEntityGo component, but all of them have additional properties for each table field. We highly recommend to use this method instead of method #3. Alternatively, you can also use a field-based serializable reference to a row