Getting Started
The best way to start using uGameDB is to install and configure a Riak cluster with three nodes. This will give you a failure-resilient test environment that you can connect to from your Unity game servers. You can then test how your game servers, the uGameDB API, and Riak behaves in a distributed environment. For example you are able to see what happens when you kill one Riak node in the middle of a test run. This event should be handled gracefully and the same goes for adding new Riak nodes to the database cluster. uGameDB has two parts. Riak is the back-end database and the uGameDB Unity package is the client-side API. Note that in this context the uGameDB client is normally a game server, not a game client. It is of course possible to have the game client connect to the database, but generally this is a security problem.Installation
First, you need to determine a way to host the Riak database. The ideal option is if you have access to three or more physical Linux machines that you can use as Riak nodes. This will give the best performance and is the recommended final deploy environment for your database. During development however, it can be more convenient to use a number of virtual Linux machines, either locally on a Unity development machine, or remotely. The benefits of this is to be able to quickly bring Riak nodes up and down without affecting other developers working on the same game. This means you can use live database code from the beginning and have it tested thoroughly by the time of release. uGameDB has been tested with Riak v1.0 running on Ubuntu Server 64 bit 11.10. Using older versions than this is not recommended, especially pre-1.0 Riak versions. First, before you do the installation, make sure you have a Linux server with a static IP. Riak is aware of the IP number of the host operating system and therefore the IP should never change, not even after a reboot. If you need help setting up a virtual Linux machine with Ubuntu Server, check out the How To-sections in this manual. How to configure a static IP can be found there. If you choose to rent an vitual Ubuntu server at some hosting comany like Amazon EC2 or GoGrid, the server will get a static IP by default. When you have a Linux host ready, by any of the options above, proceed to install Riak on it by following the Riak Installation instructions on the Basho website. Once installation completes you can go on to setting up the cluster.Cluster Setup
When the installation has completed, follow the Riak Adding and Removing Nodes instructions on the Basho website to perform initial configuration. If you want to get started quickly, you only need to perform the steps up to Start the Node section. Note that you don't have to prefix the commands with 'bin/'. This will give you a one-node cluster. If you continue after that, you will get a multi-node, or distributed, Riak cluster. Note that you will need one physical or virtual machine for each Riak node. Start Riak using the following command at the Riak host terminal. $ riak start Verify that Riak is working properly within itself by typing the following. $ riak-admin test Riak should respond that it successfully completed one read/write cycle. You can now verify that the database answers to HTTP calls. Open a browser and visit the following address (replace x.x.x.x with the IP of your Linux machine). http://x.x.x.x:8098/riak/test If you have more than one node, then you should check each of them this way. You can also perform this test from the Linux terminal using the following command. $ curl -v http://x.x.x.x:8098/riak/test By completing these steps you have made sure that your Riak cluster is running properly.Connecting to Riak from Unity
The next step is to start Unity and make a first connection from the editor. Make sure that you have imported the uGameDB Unity package. Below is a minimal script, Mini.cs, that stores one key/value-pair in Riak. Add this script together with the uGameDBConnection utility script to an empty game object, and press play in the Unity editor. The utility script can be found in Plugins/uGameDB/Utility Scripts.using UnityEngine;
using uGameDB;
using System.Collections;
public class Mini : MonoBehaviour
{
public void Start()
{
StartCoroutine(MiniCoroutine());
}
private IEnumerator MiniCoroutine()
{
var bucket = new Bucket("PlayerBucket");
var setRequest = bucket.Set("PlayerNr1", "DataForPlayerNr1", Encoding.Json);
yield return setRequest.WaitUntilDone();
Debug.Log("Wrote one value and got a reply. Success = " +
setRequest.isSuccessful);
}
}
The following should be written to the console.
Wrote one value and got a reply. Success = True
This is how it works. uGameDBConnection makes the connection to Riak in the Awake() method. Awake() is always executed before Start(). The Start() method in Mini.cs is called and it starts a coroutine. The coroutine saves one key/value-pair to Riak and then yields (waits) until the database sends a signal that it is done.
The beauty here is that using a coroutine makes it possible to halt execution without affecting the normal update-loop in Unity. The game server can continue to execute as normal until the database reply arrives, at which point the coroutine resumes and the output is written to the console.
Read more about Coroutines and Yield in the Unity manual.
To be able to verify that the key and value have been written to the database it is easy to code one read operation, or use the http API that is always available in Riak. Try the following read operation in a browser.
http://x.x.x.x:8098/buckets/PlayerBucket/keys/PlayerNr1
The response should contain “DataForPlayerNr1”. You may get it as a downloadable file because your browser will not be able to determine the document type of the data.
Use these links to learn more about Riak's complete REST-ful HTTP API. This API is very handy for developers, because it makes it easy to view and debug server-side data from a browser or from the Linux curl command-line tool.