There has been some amazing games built using the Unity platform.  Some may be seen over the Unity App Show Case section. But all of them are missing a core component to the in-game experience and that is a local database. What a local database may provide for games is the feature and ability to persist game data. This allows for in-game experiences that are not dependent on the network so the user can continue playing your game whenever network connection is dropped.  A user's in-game high score for example may be saved and then synced up to a remote database when connection is restored.  Let us explore how that is done.

Couchbase with Unity Games

To start off with Couchbase Mobile for Unity, there is a great tutorial that we will reference which takes an existing Unity game and adds a local database. The first part is to bring in the Couchbase Lite frameworks. In the example app, include Couchbase at the top of the GameController.cs file by having:

Create a Datebase

For the game that we are building, the player data is stored in a document and we will get the document containing the player high score.  To retrieve the database or create the database if it does not exist, we will reference the Couchbase Manager class.

Retrieve player document

We will reference the in-game data from the player by having a document named ‘player_data’  By referencing the database variable, db, when we request for the document, the document will be associated with the “spaceshooter” database.  We call the GetDocument method and pass in the document name.  If the document does not exist, then the document will be created. 

Data is described as properties of a document and for us to set the high score of a user within a game, we will modify the properties of the document and save a new revision. To do that we will call the Update method from Couchbase

The value add of having a local database for your game is that game properties here can be saved on the device without depending on your network.

Replicate Local Data

By creating replication endpoints, we can push local data to the remote server. To do that we will reference the
CreatePushReplication method from Couchbase

API and pass in the endpoint URL to sync with. To start the replication we execute ‘Start()’ on the variable.

The data is persisted locally and also over at the remote endpoint given if the connection is available.

Sync Remote Data

Getting the latest data from a remote endpoint is just as simple as saving it locally and syncing. To create a single pull replication we will first get a database by calling the ‘GetDatabase’ method and passing in the database name ‘spaceshooter’ in this case. But now instead of updating our remote server with data that is local to our device with a ‘PushReplication’ we will execute a ‘PullReplication’ from the remote endpoint

And like previously, calling Start() method on the variable will begin the replication process of syncing data from the remote endpoint to the device.

Retrieve Player Data

To examine what we have in our ‘spaceshooter’ database we can reference the variable representing database and see if the “player_data” document is available:

To retrieve the player high score, we would now populate the highScore variable with the value from the ‘high_score’ key.


These are the main pieces that allow the mobile app to run local activities such as saving its local state, and set up sync services to coordinate information consistency amongst app instances.  From this you can build up more functionality and create sophisticated services that can synchronize state across a network of apps. In the next blog we will explore the use of Couchbase Mobile technologies further within games.

Posted by William Hoang, Mobile Developer Advocate, Couchbase

William was a Developer Advocate on the Mobile Engineering/Developer Experience team at Couchbase. His love for coffee and code has transcended him into the world of mobile while appreciating the offline in-person experiences. Prior, William worked on the Developer Relations team over at Twitter, BlackBerry, and Microsoft while also having been a Software Embedded GPS engineer at Research In Motion. William graduated from McGill University in Electrical Software Engineering

Leave a reply