There have been some amazing games built using the Unity platform. Some may be seen over the Unity App Showcase section. Impressive as these creations are, there is a core component missing in all games built with Unity: a local database.

In Unity, a database hosted locally can persist game data and improve playability — the game doesn’t end or slow when a network connection is dropped. A player’s in-game high score may also be saved and then synced up to a remote database when the network connection is restored.

In this blog post, we’ll explore how Unity and the NoSQL database, Couchbase, can work in concert to deliver outstanding experiences for mobile game players.

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 your Unity game database

For the game that we are building, the player data is stored in a document and we will get the document containing the player’s 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 the 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.


There are a number of great reasons to employ a local database in a Unity game design. With Couchbase Mobile, Unity games can run local activities such as saving its local state, and set up sync services to coordinate information consistency amongst app instances.

Bottom line: the richer your local game environment — and the less network-dependent the Unity game experience is for playability — the more confident you’ll be adding functionality and increasingly sophisticated services that can synchronize state across a network of apps.

In the next blog, we will explore additional ways Couchbase Mobile can enhance game design, development, and play.


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