Description

Generate both scriptable object C# sources (one per table) and assets (one per row).

Setup

1. Read this guide to learn how to create a data source and a job
2. Switch to a data source and select a folder for C# source files for scriptable objects (use new, empty folder) and press on "Generate C# source files" button to generate C# sources for scriptable objects. One C# source file for each table will be generated.
   
3. Select a folder for scriptable object assets (use new, empty folder)
4. Switch to a job and setup merge settings. Be careful with "Remove orphaned" setting, because it can lead to rows or assets being deleted if no matching row or asset is found.
5. Click on "Export" button to generate assets or "Import" button to transfer data from assets to database
   

Limitations and warnings

1. Data exchange with scriptable objects is not universal. If scriptable assets are created with our generated C# classes, it's possible to export/import any data from/to the database (as soon as the fields are supported). However, if scriptable assets are not created with our generated C# classes, there is no guarantee that you will be able to export/import data from such scriptable assets into the database.
2. Select 2 new, empty folders for generated C# sources and scriptable assets. Do not put other assets in these folders.
3. Exporting data while assets are not yet exist is very slow, exporting 1000 rows can take 20-25 seconds. Transferring data to existing assets or importing data is quite fast.
4. Exporting data creates one asset(file) per each row, keep this in mind if you have a lot of rows
5. If you want to create a new asset and import it later to the database by duplicating existing asset, make sure to clear Id field in duplicated asset, otherwise the asset will be ignored
6. Though merge settings are supported, we recommend to use data source settings to include/exclude tables/fields instead
7. When you use "Remove orphaned" toggle in merge settings during export, it means that orphaned scriptable assets will be physically deleted.
8. See the job's log for more information about synchronization process
9. Not all fields are supported (read the section below for more details).
10. Read the guide below about how to change settings or table/field names safely

C# sources and assets

Scriptable objects consist of two parts- C# source files for scriptable objects (with cs extension), which defines which fields each asset has and the assets, the instances of this C# class, stored in separate files (with asset extension). Both C# source files (one for each table) and the assets (one for each row) are generated.

1. Generating C# sources: C# sources can be generated from data source page. You can also exclude some tables/fields from generation
2. Generating assets: assets are generated during export job execution. C# source files should be up-to-date, they should have all supported/included database fields, otherwise exception is thrown and C# source files generation should be run to update source files.

Unsupported fields

Most of the fields, including assets and relations are supported. The following fields are excluded because they are not supported by Unity (hashtable, guid, ray, ray2D, listGuid, decimal, all nullable fields). The following fields rely on BGDatabase code and are also excluded (objectReference, objectListReference, objectListMultiValueReference, entityReference, entityReferenceList, id, action). If you exclude some table manually, all relational fields, referencing this table, are going to be excluded automatically.

How to change settings, table/field names

If you change folders, class name prefix or table name without any further action, you are going to lose the link between database data and existing assets or create duplicates next time you export/import data. This section describes, how to update folders, class name prefix, table or field names without losing links with existing assets. [Important] Backup your project just in case before renaming

Changing folders

After changing folders in the settings, move the folders manually inside Unity Editor to new location.

Changing classes name prefix

After changing Classes name prefix in the settings, rename all generated C# source files inside Unity Editor to reflect the change, for example if your source file is S_MyTable.cs, and you change the prefix from S_ to T_ the new name should be T_MyTable.cs. After changing all file names, regenerate C# sources for scriptable objects and fix all compilation errors by changing class names from old name (S_MyTable) to new name (T_MyTable) in your C# code.

Renaming table name

After renaming table name, rename both the C# source file name and folder name for generated assets inside Unity Editor to reflect the change. For example, if the old name is MyTable and the new table name is MyTableUpdated and Classes name prefix is S_, rename C# source file from S_MyTable.cs to S_MyTableUpdated.cs and folder name from MyTable to MyTableUpdated. After changing C# file name and folder name, regenerate C# sources for scriptable objects and fix all compilation errors by changing class name from old name (S_MyTable) to new name (S_MyTableUpdated) in your C# code.

Renaming field name

if you want to change field name and then re-generate both C# sources and the assets, there is no need for extra actions. If you want to rename the field and regenerate C# sources without re-generating the assets, you need to add FormerlySerializedAs attribute to the C# field with value, equal to the old name. After renaming database field, open data source page, then "C# settings", then create a custom settings for the table, include the table, open fields popup, create a custom setting for the field, include it and enter old field name to "FormerlySerializedAs" column. You can remove this setting after assets generating is executed.