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 for referencing database row(s). Such fields store row's primary key(s) and when the value is requested it uses these keys to resolve and return database row(s). The simplest relational field (relationSingle) is like a single column nullable foreign key, referencing one single row from one single table. Here is an example: let's say you have Cities table and Countries table and Cities table has country relationSingle field, referencing Countries table.

Relational fields differ in terms of how many 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 Field (#2)

Nested field is a special field, which creates a whole new meta (table), which has many-to-one relation to owner meta. It means, you can create a linked list with any fields that are supported by BGDatabase. It is a readonly field (to change its value - delete or add nested Entities). To create a nested Entity use special method, which accept the owner of nested entity BGMetaNested.NewEntity(BGEntity owner). BGMetaNested is a class for nested tables (to be used instead of generic BGMetaRow)

Technically, it's a usual table with many-to-one relation to parent table with 2 distinct features:

1. To access nested rows you need to choose parent row first using parent table GUI
2. If you delete a parent row, related nested rows will also be deleted, because they are considered as integral part of this parent row

You can read more about nested table concept here

Unity Scene Fields (#3)

Hashtable (#4)

Hashtable is a dictionary without generic parameters. Following types are supported as keys: int, string, bool, Guid, custom fields. 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 correct C# enum type name while creating enum field. If you can not figure out 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 you created your own enum field, you can not change enum type name, namespace or underlying type, because they are stored inside database. If you want to rename enum type or namespace, follow this guide. If you want to change underlying enum type (int, short, byte), follow this guide.
3. Values are stored exactly as C# store them - with numeric value. You may consider adding numeric values to your constants so constants reordering does not affect 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 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 field 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 and all subsequent reads use the cache to retrieve the object instead of using Unity API. To enable the cache use this code: BGAssetsCache.Enabled = true;

Calculated Fields (#7)

Calculated fields store a graph, which is used for calculating 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. The alternative and more efficient way to overriding variables is to use database fields values instead. You can access the current row by using "Special/Get current entity" node.

Action is a special calculated field, which does not return value, but can change database values. To invoke the action - use Invoke method on field value

Programmable Fields (#8)

Programmable fields are alternatives to calculated fields, but calculation is implemented with C# code, rather than graph tool. Use these fields only if you want the calculation result to show up in the database GUI, otherwise you can add these fields by creating the partial class with the same name as the class, generated by CodeGen addon and adding additional properties/methods to it.

To create programmable field you need to provide the name of C# class, implementing BGCodedFieldDelegateI<type> interface during field creation. 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

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

1. By reference means, that the value, stored inside database is returned. So changing collection values will actually change database value without setting a new value
2. By value means, that the new collection is created when value is accessed, and it can be modified without changing database value

The current strategy is to return a collection by reference if it's possible, and to return the collection by value only if returning value by reference is not possible (to avoid GC and performance hit)