This is all fields types, BGDatabase currently supports (you can create your own field if it's needed.)
|Field Group||Field name||Field Type||Comments|
|string||string||single line text|
|text||string||multiple lines text|
|animationCurve2017||AnimationCurve||Field target Unity 2017. For Unity >= 2018, download field animationCurve2018 here|
|Unity Primitive nullable||vector2?||Vector2?|
|Unity Assets #6||unityTexture||Texture|
|unitySprite||Sprite||Can accept a single sprite, a sprite from a multiple sprite, a sprite from SpriteAtlas If you use SpriteAtlas, make sure to turn SpritePacker on (set Edit->Project settings->Editor->SpritePacker to "Always Enabled" and press on "Pack preview" button when you change your atlas)|
|unityObject||Object||Starting with v.1.5.6 additional type constraint can be added. Code generators generate proper type (using type from constraint)|
|List of Primitives||listBool||List<bool>|
|List of Unity Primitives||listVector2||List<Vector2>|
|Relations #1||relationSingle||BGEntity||reference to one single row from one single table|
|relationMultiple||List<BGEntity>||reference to several rows from one single table|
|manyTableRelationSingle||BGEntity||reference to one single row from several tables (use field's gear icon to define multiple tables). Not recommended, use viewRelationSingle instead|
|manyTableRelationMultiple||List<BGEntity>||reference to several rows from several tables (use field's gear icon to define multiple tables). Not recommended, use viewRelationMultiple instead|
|viewRelationSingle||BGEntity||reference to one single row from a view (several tables)|
|viewRelationMultiple||List<BGEntity>||reference to several rows from a view (several tables)|
|Unity Scene #3||objectReference||BGWithId||read-only|
|Calculated #7||calculatedBool||bool||These fields calculate the value, when this value is requested, using graph editor tool|
|action||Action||Action does not calculate any value, but change database values, create/delete rows.|
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
country relationSingle field, referencing
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)
|Field (relation)||How many tables can be referenced||How many rows can be referenced|
Nested Field (#2)
Nested field is a special field, which creates a whole new meta (table), which has many-to-one relation to owner
It means, you can create a linked list with any fields that are supported by BGDatabase.
It is a readonly field (to change it's value- delete or add nested Entities).
To create a nested Entity use special method, which accept the owner of nested entity
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:
- To access nested rows you need to choose parent row first using parent table GUI
- If you delete a parent row, related nested rows will also be deleted, cause they are considered as integral part of this parent row
You can read more about nested table concept here
Unity Scene Fields (#3)Referencing scene GameObjects using objectReference/objectListReference/objectListMultiValueReference fields is implemented with the same technique, which is used in this example Unity project, by adding additional component (component name under components menu is "BansheeGz/Id", C# class is BGWithId) with unique ID. BGWithId is a
MonoBehaviourcomponent, to access GameObject- use
gameObjectproperty. On Awake method object is added to the internal cache and On OnDestroy method object is removed from this cache. The result depends on which objects are loaded and which objects are not and can differs during play session. Here is a table, describing fields features:
|Feature ↓\Field →||objectReference||objectListReference||objectListMultiValueReference|
|Purpose||Return the first loaded GameObject with specified ID||Return all loaded GameObjects with specified ID||Return all loaded GameObjects with specified IDs|
|Internal value||Single ID||Single ID||Multiple ID|
These 2 fields differ in terms of how many IDs are used to reference multiple GameObjects.
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.
With enum/enumList fields you can reference your own enumerations. Important notes:
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
- Once you created your own enum field, you can not change enum type name, namespace or underlying type, cause 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.
- 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).
|Resources||Asset Bundles (obsolete)||Addressables||Addressables by Guid|
|Recommendations||Use it only if an amount of assets is small. Unity does not recommend to use it (more info)||not recommended under any circumstances||use it if you want database to store asset's address||use it if you want database to store asset's Guid.|
|How asset is loaded||using Resources.Load||using AssetBundle.Load||using Addressables.LoadAssetAsync|
|Prerequisites||asset should be placed under one of Resources folder||asset should be included to one of asset bundles||
|Stored value||path, relative to Resources folder||path within asset bundle||asset address||asset Guid|
|Limitations after asset was added to database (otherwise you need to reassign the value)||path/name can not be changed||name can not be changed||asset address can not be changed, but you can freely move/rename asset||asset Guid can not be changed (it's stored in corresponding meta file), but you can freely move/rename asset|
|More information||Read more about Resources folder and asset bundles here||Read Unity's Addressables manual here. To add support for addressables, please, download our plugin and follow setup/use manual at our download page|
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 it's 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
Collections fields may return the result (the list/hashtable) by reference or by value
- 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
- 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)
|Field(s)||Basic API||CodeGen addon|
|Lists with primitive values (List<string> etc.)||by reference||by reference|
|Hashtable||by reference||by reference|
|Multiple relational fields (Lists with rows values)||by value||by value|
|Enum list||by value||by reference|