GameMaker
GameMaker
The wrapper has two files. zokogames.js is an extension file for the HTML5 target and talks to the SDK. zokogames_sim.gml is a GML script for every other target (Windows, macOS, Linux and so on); it defines the same zoko_* functions and answers through the same event layout, so a game runs unchanged in the IDE. The simulator needs GameMaker 2023.1 or newer.
Install#
- Create an extension and add
zokogames.jsto it. Enable it for the HTML5 target only, and register every function from the tables below (GameMaker needs each function declared in the extension; the names are exactly thezoko_...names shown). - Add
zokogames_sim.gmlas a script asset, or as a second extension file that is excluded from HTML5, so the non-web targets have the functions too. - In Game Options > HTML5, add
<script src="https://sdk.zokogames.com/zokogames-sdk-v1.js"></script>to the index file so the SDK loads before the game starts. - Call
zoko_init()once, in the first room's Create event.
To tune the simulator, edit global.zoko_sim_config before calling zoko_init(): disabled, account_available, logged_in, username, user_id, friend_count, ad_behaviour ("fill", "no_fill" or "error"), ad_duration (seconds), adblock, mute_audio, disable_chat, verbose.
How calls work#
Functions are named zoko_<module>_<method> in snake_case.
- Asynchronous functions return a request id (a real number) immediately. The result arrives later in an Async - Social event.
- Synchronous functions (state, settings and cloud save reads) return a value directly. Booleans are
1or0; structured values are JSON strings, so wrap them injson_parse.
Every Async - Social event from the wrapper has async_load[? "type"] == "zoko". Look at async_load[? "event"]:
| Event | When | Useful fields |
|---|---|---|
response |
An asynchronous call finished | request_id, method, ok (1 or 0), result (JSON string), error_code, error_message |
ad_started |
The ad began; pause and mute | request_id |
ad_finished |
The ad ended; resume | request_id |
ad_error |
The ad failed; resume | request_id, error_code, error_message |
settings_changed |
The portal changed mute or chat | result (JSON of { disableChat, muteAudio }) |
auth_changed |
A player logged in | result (JSON of the user) |
join_room |
The player joined through an invite | result (JSON of the invite parameters) |
request_id is 0 for events that are not tied to one call.
Functions#
| JavaScript | GML |
|---|---|
SDK.init() |
zoko_init() (event response, method init) |
SDK.environment |
zoko_environment(), zoko_is_initialized(), zoko_is_qa_tool() |
SDK.ad.requestAd(type) |
zoko_ad_request_ad("midgame") or "rewarded" |
SDK.ad.hasAdblock() |
zoko_ad_has_adblock() |
SDK.banner.requestBanner(...) |
zoko_banner_request_banner(id, width, height, x, y, w, h, area_w, area_h) |
SDK.banner.requestResponsiveBanner(id) |
zoko_banner_request_responsive_banner(id, x, y, w, h, area_w, area_h) |
SDK.banner.clearBanner(id) |
zoko_banner_clear_banner(id), zoko_banner_clear_all_banners() |
SDK.game.gameplayStart() |
zoko_game_gameplay_start(), zoko_game_gameplay_stop() |
SDK.game.loadingStart() |
zoko_game_loading_start(), zoko_game_loading_stop() |
SDK.game.happytime() |
zoko_game_happytime() |
SDK.game.reportGameCompletedPercentage(n) |
zoko_game_report_game_completed_percentage(n) |
SDK.game.setGameContext(obj) |
zoko_game_set_game_context(json), zoko_game_clear_game_context() |
SDK.game.updateRoom(u) |
zoko_game_update_room(json), zoko_game_left_room() |
SDK.game.inviteLink(p) |
zoko_game_invite_link(json) |
SDK.game.settings |
zoko_game_get_settings() (JSON string) |
SDK.game.isInstantMultiplayer |
zoko_game_is_instant_multiplayer() |
SDK.game.inviteParams, getInviteParam(k) |
zoko_game_get_invite_params() (JSON), zoko_game_get_invite_param(key) |
SDK.user.isUserAccountAvailable |
zoko_user_is_account_available() |
SDK.user.systemInfo |
zoko_user_get_system_info() (JSON string) |
SDK.user.getUser() |
zoko_user_get_user() |
SDK.user.listFriends(opts) |
zoko_user_list_friends(page, size) |
SDK.user.getUserToken(opts) |
zoko_user_get_user_token(signing_key_type) (pass "" for the default) |
SDK.user.showAuthPrompt() |
zoko_user_show_auth_prompt() |
SDK.user.showAccountLinkPrompt() |
zoko_user_show_account_link_prompt() |
SDK.user.submitScore(opts) |
zoko_user_submit_score(encrypted_score, score) |
SDK.data.getItem(k) |
zoko_data_get_item(key) ("" when missing), zoko_data_has_key(key) |
SDK.data.setItem(k, v) |
zoko_data_set_item(key, value), zoko_data_remove_item(key), zoko_data_clear(); each returns 1 or 0, and zoko_data_get_last_error() returns the error as JSON |
SDK.analytics.trackOrder(p, o) |
zoko_analytics_track_order(provider, order_json) |
Banner rectangles are in pixels of the area you describe with area_w and area_h (pass 0 to use the browser window size).
Examples#
Ads#
// Create event of obj_game
zoko_init();
paused_for_ad = false;
// Where the player reaches a break
zoko_ad_request_ad("midgame");
// Async - Social event
if (async_load[? "type"] == "zoko") {
switch (async_load[? "event"]) {
case "ad_started":
paused_for_ad = true;
audio_pause_all();
break;
case "ad_finished":
case "ad_error":
paused_for_ad = false;
audio_resume_all();
break;
}
}Settings#
// Async - Social event
if (async_load[? "type"] == "zoko" && async_load[? "event"] == "settings_changed") {
var s = json_parse(async_load[? "result"]);
audio_master_gain(s.muteAudio ? 0 : 1);
}Banners#
zoko_banner_request_banner("menu", 300, 250, x, y, 300, 250, room_width, room_height);
// leave the screen:
zoko_banner_clear_all_banners();Game#
zoko_game_gameplay_start();
zoko_game_report_game_completed_percentage(25);User#
global.token_request = zoko_user_get_user_token("");
// Async - Social event
if (async_load[? "type"] == "zoko" && async_load[? "event"] == "response"
&& async_load[? "request_id"] == global.token_request) {
if (async_load[? "ok"]) { var token = json_parse(async_load[? "result"]); /* send to your server */ }
else { global.guest = true; }
}Data#
var level = real(zoko_data_has_key("level") ? zoko_data_get_item("level") : "1");
if (!zoko_data_set_item("level", string(level + 1))) {
show_debug_message(zoko_data_get_last_error()); // for example dataLimitExceeded
}Analytics#
zoko_analytics_track_order("provider-name", json_stringify({ sku: "gems_100", price: 0.99 }));Tips#
- The HTML5 target is single-threaded; keep your step event cheap while ads show.
- Use texture groups so only the first room's textures are in the initial download.
- Run the exported game in the preview tool to see every call.