Castle Game Engine

Class TGameService

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleGameService

Declaration

type TGameService = class(TComponent)

Description

Integration with a game service, that can be used to show achievements, leaderboards, and store save games "in the cloud". This integrates with

Usage:

  1. Include the necessary integration code in your Android / iOS project.

    For Android, declare your project type as "integrated" and add the "google_play_games" service inside CastleEngineManifest.xml. See https://castle-engine.io/android-Project-Services-Integrated-with-Castle-Game-Engine .

    For iOS, add the "apple_game_center" service inside CastleEngineManifest.xml. See https://castle-engine.io/ios-Project-Services-Integrated-with-Castle-Game-Engine .

    Build your project with the Castle Game Engine build tool: https://castle-engine.io/build_tool .

  2. Create an instance of this class. Only a single instance of this class is allowed.

  3. Call TGameService.Initialize. You usually do it from TCastleApplication.OnInitialize. The TGameService.Initialize must be called before calling any other method of this class.

  4. Use this to manage achievements, leaderboards and so on.

  5. The user must be "signed in" to the game service.

    The methods that display some user-interface will automatically attempt to sign-in the user if needed. These include ShowAchievements, ShowLeaderboard, ShowSaveGames. So you don't have to do anything before you call them.

    All other methods will not sign-in the user automatically. For example, Achievement or SubmitScore or SaveGameLoad or SaveGameSave. You should always make sure that the user is signed-in before calling them. To do this, pass AutoStartSignInFlow parameter as True to Initialize or call the RequestSignedIn(true). And then wait for the Status property to change to gsSignedIn (you can register OnStatusChanged to be notified about changes).

Hierarchy

Overview

Methods

Protected procedure DoSignedInChanged; virtual; deprecated 'use DoStatusChanged';
Protected procedure DoStatusChanged; 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 function SignedIn: boolean;
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 Status: TGameServiceStatus read FStatus;
Published property OnStatusChanged: TNotifyEvent read FOnStatusChanged write FOnStatusChanged;
Published property OnSignedInChanged: TNotifyEvent read FOnStatusChanged write FOnStatusChanged stored false; deprecated 'use OnStatusChanged';
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; deprecated 'use DoStatusChanged';

Warning: this symbol is deprecated: use DoStatusChanged

 
Protected procedure DoStatusChanged; 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 the service, optionally try to sign-in player.

If the player already connected this application with Google Play Games (Android) or Apple Game Center (iOS), (s)he will be signed-in automatically. If not, player will be asked to sign-in (which means asking to accept permissions on Android) only if AutoStartSignInFlow. So if you want to avoid the initial Google Play Games dialog on Android, just always pass AutoStartSignInFlow=false.

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 the leaderboars or achievements) will be ignored until you call this.

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 Play Games: https://developers.google.com/games/services/common/concepts/savedgames.
Public function SignedIn: boolean;

Is user currently signed-in. Just a shortcut for Status = gsSignedIn check.

Public procedure Achievement(const AchievementId: string);

Report the given achievement as achieved.

For Google Play Games (Android): Use Google Developer Console to define achievements for your game, and use their ids with this method. The achievement ids are autogenerated by Google, they look like CgkIvYuzpZsIEAIQAQ.

For Apple Game Center (iOS): Use iTunes Connect to define achievements for your game, and use their ids with this method. The achievement ids are chosen by you, so you can choose something readable like 'boss_defeated'.

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

Report a score in given leaderboard. Use Google Developer Console (Android) or iTunes Connect (iOS) to create leaderboards for your game, use their ids here.

TODO: Not implemented for Apple Game Center (iOS) yet.

Public procedure RequestPlayerBestScore(const LeaderboardId: string);

Get the best score, if available, for given leaderboard.

This may (after some time, asynchronously) call OnPlayerBestScoreReceived 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 the game service (this method doesn't connect automatically; wait for OnStatusChanged before calling this, if you need).

TODO: Not implemented for Apple Game Center (iOS) yet.

Public procedure RequestSignedIn(const Value: boolean);

Request sign-in or sign-out. The operation will be done asynchronously (it will in most cases require some network communication).

Watch for changes to the Status property. You can register an event on OnStatusChanged to be notified about this.

Public procedure ShowAchievements;

Show the user achievements, using the default UI. Automatically connects (signs-in) player to game services, 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 of the Google Developer Console (Android) or iTunes Connect (iOS). Automatically connects (signs-in) player to game services, if not connected yet.

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

Show the existing saved games stored in the cloud 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 imply that each game service user (Google Play Games user or Apple Game Center user) has only one savegame in the cloud for your game.

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.

Using this requires initializing the game service first, by calling the Initialize with SaveGames parameter set to True. Just like ShowAchievements and ShowLeaderboard, this method automatically signs-in player to game service, if not signed-in 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!), and only then call ShowSaveGames.

TODO: Not implemented for Apple Game Center (iOS) yet.

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 game service, 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 game service. 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 game service (like 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 game service yet (this method does not connect user automatically; wait for OnStatusChanged before calling this method, if you need it).

Properties

Public property Initialized: boolean read FInitialized;

Was the Initialize called.

Public property Status: TGameServiceStatus read FStatus;

Current status of signing-in.

Published property OnStatusChanged: TNotifyEvent read FOnStatusChanged write FOnStatusChanged;

Event called when Status 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 OnSignedInChanged: TNotifyEvent read FOnStatusChanged write FOnStatusChanged stored false; deprecated 'use OnStatusChanged';

Warning: this symbol is deprecated: use OnStatusChanged

 
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.16.0.