Fields overview

Fields table

This is all fields types, BGDatabase currently supports (you can create your own field if it's needed.)

Relational fields (#1)

Relational fields are used to reference database rows. These fields store a row's primary keys and use these keys to resolve and return the corresponding database rows when requested. The simplest relational field, relationSingle, functions like a nullable foreign key referencing a single row from a single table.

For example, there are two tables a Cities table and a Countries table. The Cities table has a country relationSingle field referencing the Countries table.

Relational fields differ in the number of tables and rows they can reference (read this blog post for more details)

Starting with BGDatabase 1.7.5- viewRelationSingle and viewRelationMultiple fields are recommended over manyTablesRelationSingle and manyTablesRelationMultiple fields (read this blog post for more details)

Nested fields (#2)

A nested field is a special field that creates a new meta (table) with a many-to-one relationship to its owner meta. This allows you to create a linked list where each element represents a row from the nested table. It is a readonly field (to change its value - delete or add nested entities). To create a nested entity from C# code, use the special method that accepts the owner of the nested entity BGMetaNested.NewEntity(BGEntity owner). BGMetaNested is a class for nested tables (to be used instead of generic BGMetaRow)

Technically, a nested table is a standard table with a many-to-one relationship to its parent table, distinguished by two key features:

1. To access nested rows, you must first select a parent row using the parent table’s GUI.
2. Deleting a parent row automatically deletes all related nested rows, as they are considered an integral part of that parent row.

The comparison between nested and row tables. Also, you can read more about nested table concept here

Unity scene fields (#3)

Referencing scene GameObjects using objectReference/objectListReference/objectListMultiValueReference fields is implemented using the same technique as demonstrated in this example Unity project. This involves adding a component (available under the "Components" menu as "BansheeGz/Id" and implemented as the C# class BGWithId) that assigns a unique ID to each object. BGWithId is a MonoBehaviour component; to access the associated GameObject- use gameObject property. In the Awake method, the object is added to the internal cache and in the OnDestroy method, it's removed from this cache. The results depend on which objects are loaded and which are not, and may vary during a play session. A table describing the fields’ features follows:

Hashtable (#4)

Hashtable is a dictionary without generic parameters. The following types are supported as keys: int, long, short, byte, string, bool, Guid, enums. The following types are not supported as values: Unity assets, relations, hashtable, nullable structs. Null values are also not supported.

Enum/enumList (#5)

With enum/enumList fields you can reference your own enumerations. Important notes:

1. You need to provide the correct C# enum type name when creating an enum field. If you are unable to determine the correct C# type name for your enum, use Type.FullName property to print enum type name to the console Debug.Log(typeof(MyEnum).FullName);
   Enum type name examples

   // MyEnum
   public enum MyEnum
   {
   }
   
   // MyNameSpace.MyEnum
   namespace MyNameSpace
   {
       public enum MyEnum
       {
       }
   }
   
   // MyNameSpace.MyClass+MyEnum
   namespace MyNameSpace
   {
       public class MyClass
       {
           public enum MyEnum
           {
           }
       }
   }

2. Once enum field is created, you cannot change the enum type name, namespace, or underlying type, as these are stored in the database. If you need to rename the enum type or namespace, refer to this guide. If you need to change underlying enum type (int, short, byte), refer to this guide.
3. Values are stored exactly as C# stores them— with numeric values. Consider assigning numeric values to your constants so that you can reorder them without affecting the stored values.
   

Enums with [Flags] attribute has special GUI, allowing to select multiple constants

Unity Asset Fields (#6)

All these fields are read only. You can reference any Unity asset (unityObject field can be used to reference any asset).

Available loaders

Third-party YooAsset loader is also available as a plugin

Sprite field and complex assets

Sprite and UnityObject fields support complex assets (when multiple assets are stored in one single file). Sprite fields support spritesheets/atlases. UnityObject field should support other asset types (like FBX file etc.) if you assign correct "Asset Type" parameter while creating UnityObject field. "Asset Type" parameter accepts valid full C# class name (for example UnityEngine.Material)

Optional L2 cache

Asset fields support optional additional cache on top of Unity API. If this cache is enabled Unity API is used to load the object for the first time; all subsequent reads use the cache to retrieve the object instead of using Unity API. To enable the cache use the following code: BGAssetsCache.Enabled = true;

Calculated Fields (#7)

Calculated fields store a graph used to calculate a result value. Graph is edited using graph editor.

Fields can have a default graph (edit via gears icon under "Configuration" tab) and a list of public variables

Each row can 1) override any public variable of default graph and 2) can have its own graph. A more efficient alternative to overriding variables is to use database field values. You can access the current row using the "Special/Get current entity" node.

An Action is a special calculated field that doesn’t return a value but can change database values. To invoke an action, use the Invoke method on the field value.

Programmable Fields (#8)

Programmable fields are alternatives to calculated fields; however, the calculation is implemented with C# code rather than the graph tool. Use these fields only if you want the calculation result to appear in the database GUI; otherwise, you can extend generated classes as described here

To create programmable field, you must provide the name of C# class implementing BGCodedFieldDelegateI<type> interface during field creation. The instance of this class will be used for value calculation

using BansheeGz.BGDatabase;

public class CalculateC : BGCodedFieldDelegateI<int>
{
    public int Get(BGCodedFieldContext context)
    {
        var entity = context.Entity;
        return entity.Get<int>("a") + entity.Get<int>("b"); // c = a + b
    }
}

If you want to use events, implement BGCodedFieldDelegateLifeCycleI interface as well

public class CalculateC : BGCodedFieldDelegateI<object>, BGCodedFieldDelegateLifeCycleI
{
    private BGField myField;

    public object Get(BGCodedFieldContext context)
    {
        var entity = context.Entity;
        return entity.Get<int>("a") - entity.Get<int>("b");
    }

    //this method is called on delegate loading
    public void OnLoad(BGCodedFieldDelegateLifeCycleContext context)
    {
        //add event listeners
        myField = context.Field;
        var aField = context.Field.Meta.GetField("a");
        aField.ValueChanged += FieldValueChanged;
        var bField = context.Field.Meta.GetField("b");
        bField.ValueChanged += FieldValueChanged;
    }

    //this method is called on delegate unloading
    public void OnUnload(BGCodedFieldDelegateLifeCycleContext context)
    {
        //remove event listeners
        var aField = context.Field.Meta.GetField("a");
        aField.ValueChanged -= FieldValueChanged;
        var bField = context.Field.Meta.GetField("b");
        bField.ValueChanged -= FieldValueChanged;
    }

    //fire 'c' field value changed
    private void FieldValueChanged(object sender, BGEventArgsField e) => myField.FireValueChanged(e.Entity);
}

Collection values

Collection fields may return the result (the list/hashtable) by reference or by value

1. Returning by reference means the value stored inside the database is returned. Consequently, changing the collection’s values will actually change the database value without setting a new value.
2. Returning by value means a new collection is created when the value is accessed, and it can be modified without changing the database value.

The current strategy is to return a collection by reference whenever possible, and to return the collection by value only when returning it by reference is not feasible (to avoid garbage collection and performance impact)

Example using CodeGen add-on with "classes prefix"= "D_"