Getting Started

Load Scene On Event

This script loads the defined scene when the chosen CloudOnce event is called. It can be placed on any GameObject.

One use case for this script is if you have your loading screen as it's own scene, and you want to load a menu scene when a CloudOnce event is called.

You must enter the filename of the scene that is to be loaded (without ".unity"), and the scene must be first be added to Build Settings. You can press Ctrl + Shift + B to open Build Settings.

You have the option to load the scene with additive and/or async. Please refer to the official Unity documentation about these scene loading methods: SceneManager.LoadScene, SceneManager.LoadSceneAsync.

Deactivate On Event

This script deactivates the GameObject it is attached to when the chosen CloudOnce event is called. A use case for this script is if you want to deactivate a loading screen when a CloudOnce event is called.

Show Achievements Button

This script opens the native achievements overlay for the current platform. It will not work in the Unity editor, only on mobile devices. If the player is currently signed out, it will attempt to sign in the player.

This script will only work if placed on a button created from the "GameObject > UI > Button" menu.

Show Leaderboards Button

This script opens the native leaderboards overlay for the current platform. It will not work in the Unity editor, only on mobile devices. If the player is currently signed out, it will attempt to sign in the player.

This script will only work if placed on a button created from the "GameObject > UI > Button" menu.

Google Sign In/Out Button

As stated in the Quality Checklist for Google Play Games Services, you are required to provide players with both a sign-in option and a sign-out option. This script is designed to provide both, with the same button.

It will update the text on a standard GUI button to "Sign in" if the player is currently signed out, and "Sign out" when the player is signed in.

This script will only work if placed on a button created from the "GameObject > UI > Button" menu.

Deactivate If Not Google

This script deactivates the GameObject it is attached to if the current platform is not Google Play. A use case for this script is when using the above Google Sign In/Out Button script, you will likely want the button to only be visible if playing on Google Play.

If you want the button to be visible when testing in the Unity editor, "Active In Editor" must be enabled. This can be useful to see how a menu would look on Google Play, as opposed to other platforms. If you want to see the effect of switching this setting, you'll have to restart the game, as the GameObject is deactivated in the Awake method.

To use CloudOnce, it must first be initialized. The easiest way to do this is to use the above Initialize CloudOnce Quick Start script.

The initialization first tries to sign the user into the current platform's native game services (Game Center/Play Games). If the sign in is successful, it attempts to fetch progress details about any achievements and download any cloud data. If the sign in fails, the system will fall back to using the local cached data. In this scenario you will be able to continue to use the cloud variables, and the system will merge the local data with the cloud data at the next sign in.

The above Quick Start scripts Load Scene On Event and Deactivate On Event work well together with the Initialize CloudOnce Quick Start script.

If you prefer to implement the initialization into one of your existing scripts, you must first add the using directive CloudOnce and then use the method Cloud.Initialize() for initialization. It is recommended to call this method in an Awake method. To know when the initialization is complete you can subscribe to the event Cloud.OnInitializeComplete.

If you don't intend to use Cloud Save in your game, you can disable it by adding false as a parameter to the Initialize method, like this: Cloud.Initialize(false).

You also have to option of disabling auto sign-in and auto load in the Initialize method.

Example code

This example code shows initialization of CloudOnce and subscribing to the event Cloud.OnInitializeComplete.

using CloudOnce;
using UnityEngine;

public class CloudOnceInitializer : MonoBehaviour
{
    private void Awake()
    {
        Cloud.OnInitializeComplete += CloudOnceInitializeComplete;
        Cloud.Initialize();
    }

    public void CloudOnceInitializeComplete()
    {
        Cloud.OnInitializeComplete -= CloudOnceInitializeComplete;

        // Do anything that requires CloudOnce to be initialized,
        // for example disabling your loading screen
    }
}

Platform differences

Hidden achievements work a bit differently on each platform:

