Skip to content
ZokoGames

Log in

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#

  1. Create an extension and add zokogames.js to 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 the zoko_... names shown).
  2. Add zokogames_sim.gml as a script asset, or as a second extension file that is excluded from HTML5, so the non-web targets have the functions too.
  3. 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.
  4. 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 1 or 0; structured values are JSON strings, so wrap them in json_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.

Something unclear, wrong or missing on this page? Tell us through support · Test your game in the preview tool