Castle Game Engine

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Class TGooglePlayGames

DescriptionHierarchyFieldsMethodsProperties

Unit

CastleGooglePlayGames

Declaration

type TGooglePlayGames = class(TComponent)

Description

Google Play Games integration (achievements, leaderboards, save games). Right now only on Android (will simply do nothing on other platforms).

Usage:

  1. Create an instance of it (only a single instance allowed).

  2. Call TGooglePlayGames.Initialize at some point. Usually from TCastleApplication.OnInitialize.

  3. Use this to manage Google Games achievements, leaderboards and so on.

  4. To include the necessary integration code in your Android project, declare your Android project type as "integrated" with the "google_play_games" component inside CastleEngineManifest.xml. See https://github.com/castle-engine/castle-engine/wiki/Android-Project-Services-Integrated-with-Castle-Game-Engine .

Hierarchy

  • TComponent
  • TGooglePlayGames

Overview

Methods

Protected procedure DoSignedInChanged; virtual;
Protected procedure DoPlayerBestScoreReceived(const LeaderboardId: string; const Score: Int64); virtual;
Protected procedure DoSaveGameChosen(const Choice: TSaveGameChoice; const SaveGameName: string); virtual;
Protected procedure DoSaveGameLoaded(const Success: boolean; const Content: string); virtual;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Initialize(const AutoStartSignInFlow: boolean = true; const SaveGames: boolean = false);
Public procedure Achievement(const AchievementId: string);
Public procedure SubmitScore(const LeaderboardId: string; const Score: Int64);
Public procedure RequestPlayerBestScore(const LeaderboardId: string);
Public procedure RequestSignedIn(const Value: boolean);
Public procedure ShowAchievements;
Public procedure ShowLeaderboard(const LeaderboardId: string);
Public procedure ShowSaveGames(const Title: string; const AllowAddButton, AllowDelete: boolean; const MaxNumberOfSaveGamesToShow: Integer);
Public procedure SaveGameSave(const SaveGameName, Contents, Description: string; const PlayedTime: TFloatTime);
Public procedure SaveGameLoad(const SaveGameName: string);

Properties

Public property Initialized: boolean read FInitialized;
Public property SignedIn: boolean read FSignedIn;
Published property OnSignedInChanged: TNotifyEvent read FOnSignedInChanged write FOnSignedInChanged;
Published property OnPlayerBestScoreReceived: TPlayerBestScoreEvent read FOnPlayerBestScoreReceived write FOnPlayerBestScoreReceived;
Published property OnSaveGameChosen: TSaveGameChosenEvent read FOnSaveGameChosen write FOnSaveGameChosen;
Published property OnSaveGameLoaded: TSaveGameLoadedEvent read FOnSaveGameLoaded write FOnSaveGameLoaded;

Description

Methods

Protected procedure DoSignedInChanged; virtual;
 
Protected procedure DoPlayerBestScoreReceived(const LeaderboardId: string; const Score: Int64); virtual;
 
Protected procedure DoSaveGameChosen(const Choice: TSaveGameChoice; const SaveGameName: string); virtual;
 
Protected procedure DoSaveGameLoaded(const Success: boolean; const Content: string); virtual;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Initialize(const AutoStartSignInFlow: boolean = true; const SaveGames: boolean = false);

Connect to Google, try to sign-in player. If the player already connected this application with Google Play Games, (s)he will be signed-in automatically, without any dialogs. If the player did not connect with Google Play Games, (s)he will be asked to sign-in (accept permissions etc.) only if AutoStartSignInFlow.

Calling this when already initialized is harmless (will not do anything).

In theory, you can call this at any point in your application. But you probably want to call it early, e.g. from Application.OnInitialize, otherwise user will not be signed-in automatically. Most calls (like sending or showing the leaderboars) will be ignored until you call this. If you want to avoid the initial Google Games dialog, just pass AutoStartSignInFlow=false.

Parameters
SaveGames
Indicates whether you want to use save games feature. You can then use ShowSaveGames, SaveGameSave, SaveGameLoad methods. See also the description of this feature in Google: https://developers.google.com/games/services/common/concepts/savedgames.
Public procedure Achievement(const AchievementId: string);

Report the given achievement as achieved. Use Google Developer Console to create achievements for your game, copy their ids from there.

Public procedure SubmitScore(const LeaderboardId: string; const Score: Int64);

Report a score in given leaderboard. Use Google Developer Console to create leaderboards for your game, copy their ids from there.

Public procedure RequestPlayerBestScore(const LeaderboardId: string);

Get the best score, if available, for given leaderboard. This will (may) eventually (after some unspecified time) call OnPlayerBestScoreReceived event with this score.

