The Construct Game Services (CGS) plugin allows accessing game services hosted by Scirra, the makers of Construct. Features include authentication and submitting high scores both for the Construct Arcade and cross-platform leaderboards.
Scripting
When using JavaScript or TypeScript coding, the features of this object can be accessed via the ICGSObjectType script interface.
Authentication
If you want to allow the player to sign in, you can make a login system with these steps.
- In your Construct Game Services account, create a game. Take note of the game ID.
- Use an action like Sign in with provider to provide a login using one of several existing account providers like Google, Microsoft or Steam. (You may want to allow multiple providers.) You'll need to specify the game ID to sign in to.
- When the player chooses this option, a popup window will appear asking them to log in, or if they are already logged in, to confirm that they wish to proceed.
- If the player signs in successfully, then On success will trigger for Sign in with provider. You can then access the PlayerName and PlayerID expressions, and make use of other features like submitting scores to cross-platform leaderboards.
Sign in persistent
If the user signs in with Allow persisting enabled, then their sign in is remembered. Upon returning the Can sign in persistent condition will be true, and you can offer an option to log in again using the Sign in persistent action. This can continue with the previous sign in without showing any user interface.
If the user signs out, it will delete their remembered sign in, so Can sign in persistent will not be true when they return to your game.
Leaderboards
Scores can be submitted to either the Construct Arcade or a cross-platform leaderboard.
Construct Arcade leaderboards
To publish a game to the Construct Arcade with leaderboards, follow these steps:
- Add the Construct Game Services plugin to your project
- Add a Submit score action to submit the player's score at the appropriate time (such as when a 'Game over' screen appears). Leave the Leaderboard ID parameter empty.
- Publish to the Construct Arcade following the normal process
- Play your game until a score is submitted
- Reload the page and a leaderboard will have appeared with your score
Note that you do not need to add any authentication features to your project to submit a score to the Construct Arcade, as it handles authentication automatically.
Cross-platform leaderboards
To make use of leaderboards on other platforms, follow these steps:
- In your Construct Game Services account, create a game (if you haven't already), and then create a leaderboard in that game. Take note of both the game ID and leaderboard ID.
- Add a sign-in feature to your game using the authentication features, as players must be signed in to be able to submit a score. You'll need to specify the game ID to sign in to.
- Once a player is signed in, you can use the Submit score action, specifying the leaderboard ID to submit to.
You should then be able to find the score on the leaderboard in your Construct Game Services account. You can display scores in your game using the Get leaderboard scores action.
CGS conditions
- Can sign in persistent
- True if the user previously successfully signed in when Allow persisting was enabled and did not sign out. This means the Sign in persistent action can be used to continue with the previous sign in.
- Is signed in
- True if the user is currently signed in.
- On success
- On error
- Triggered after an action depending on whether it completed successfully or failed.
CGS actions
- Sign in with provider
- Attempt to sign the user in with a third-party identity service like Google or Microsoft. The game ID to sign in to from your Construct Game Services account must be provided. If Allow persisting is enabled, a successful sign in is remembered, and may be re-used in future with the Sign in persistent action. The Expiry is the time in minutes that sessions remain active. Signing in with a provider will open a popup window, and you can also specify the size of this popup window. Upon completing a sign in, On success will trigger for sign in with provider. In some cases if the sign in is cancelled or fails, On error will trigger.
- Sign in persistent
- Attempt to sign in re-using a previous successful sign in that allowed persisting. This can only be used when Can sign in persistent is true. This will trigger either On success or On error for sign in persistent depending on whether the persistent sign in completed successfully.
- Sign out
- Sign out of any account the user is currently signed in to, and also delete any remembered sign in if it allowed persisting. Locally this operation completes immediately and so there is no corresponding success or error trigger. For completeness signing out will send a request in the background to ensure the session is ended on the server-side as well, but that is optional and if it fails the session will time out anyway.
- Submit score
- Submit a score to a leaderboard. The Score must be an integer (fractional scores are not supported). The Leaderboard ID may be left empty to submit a score on the Construct Arcade, which does not require authentication. Otherwise it may be set to the leaderboard ID to submit the score to, in which case authentication is required.
- Get leaderboard scores
- Request a page of scores from a given leaderboard ID, with a specified zero-based page number and number of results per page. This does not require authentication. The returned scores can optionally be filtered with several options. An ISO 3166-1 alpha-2 country code filter can be provided, e.g. "US" to only return scores submitted in the United States of America. A time range can also be specified, such as Daily to return today's scores. Weekly leaderboards run from Monday to Sunday. A range offset can also be specified to return a prior range - for example specifying a Daily range with offset 1 will return yesterday's scores. The Culture can be set to a locale to use for returned values, or left empty to use the leaderboard's default culture. On success will trigger for get scores when scores are retrieved successfully, in which case the leaderboard expressions can be used to access them.
CGS expressions
- GameID
- A string of the game ID currently signed in to.
- PlayerID
- A string with a unique ID to identify the currently signed in player.
- PlayerName
- The display name of the currently signed in player.
- ScoreCount
- After successfully retrieving leaderboard scores, the number of scores available.
- ScoreAt(index)
- ScoreFormattedAt(index)
- ScoreRankAt(index)
- ScoreFormattedRankAt(index)
- ScorePlayerIDAt(index)
- ScorePlayerNameAt(index)
- ScoreCountryAt(index)
- After successfully retrieving leaderboard scores, these expressions return information about a score at a given zero-based index. Scores and ranks are numbers, but the formatted versions return a string formatted according to the locale. Countries are returned as ISO 3166-1 alpha-2 country codes.
- TotalPageCount
- After successfully retrieving leaderboard scores, the total number of pages available.