Skip to content

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:

  1. The primary field in each table must be named UnityId.
  2. 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.

Rename Primary Field

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.

Open Airtable Editor Window

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!

Airtable Editor Window

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 the UnityId value in an Airtable record is modified, its associated ScriptableObject in Unity will be deleted and recreated with the new UnityId; 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 ScriptableObjects will be written to. The default is GameData.

4. Test Connection

Verify your Personal Access Token is configured correctly by pressing the Test Connection button. A modal will appear with the test result:

Connectivity Test Modal

5. Load Airtable Metadata

Load your Airtable metadata into GameDataSync by pressing the Load Airtable Metadata button. 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
  • Allows tables defined within the base to be synced.
  • Prevents tables defined within the base from syncing their schemas and records into Unity.
  • Will not delete synced data from the Unity project if unchecked after having already synced one or more of the base's tables.
Table
  • Allows C# classes to be created in Unity to represent the table's schema.
  • Allows table records to be created as ScriptableObjects in Unity.
  • Prevents C# classes and ScriptableObjects associated with the table and its records from syncing into Unity.
  • Will not reflect schema or record changes made in Airtable during future data syncs if unchecked after having already synced one or more of its records.
  • Will not delete synced data from the Unity project if unchecked after having already synced one or more of its records.
Field
  • Adds the field as a typed field to the owning table's C# class.
  • Populates each record's ScriptableObject with the field's corresponding value from the record.
  • Omits the field from the owning table's C# class if the C# class has not yet been created.
  • Removes the field from the owning table's C# class if the C# class has already been created.
  • Removes the field and its value from each record's ScriptableObject for any ScriptableObjects that have already been created for records in the owning table.
Is Array
  • Explicitly tells GameDataSync to treat a string field's value as a comma-delimited array of elements.
  • This enables parsing field values 1,2,3,4,5 into an int[], 1.23,4.56,7.89 into a float[], hello,world into a string[], etc.
  • GameDataSync will not parse the field as a comma-delimited array if it a string field in Airtable; GameDataSync will still automatically parse the field as an array if the field is a Link to other records or Multiple Select-type field in Airtable.

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 Sync Data button. The plugin will:

  1. Download your Airtable data and generate ScriptableObject-derived classes that best conform to each table's schema.
  2. Wait for the Unity editor to recompile with the new classes defined.
  3. 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 a ScriptableObject.
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 ScriptableObjects (Monsters, StatBlocks, and Items) for each record with appropriate values - including references to other ScriptableObjects!

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