Note that no error is signalled if loading the score fails for any reason. This includes failing to load because user is not connected to Google Play Games (this method doesn't connect automatically; wait for OnSignedInChanged before calling this, if you need).

Public procedure RequestSignedIn(const Value: boolean);

Request sign-in or sign-out. This will (may) eventually (after some network delay) change the SignedIn value, also calling OnSignedInChanged event.

Public procedure ShowAchievements;

Show the user achievements, using the default UI. Automatically connects player to Google Play Games, if not connected yet.

Public procedure ShowLeaderboard(const LeaderboardId: string);

Show the given leaderboard, using the default UI. The leaderboard should be created in the Games configuration in the Google Play Developer Console. Automatically connects player to Google Play Games, if not connected yet.

Public procedure ShowSaveGames(const Title: string; const AllowAddButton, AllowDelete: boolean; const MaxNumberOfSaveGamesToShow: Integer);

Show the existing saved games stored in Google Play Games for this user. This can be used to offer user a choice in which slot to save the game, or from which slot to load the game.

Note that it's not necessary to use this method to manage savegames. E.g. if you want, you can just choose a constant savegame name for your game, and use SaveGameSave and SaveGameLoad with this name. This would mean that each Google user has only one savegame in the cloud for your game.

Using this requires being logged to Google Play Games, and the Initialize method must have been called with SaveGames parameter set to True.

The user may choose an existing savegame, or indicate creation of a new savegame (if parameter AllowAddButton is True). In response, the callback OnSaveGameChosen will be called. It will either

  1. indicate the name of an existing savegame user has chosen,

  2. or that user wants to create a new savegame,

  3. or that user cancelled the dialog.

Just like ShowAchievements and ShowLeaderboard, this method automatically connects player to Google Play Games, if not connected yet.

Note that the OnSaveGameChosen callback is not called if the user cancels the sign-in operation, and therefore cancels the savegame choice this way. The same remark applies to all reasons why sign-in may fail (network problems etc.). If this is a problem for your logic (e.g. if you want to "wait" until OnSaveGameChosen is called), then never call ShowSaveGames when SignedIn is False. Instead, call RequestSignedIn, wait until SignedIn changed to True (which may be "never", in case of network problems or user cancelling!), for example using OnSignedInChanged event, and only then call ShowSaveGames.

Parameters
Title
Dialog title to display.
AllowAddButton
Enable user to choose "new save game".
AllowDelete
Enable user to delete savegames from the dialog.
MaxNumberOfSaveGamesToShow
Maximum number of savegames to show. Use -1 to just show all savegames.
Public procedure SaveGameSave(const SaveGameName, Contents, Description: string; const PlayedTime: TFloatTime);

Save a savegame identified by the given name. See the SaveGameLoad documentation about the conflict resolution and valid savegame names.

The Contents should be a valid UTF-8 string. For implementation reasons, you should not save arbitrary binary data this way, for now (or it could result in exceptions about being unable to encode/decode UTF-8 sequences).

Description and PlayedTime are shown to player in ShowSaveGames. PlayedTime may also be used for conflict resolution (if the savegame on the server was modified in the meantime, without loading it in this game).

No callback is called in response, the game is saved in the background.

This does not connect player to Google Play Games, if it's not connected already. An error when saving is not reported back to Pascal, for now. (The assumption here is that you will keep a local savegame anyway, in case user does not connect to Google Play Games. So inability to save the savegame to the cloud is not alarming, and does not require any special reaction. Please submit a request if you'd like to have a callback about it.)

Public procedure SaveGameLoad(const SaveGameName: string);

Load a savegame identified by the given name. If the savegame does not exist, it will be automatically created.

If the server requires conflict resolution, the savegame with longest playtime is used (internally: we use RESOLUTION_POLICY_LONGEST_PLAYTIME flag with Google Play Games). For this to work, you must provide a proper PlayedTime parameter when saving all your savegames through SaveGameSave.

Valid savegame names are defined by Google Play Games: Must be between 1 and 100 non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "˜").

In response, the callback OnSaveGameLoaded will be always called, with the loaded savegame contents (as a string), or the error message.

This does not connect player to Google Play Games, if it's not connected already.

An error will be reported to OnSaveGameLoaded callback if trying to load fails for any reason. This includes the case when loading fails because user is not connected to Google Play Games yet (this method does not connect user automatically; wait for OnSignedInChanged before calling this method, if you need it).

Properties

Public property Initialized: boolean read FInitialized;

Was the Initialize called.

Public property SignedIn: boolean read FSignedIn;

Is user currently signed-in.

Published property OnSignedInChanged: TNotifyEvent read FOnSignedInChanged write FOnSignedInChanged;

Event called when SignedIn changed, for example because RequestSignedIn was called, or because user signs-in automatically (which may happen if you used AutoStartSignInFlow with Initialize, or if user was signed-in in this application previously).

Published property OnPlayerBestScoreReceived: TPlayerBestScoreEvent read FOnPlayerBestScoreReceived write FOnPlayerBestScoreReceived;

Event received in response to RequestPlayerBestScore.

Published property OnSaveGameChosen: TSaveGameChosenEvent read FOnSaveGameChosen write FOnSaveGameChosen;

Event received in response to ShowSaveGames.

Published property OnSaveGameLoaded: TSaveGameLoadedEvent read FOnSaveGameLoaded write FOnSaveGameLoaded;

Event received in response to SaveGameLoad. See TSaveGameLoadedEvent for documentation of parameters.

Generated by PasDoc 0.14.0.