Setup
Prerequisites
Airtable
GameDataSync syncs your game's Airtable data into Unity, so you must have an Airtable account and at least one Airtable base to get started.
Sign Up for Airtable
Navigate to Airtable's sign-up page and create a free account.
Create an Airtable Base
Follow Airtable's Quick Start guide to create your first base and create some records in a table. You may wish to run through the full Quick Start if you're unfamiliar with the flexible data authoring and visualization tools Airtable provides.
Did you know?
While Airtable's examples may be business-oriented, its tooling is extremely powerful for authoring and organizing game design data!
Configure the UnityId Field
GameDataSync imposes two requirements on your Airtable tables:
- The primary field in each table must be named
UnityId
. - All of the values in this field must be unique within a given table.
Rename the primary field in any tables you wish to sync by double-clicking the field name and entering UnityId
.
Version Control
It is strongly recommended that you use a version control system, such as Git, to manage your Unity project and commit game data changes in isolation from game logic changes.
Installation
GameDataSync must be installed via the Unity package manager. Once installed, the GameDataSync editor window can be accessed by navigating to Services GameDataSync in the top menu bar.
Automatic Initialization
An AirtableConfiguration
asset will be created in your project's Assets directory upon opening the GameDataSync editor window for the first time.
Important
- You may freely move or rename the
AirtableConfiguration
asset within your project's Assets directory for organizational purposes, but it must not be deleted or duplicated. - You should commit the
AirtableConfiguration
asset to your source code repository to ensure all project contributors are using the same plugin configuration. - The
AirtableConfiguration
asset cannot be modified through its inspector - its values are configured exclusively via the editor window.
Configuration
GameDataSync provides a simple, easy-to-use editor window for centralized configuration and use of the plugin. The example below is fully configured and ready to sync data!
1. "Sync by UnityId column" Checkbox
Determine whether you would like your records synced by Airtable Record IDs or by the unique UnityId
field values you enter. This impacts how ScriptableObject
references are maintained throughout your codebase. By default, records are synced by Airtable Record ID, which is a unique ID that Airtable creates under the hood for each record in each table. The UnityId
field values are values you control and enter alongside the rest of your data.
Generally, ScriptableObject
references will be properly maintained across your codebase using either approach; references may be lost and may need to be reconfigured in the following cases:
- For Airtable Record ID syncing: If an Airtable record is deleted entirely from Airtable and then recreated with the same values, its associated
ScriptableObject
in Unity will also be deleted and recreated; this will cause asset references to break in Unity. - For
UnityId
column syncing: If theUnityId
value in an Airtable record is modified, its associatedScriptableObject
in Unity will be deleted and recreated with the newUnityId
; this will cause asset references to break in Unity. - It is recommended to sync by
UnityId
column if your workflow involves authoring data in a spreadsheet program (e.g. Excel or Google Sheets), then importing those sheets into Airtable.
2. Enter Personal Access Token
Navigate to the Airtable token creation page and create a new Personal Access Token. Fill out the following fields:
Field | Value | Notes |
---|---|---|
Name | GameDataSync - {your_unity_project_name} | You may name the token whatever you like; this is just an organizational recommendation. |
Scopes | data.records:read , schema.bases:read |
These are the minimum required scopes for the plugin to function. |
Access | All current and future bases in all current and future workspaces | Select specific bases if you want to limit the Airtable bases that the plugin can detect and sync in your Unity project. |
Once you have created your token, paste it into the Personal Access Token field in the editor window.
Important
This is a sensitive value that should not be committed to a source code repository! As such, it is stored in EditorPrefs
, and each developer must enter their own Personal Access Token on each development machine that will use the plugin.
3. Select Output Directory
Enter the Assets-relative subdirectory that your synced Airtable C# classes and ScriptableObject
s will be written to. The default is GameData
.
4. Test Connection
Verify your Personal Access Token is configured correctly by pressing . A modal will appear with the test result:
5. Load Airtable Metadata
Load your Airtable metadata into GameDataSync by pressing . The plugin will download your Airtable base and table schemas via Airtable's metadata API and populate a new Airtable Bases to Sync section of the editor window with the bases, tables, and fields that your Personal Access Token has permission to sync into Unity.
6. Select Data to Sync
Use the checkboxes to select the bases, tables and fields to sync into Unity.
Setting | Behavior when | Behavior when |
---|---|---|
Base |
|
|
Table |
|
|
Field |
|
|
Is Array |
|
|
In the example below, the Monsters
, Stat Blocks
, and Items
tables in the Demo
base are configured to be synced.
graph LR
subgraph Configuration
A[<img src='./img/demo_airtable_bases_to_sync.png' width=280 height=480 />]
end
7. Sync Data
Once you have the configuration to your liking, press . The plugin will:
- Download your Airtable data and generate
ScriptableObject
-derived classes that best conform to each table's schema. - Wait for the Unity editor to recompile with the new classes defined.
- Generate a
ScriptableObject
of the appropriate type for each record that was loaded from Airtable.- Any records in Airtable with an empty
UnityId
value will not be synced into aScriptableObject
.
- Any records in Airtable with an empty
Info
Unity may recompile scripts in the middle of the synchronization process. This is necessary whenever new tables are synced or any table schemas have changed; the associated C# classes must be rewritten and recompiled before updating the data in all of your ScriptableObject
assets.
Check out the following sample configuration and its associated C# and ScriptableObject
output. GameDataSync created C# classes for each table and populated different types of ScriptableObject
s (Monsters
, StatBlocks
, and Items
) for each record with appropriate values - including references to other ScriptableObject
s!
graph LR
subgraph Configuration
A[<img src='./img/demo_airtable_bases_to_sync.png' width=280 height=480 />]
end
subgraph Monsters
monstercs[<img src='./img/monsters_cs.png' width=445 height=385 />]
monster[<img src='./img/monster_werewolf.png' width=400 height=240 />]
end
subgraph Stats["Stat Blocks"]
statscs[<img src='./img/stat_blocks_cs.png' width=444 height=354 />]
stats[<img src='./img/stats_werewolf.png' width=400 height=160 />]
end
subgraph Items
itemscs[<img src='./img/items_cs.png' width=444 height=350 />]
item[<img src='./img/item_werewolf_tooth.png' width=400 height=160 />]
end
A --> Monsters
A --> Stats
A --> Items