• Apple Game Center
  Hidden achievements are revealed if you use any of the three methods; Reveal, Increment or Unlock.
• Google Play Game Services
  You can reveal hidden achievements by using the Reveal method. They are also automatically revealed when they are unlocked.

Keep this in mind when implementing your achievements.

Initial setup

To add achievements to your game, you must first set them up in each platform's developer console and in the CloudOnce editor. Please see the Cloud IDs section above for more information about setting up achievements in the CloudOnce editor.

Each platform gives you a total of 1000 points (or XP) to distribute on achievements. However, iOS allows a maximum of 100 points per achievement, have this in mind when distributing these points.

Implementation

After you have set up all your achievements in the CloudOnce editor, it will generate a static class called Achievements. This class allows you to increment, reveal and unlock your achievements. To access this class in your scripts you must first add the using directive CloudOnce. After that each achievement can be accessed like this Achievements.YourInternalID. Here is a code example where you see the syntax for all three achievement methods:

void GameOver()
{
    // Report on achievements
    Achievements.Score250.Increment(newScore, 250);

    if (_didAmazingThing)
    {
        Achievements.IsAmazing.Unlock();
        Achievements.IsMoreAmazing.Reveal();
    }
}

Don’t worry about calling these methods if the achievements are already unlocked, etc. The states of all the achievements are known before uploading progress, and the methods will ignore the call if there's no change.

Advanced methods

If you need more flexibility than what the generated Achievements class can offer, there are equivalent methods that also take the achievement ID as a string parameter. Note that this is not the internal ID, but the platform ID for the current platform. Here is the same code example as above with the advanced methods:

void GameOver()
{
    // Report on achievements
    Cloud.Achievements.IncrementAchievement(platformID, newScore, 250);

    if (_didAmazingThing)
    {
        Cloud.Achievements.RevealAchievement(platformID);
        Cloud.Achievements.UnlockAchievement(platformID);
    }
}

Native Achievements Overlay

The easiest way to display the native achievements overlay, is to use the above Show Achievements Button Quick Start script.

If you prefer to open the native overlay from one of your existing scripts, you must first add the using directive CloudOnce and then use the method Cloud.Achievements.ShowOverlay().

When the native overlay is showing, your game will be paused and the Unity event MonoBehaviour.OnApplicationPause(bool) is called.

Implementation

After you have set up all your leaderboards in the CloudOnce editor, it will generate a static class called Leaderboards. This class allows you to submit scores to your leaderboards. To access this class in your scripts you must first add the using directive CloudOnce. After that each leaderboard can be accessed like this Leaderboards.YourInternalID. Here is a code example where you see the syntax:

void GameOver()
{
    // Submit to leaderboard
    Leaderboards.HighScores.SubmitScore(score);
}

Even if the player has not set a new high score, you should still submit the score to the leaderboard. This is for seeing daily and weekly scores, etc.

Advanced method

If you need more flexibility than what the generated Leaderboards class can offer, there is an equivalent method that also takes the leaderboard ID as a string parameter. Note that this is not the internal ID, but the platform ID for the current platform. Here is the same code example as above with the advanced method:

void GameOver()
{
    // Submit to leaderboard
    Cloud.Leaderboards.SubmitScore(platformID, score);
}

Native Leaderboards Overlay

The easiest way to display the native leaderboards overlay, is to use the above Show Leaderboards Button Quick Start script.

If you prefer to open the native overlay from one of your existing scripts, you must first add the using directive CloudOnce and then use the method Cloud.Leaderboards.ShowOverlay().

When the native overlay is showing, your game will be paused and the Unity event MonoBehaviour.OnApplicationPause(bool) is called.

Post build steps for tvOS

After building the project, in Xcode:

1. Open Images.xcassets
2. Right click and select Game Center -> New Apple TV Leaderboard
3. Select leaderboard(s) and set the identifier(s) to match your leaderboard id(s)
4. Add graphics to leaderboards