Nakama Cloud Save Sample Project

The official sample project demonstrating Cloud Save functionality in Nakama. Built with minimal boilerplate so you can easily copy the code into your project and adapt the scripts and UI to suit your game.

Features

• Authenticate via your device or Facebook to create an account.
• Link an existing account to Facebook.
• Save account data to the cloud, which is synced between devices.
• Connect an existing social provider and fetch player data from the cloud.

Installation

The installation steps and resulting folder structure will vary depending on if you downloaded the project from Github or the Unity Asset Store.

The project connects to our demo server so you can see the features in action immediately.
Note: The server is reset on the 1st of every month at 00:00 UTC.

Folder structure

Assets/
├── UnityNakamaCloudSave/
    ├── HeroicUI/           # UI assets and styling
    ├── Scripts/            # Main project code
    ├── UI/                 # UI Builder files
    └── ...                 # Everything else
├── Packages/               # Contains the Nakama Unity package

Although Facebook is used in this sample project, other social providers are supported as well e.g., Google, Steam, Apple, and so on. You will need your own developer account in order to connect to these providers.

Setting up with Facebook #

In order to authenticate or link an account to Facebook, you’ll need your own Meta developer account and credentials. This project comes pre-loaded with the Facebook Unity SDK so you don’t need to download and install the package yourself.

1. Register as a Meta developer if you haven’t done so already.
2. Follow the steps in the Facebook Unity SDK guide to retrieve your Facebook App ID and Client token.
3. In the Unity editor, select Facebook > Edit Settings and add your credentials to their respective fields.

You’ll need to Build and run the project in order to authenticate or link an account with Facebook, as requests to third-party services don’t work while running the project inside the Unity Editor.

See the Cloud Save feature in action #

1. Click Sign in as Guest. The system creates a new player account using device authentication.
2. Under Data Simulator, enter a number in Points and select Submit.
3. Select Link Facebook to link this account to Facebook. Follow the prompts.
4. Close the window and Build and run the project again.
5. This time, select Sign in with Facebook.

The dialog displays the same points value you entered earlier. This is because Nakama recognizes your account and loads your saved data.

Code overview #

Main controller (NakamaCloudSaveController.cs) #

Handles all core operations including authentication and cloud storage.

Authentication

Supports both device authentication and Facebook authentication:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Device authentication using device ID
private async Task AuthenticateWithDevice()
{
    var deviceId = PlayerPrefs.GetString("deviceId", SystemInfo.deviceUniqueIdentifier);
    session = await client.AuthenticateDeviceAsync(deviceId);
}

// Facebook authentication
private async void AuthenticateWithFacebook()
{
    // Authenticate with Facebook if session does not exist, otherwise link to Facebook
    if (session != null)
    {
        await client.LinkFacebookAsync(session, AccessToken.CurrentAccessToken.TokenString, false);
    }
    else
    {
        session = await client.AuthenticateFacebookAsync(AccessToken.CurrentAccessToken.TokenString, null, true, false);
    }
}

Cloud storage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// Save data to Nakama cloud storage
private async Task HandleSubmitData(int points)
{
    var pointsData = new PointsData
    {
        points = points,
        timestamp = System.DateTime.UtcNow.ToString("o")
    };

    var writeObject = new WriteStorageObject
    {
        Collection = "points",
        Key = "latest_points",
        Value = pointsData.ToJson(),
        PermissionRead = 1,  // Only server and owner can read
        PermissionWrite = 1  // Only server and owner can write
    };

    await client.WriteStorageObjectsAsync(session, new IApiWriteStorageObject[] { writeObject });
}

// Load data from cloud storage
private async Task LoadLatestData()
{
    var readObjectId = new StorageObjectId
    {
        Collection = "points",
        Key = "latest_points",
        UserId = session.UserId
    };

    var result = await client.ReadStorageObjectsAsync(session, new IApiReadStorageObjectId[] { readObjectId });

    // Process retrieved data and update UI
    if (result.Objects.Any())
    {
        var pointsData = result.Objects.First().Value.FromJson<PointsData>();
        pointsLabel.text = $"Points: {pointsData.points}";
    }
}

Account Switcher

The Account Switcher lets you explore the project as different players without managing multiple builds. Use it to test features from different accounts.

How to use:

1. Open the Account Switcher panel (Tools > Nakama > Account Switcher).
2. Select different accounts from the dropdown to switch between up to four test users.
3. Each account is automatically created the first time you select it.

Key points:

• Only works while your game is running in Play mode.
• Usernames will display in the panel after switching to an account for the first time.

Setting up your own Nakama server

While this project works with our demo server, you'll want to set up your own Nakama instance to customize the features and configurations. Using Docker, you can get up and running in minutes.

Read the full setup guide: Nakama Installation Docs

Connect this Unity Project to your Server

After installing Nakama and running it locally, edit these settings in the Unity Editor to connect it to your server:

1. Select the main controller component from the scene hierarchy panel.
2. Open the Inspector tab.
3. Look for the field inputs under Nakama Settings and replace them with the following:
   1. Scheme: http
   2. Host: 127.0.0.1
   3. Port: 7350
   4. Server Key: defaultkey

Additional resources

• Authentication concept guide
• Storage Engine concept guide
• Nakama Unity SDK guide
• Community forum