Construct 3
Construct 3
The ZokoGames addon is a single-global plugin (zokogames) for Construct 3 SDK v2. It works in worker mode: all SDK work runs on the page's main thread (a DOM-side script) and the runtime exchanges plain results with it.
Install#
- Install the addon (
.c3addon) through Menu > View > Addon Manager. - Add the ZokoGames object to your project. It is a single-global object, so one is enough.
- Run the Initialize action once at the start of the first layout. It loads
https://sdk.zokogames.com/zokogames-sdk-v1.jsand initialises the SDK, so you do not edit the export settings. - Export as an HTML5 web game and upload the zip.
You can leave Use worker mode on.
Tags, results and errors#
Every asynchronous action takes a Tag. When the call ends, either On request completed (with that tag) or On request failed (with that tag) triggers. On any request failed triggers for every failure.
After a call, read what came back from expressions:
| Expression | Contents |
|---|---|
ResultString |
The last result when it is text: a token, an invite link, a saved item. |
ResultNumber |
The last result as a number (booleans are 1 and 0, so Check ad blocker reads ResultNumber). |
ResultJSON |
The last result as JSON (the friends page, the account link answer). |
ErrorCode, ErrorMessage, ErrorContainerId |
Details of the last failure. ErrorContainerId is set for banner errors. |
Actions#
| Group | Actions |
|---|---|
| Start-up | Initialize |
| Ads | Request ad (type midgame or rewarded), Check ad blocker |
| Banners | Request banner (container id, size, rectangle), Request responsive banner, Clear banner, Clear all banners |
| Game | Gameplay start, Gameplay stop, Loading start, Loading stop, Happytime, Report completed percentage, Set game context (JSON), Clear game context |
| Multiplayer | Update room, Left room, Create invite link |
| User | Get user, List friends, Get user token, Show login prompt, Show account link prompt, Submit score |
| Cloud save | Get saved item, Set saved item, Remove saved item, Clear saved data |
| Analytics | Track order |
Banner rectangles are in canvas CSS pixels with the origin at the top left. The addon maps them onto the game canvas for you.
Conditions#
- Status: Is initialized, Is available (false when the SDK is disabled in the embed).
- Ads: On ad started, On ad finished, On ad error, Is ad playing.
- Settings: On settings changed, Is mute requested, Is chat disabled.
- Multiplayer: Is instant multiplayer, On join room.
- Account: On auth changed, Is logged in, Is account available.
Other expressions#
Environment, MuteAudio, DisableChat, InviteParam(key), InviteParamsJSON, UserName, UserPictureUrl, UserId (do not trust it on the client; verify the token on your server), UserToken, FriendCount, FriendsTotal, FriendsHasMore, FriendName, FriendId, FriendPictureUrl, Locale, CountryCode, DeviceType, SavedItem and HasSavedItem.
Event sheet recipes#
Ads#
- On ad started: set time scale to 0, set master volume to 0.
- On ad finished: set time scale to 1, restore volume; grant the reward for rewarded ads.
- On ad error: set time scale to 1, restore volume.
- Wherever you want an ad: Request ad with type
midgameorrewardedand a tag.
Settings#
- On settings changed: if Is mute requested set master volume to 0, otherwise restore it.
Cloud save#
- Set saved item: key
coins, valuestr(Coins). Values are text; the total is limited to 1 MiB. - Later, Get saved item with key
coins. In On request completed useSavedItemorResultString.
User token#
Get user token (leave the key type default, or choose in-game auth) and send UserToken to your server, which verifies it. See user.
Scripting#
You can still call the SDK directly from a script file; it is the same SDK the addon uses.
runOnStartup(async (runtime) => {
const SDK = globalThis.ZokoGames.SDK;
await SDK.init();
runtime.globalVars.Ready = 1;
});Call scripting only after the Initialize action has run, so the SDK script is on the page.
Tips#
- Keep sound and music on separate buses so you can mute everything in On ad started.
- Large Construct projects load every layout's data up front; split rarely used layouts to cut the initial download.
- Check your calls in the preview tool.