GoogleDB Documentation

Overview

Welcome to the GoogleDB documentation page. GoogleDB is a toolset for using Google Docs spreadsheets as a form of database to generate static C# classes dynamically that can be used inside of Unity.

Below you'll find resources on how to use GoogleDB and all it's features. To report any bugs or for questions not covered in the documentation, please e-mail jschieck@gmail.com. If you are having issues with a specific spreadsheet, the easiest way is to share it with me and I can quickly tell you what the issue is.

Features

Topics

Setting up a spreadsheet

Setting up a spreadsheet (this is the "database") is very simple in GoogleDB. Once you have a google account, go to drive.google.com, login, and in the upper left click Create -> Spreadsheet.

Once the new spreadsheet is created you can begin populating your data. All databases must start with an ID column in column one. The spreadsheet format is as follows:

ID Variable1 Variable2 etc...
null int float etc...
Weapon1 23 2.2 etc...
Weapon2 19 2.4 etc...

Rules of a spreadsheet:


An example of having multiple sheets (classes) in a single document.

Supported Data Types

DataType Usage
null A null data type will not be imported into the class. It will be skipped during generation.
string Sword of 1000 Truths
bool TRUE or FALSE
float 235.54 - NOTE: No "F" suffix is required
double 5452.2458
short -32768 to 32767
ushort 0 to 65535
int -2147483648 to 2147483648
uint 0 to 4294967295
long -9223372036854775808 to 9223372036854775808
ulong 0 to 18446744073709551615
byte 0 to 255
sbyte -128 to 128
char A single letter: b
Vector3 Three floats seperated by commas: 1.25,545,124
Vector2 Two floats seperated by commas: 1.25,545
Color Four floats seperated by commas: 0.5,0.25,1,1
hash Will take the specified string and store it as an int. Useful for storing an ID column value.
hash[] Same as the hash but with comma seperated values.
enum Enum is a special type that will take all the values in the column, and generate an enumeration from them. For example if you wanted to create a "Type" on your weapons, use the enum data type and for the data use things like: Sword, Axe, Bow, etc... and the class will have an enumeration on it called eType with all possible values.
string[]
bool[]
float[]
short[]
int[]
double[]
long[]
uint[]
ushort[]
ulong[]
byte[]
All arrays follow the same format as their native types, values are seperated by commas.
Example of string[]: dog,cat,cow
Example of int[]: 1,5234,342

Example Spreadsheets

Below are examples of two sheets, one for Weapons and one for Enemies.

The hash or hash[] datatype can be used to reference other items in another sheet as well. Since it is a spreadsheet, you can use built in functions to reference cell values. So things like =Weapons!A3 will pull the value from the Weapons sheet in cell A3, and then if you change the weapons ID, the link will not be broken in the Enemies table.

Click here for a list of functions for Google spreadsheets

View this spreadsheet in Google Docs

Importing Into Unity

The import process for Unity is incredibly simple. Once you've imported the package to your project, go to Window -> GoogleDB Importer.

Once the window is opened you'll see the authentication screen. Click Get Authentication Token. This will open the google authentication page.

Click Accept and then copy the code from the next page.

Copy the code.

Paste the code into the GoogleDB window and click Authenticate

After authenticating you'll see the importer window. This window will list all spreadsheets linked to that Google account including shared ones from other users. After expanding the dropdown for the spreadsheet you want to import, you'll see a list of all the sheets inside of that spreadsheet. You can choose whether or not to import this sheet into your project.

Options:

Selection Options:

Once you have selected the sheets you want to import, click Import and it will generate the C# classes for your data.

Classes will be put into the GoogleDB folder under a folder named the same as the spreadsheet.
For example: Assets/GoogleDB/ExampleSpreadsheet/Weapons.cs

If you change the name of the spreadsheet, you'll need to delete the old scripts to prevent script name conflicts.

View the example weapons generated class

Usage Examples

Once some classes have been imported, let's take a closer look at how the data is stored and how to use it.

Each class generates it's own enumeration for a unique ID. We'll be using the Weapons class for this example. Data can be retrieved by simply using:

Weapons broadSword = Weapons.Get(Weapons.WeaponsID.BROADSWORD);

You can then use this data however you wish.

Looping through all data

If you chose the Make databases public in classes option on import, the simplest way to loop through all the data would be:

foreach (var keypair in Weapons.db)
{
    Weapons data = keypair.Value;
    Debug.Log(data.Id);
    Debug.Log(data.Damage);
}

Another way to do it is to use the avaiable GetEnumerator() method on the class:

foreach (Weapons.WeaponsID id in Weapons.GetEnumerator())
{
    Weapons data = Weapons.Get(id);
    Debug.Log(data.Id);
    Debug.Log(data.Damage);
}

Loading Data at Runtime

The best practice is to specify a public ID field on the MonoBehaviour/Prefab/Object where you need your data, then load it in inside of the Start() function of that behaviour. If using the Make classes serializable option, you can then also see the class in the inspector.

*NOTE: Since all data is stored statically, the data can be accessed at any time, no need to initialize it.

using UnityEngine;
using System.Collections;
using System.Collections.Generic;

public class MyWeaponClass : MonoBehaviour
{
    public Weapons.WeaponsID weaponID;
    public Weapons data;

    void Start()
    {
        data = Weapons.Get(weaponID);
    }
    void DoAttack(GameObject target)
    {
        // attack some target
        target.SendMessage("Damage", data.Damage);
    }
}

Getting the Next or Previous item

If you are trying to do something like a menu where you can cycle through all the data, you can use the extension methods to cycle to the next or previous ID like this:

Weapons.WeaponsID currentWep = Weapons.WeaponsID.BROADSWORD;
currentWep = currentWep.Next();
Debug.Log(currentWep); // Result: WOODAXE
currentWep = currentWep.Previous();
Debug.Log(currentWep); // Result: BROADSWORD

Getting a Random Item

Weapons randomWep = Weapons.GetRandom();

Conclusion

Though GoogleDB is not be the best solution for large scale MMO's and isn't nearly as powerful as something like a SQL database, it certainly has it's advantages for smaller projects and for those who don't want to build a whole backend for their game or edit, import, and parse XML based data. Any questions or suggestions email jschieck@gmail.com.