General informationDatabase consists of 4 main parts:
- Table (meta)
- Table field
- Table row (entity)
- Database addon
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.
You can edit database data in external tools (Excel/GoogleSheets). Use json export/import to create database backup.
Data binder components let you inject values from database to Unity's components (including your own ones, inherited from MonoBehaviour).
Accessing the database at runtime
- With C# code using basic API (not recommended, use #2 instead)
- With C# code using generated classes (highly recommended over basic API)
- By adding BGEntityGo component to any GameObject and choosing table and row. (not recommended, use #4 instead)
- Instead of using BGEntityGo component, you can use generated components. (highly recommended over using BGEntityGo)
- 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);
- Read more about basic C# API
- 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 it's 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 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.