Skip to content
ZokoGames

Log in

Defold

Defold

The zokogames library is pure Lua. It evaluates a small JavaScript bridge with html5.run(), loads the ZokoGames SDK script for you, and polls the bridge for results every 50 ms, because Defold cannot receive calls from JavaScript without a native extension. Outside HTML5 (the editor, desktop builds) a Lua simulator answers instead.

Install#

  1. Add the library folder to your project. It is a Defold library project ([library] include_dirs = zokogames), so you can add it as a dependency in game.project once you host the archive, or copy the zokogames folder into your project:
[project]
dependencies#0 = <URL of your zokogames library archive>
  1. Select Project > Fetch Libraries if you used a dependency.
  2. Require the module and call init once, from a script's init function:
local zokogames = require "zokogames.zokogames"

function init(self)
    zokogames.init(function(err)
        if err then print("ZokoGames:", err.code) end
    end)
end

You do not need a custom HTML shell; the module loads https://sdk.zokogames.com/zokogames-sdk-v1.js itself on the first init.

To tune the simulator, set fields on zokogames.sim before init: disabled, account_available, logged_in, username, user_id, friend_count, ad_behaviour ("fill", "no_fill" or "error"), ad_duration, adblock, mute_audio, disable_chat, verbose.

How calls work#

Names are snake_case. Calls that wait for the browser take an optional callback as the last argument with the shape callback(err, result). err is nil on success and a table { code, message } otherwise.

State is available as plain fields once init has finished: zokogames.environment ("local", "zokogames" or "disabled"), is_initialized, is_simulated, is_qa_tool, is_user_account_available, is_instant_multiplayer, system_info, invite_params and settings. zokogames.is_available() is true when initialised and not disabled.

JavaScript Lua
SDK.init() zokogames.init(callback)
SDK.environment zokogames.environment
SDK.ad.requestAd(type, cbs) zokogames.ad.request_ad("midgame", { started = f, finished = f, error = f })
SDK.ad.hasAdblock() zokogames.ad.has_adblock(callback)
SDK.banner.requestBanner(...) zokogames.banner.request_banner(id, width, height, rect, callback)
SDK.banner.requestResponsiveBanner(id) zokogames.banner.request_responsive_banner(id, rect, callback)
SDK.banner.clearBanner(id) / clearAllBanners() zokogames.banner.clear_banner(id, callback) / zokogames.banner.clear_all_banners(callback)
SDK.game.gameplayStart() zokogames.game.gameplay_start(), gameplay_stop, loading_start, loading_stop, happytime, left_room
SDK.game.reportGameCompletedPercentage(n) zokogames.game.report_game_completed_percentage(n, callback)
SDK.game.setGameContext(obj) zokogames.game.set_game_context(table, callback), clear_game_context
SDK.game.updateRoom(u) / inviteLink(p) zokogames.game.update_room(table, callback) / zokogames.game.invite_link(table, callback)
SDK.game.settings zokogames.game.get_settings(), listeners add_settings_change_listener(fn) / remove_settings_change_listener(fn)
SDK.game.addJoinRoomListener(fn) zokogames.game.add_join_room_listener(fn) / remove_join_room_listener(fn)
SDK.game.getInviteParam(k) zokogames.game.get_invite_param(key) (synchronous)
SDK.user.getUser() zokogames.user.get_user(callback)
SDK.user.listFriends(opts) zokogames.user.list_friends(page, size, callback)
SDK.user.getUserToken(opts) zokogames.user.get_user_token(signing_key_type, callback)
SDK.user.showAuthPrompt() zokogames.user.show_auth_prompt(callback), listeners add_auth_listener(fn) / remove_auth_listener(fn)
SDK.user.showAccountLinkPrompt() zokogames.user.show_account_link_prompt(callback)
SDK.user.submitScore(opts) zokogames.user.submit_score(encrypted_score, score, callback)
SDK.data.getItem(k) zokogames.data.get_item(key) (synchronous, nil when missing), has_key, remove_item, clear
SDK.data.setItem(k, v) zokogames.data.set_item(key, value) (returns true, or false and an error table)
SDK.analytics.trackOrder(p, o) zokogames.analytics.track_order(provider, order, callback)

Examples#

Ads#

Pause and mute in started, resume in finished or error.

function show_ad(self)
    local function resume()
        msg.post("@system:", "set_time_step", { factor = 1, mode = 0 })
        sound.set_group_gain("master", 1)
    end
    zokogames.ad.request_ad("midgame", {
        started = function()
            msg.post("@system:", "set_time_step", { factor = 0, mode = 0 })
            sound.set_group_gain("master", 0)
        end,
        finished = resume,
        error = function(err) resume() end,
    })
end

Banners#

Banners are DOM elements drawn over the canvas. Describe where one should sit with a rectangle { x, y, w, h } in window pixels with the origin at the top left, or build one from a GUI node (centred pivot assumed).

local rect = zokogames.banner.rect_from_gui_node(gui.get_node("banner_slot"))
zokogames.banner.request_responsive_banner("menu", rect, function(err)
    if err then print("banner:", err.code) end
end)

Game#

zokogames.game.gameplay_start()
zokogames.game.gameplay_stop()

User#

zokogames.user.get_user_token(nil, function(err, token)
    if err then self.guest = true else http.request(API, "POST", on_response, { Authorization = "Bearer " .. token }) end
end)

Data#

local level = tonumber(zokogames.data.get_item("level") or "1")
local ok, err = zokogames.data.set_item("level", tostring(level + 1))
if not ok then print(err.code) end -- for example dataLimitExceeded

Tips#

  • Defold bundles are already small; use texture profiles and archive compression to stay inside the initial download limit.
  • Call zokogames.game.loading_stop() once your own loading screen is gone.
  • Check the exported build in the preview tool.

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