Skip to content
ZokoGames

Log in

Godot

Godot

The zokogames addon (addons/zokogames) targets Godot 4 Web exports. It registers one autoload, ZokoGames, that talks to the JavaScript SDK through a small bridge in the export shell. Outside a browser (in the editor, or a desktop run) a built-in simulator answers instead, so the same code runs everywhere.

Install#

  1. Copy addons/zokogames into your project's res://addons/ folder.
  2. Open Project > Project Settings > Plugins and enable ZokoGames. This registers the autoload ZokoGames and the simulator settings.
  3. Open Project > Export, add a Web preset and set HTML > Custom HTML Shell to res://addons/zokogames/export/zokogames_shell.html. The shell loads zokogames-sdk-v1.js before the engine and creates the bridge object (ZokoBridge) the addon expects.
  4. Call ZokoGames.init() once at startup, before any other call.
Important

Without the custom shell window.ZokoBridge does not exist. The addon then logs a warning and falls back to the simulator, so the game runs but no real ads, users or saves are used.

Editor simulator settings appear under Project Settings > zokogames/simulator: ad_behaviour (fill, no_fill, error), ad_duration_seconds, adblock, disabled, account_available, logged_in, username, user_id, friend_count, mute_audio, disable_chat and verbose.

How calls work#

JavaScript names become snake_case. Every method that talks to the portal comes in two forms:

Form Example Use it for
Callback ZokoGames.get_user(callback) Fire-and-forget calls, or when you do not want a coroutine. The last argument is an optional Callable.
Awaitable await ZokoGames.get_user_async() Straight-line code. The name ends in _async.

Both deliver a Dictionary: { "ok": true, "result": <value> } or { "ok": false, "error": { "code": "...", "message": "..." } }.

All methods live directly on the autoload; there are no ad., game. or user. sub-objects.

JavaScript GDScript
SDK.init() await ZokoGames.init_async() or ZokoGames.init(callback)
SDK.environment ZokoGames.environment ("local", "zokogames" or "disabled")
SDK.ad.requestAd(type, cbs) ZokoGames.request_ad(type, callbacks) or await ZokoGames.request_ad_async(type)
SDK.ad.hasAdblock() ZokoGames.has_adblock(callback) or await ZokoGames.has_adblock_async()
SDK.banner.requestBanner(...) await ZokoGames.request_banner_async(id, width, height, window_rect)
SDK.banner.requestResponsiveBanner(id) await ZokoGames.request_responsive_banner_async(id, window_rect)
SDK.banner.clearBanner(id) / clearAllBanners() ZokoGames.clear_banner(id) / ZokoGames.clear_all_banners()
SDK.game.gameplayStart() / gameplayStop() ZokoGames.gameplay_start() / ZokoGames.gameplay_stop()
SDK.game.loadingStart() / loadingStop() ZokoGames.loading_start() / ZokoGames.loading_stop()
SDK.game.happytime() ZokoGames.happytime()
SDK.game.reportGameCompletedPercentage(n) ZokoGames.report_game_completed_percentage(n)
SDK.game.setGameContext(obj) / clearGameContext() ZokoGames.set_game_context(dict) / ZokoGames.clear_game_context()
SDK.game.updateRoom(u) / leftRoom() ZokoGames.update_room(dict) / ZokoGames.left_room()
SDK.game.inviteLink(p) / getInviteParam(k) await ZokoGames.invite_link_async(dict) / ZokoGames.get_invite_param(key)
SDK.game.settings ZokoGames.settings (a Dictionary with disableChat and muteAudio), signal settings_changed
SDK.game.isInstantMultiplayer / inviteParams ZokoGames.is_instant_multiplayer / ZokoGames.invite_params, signal join_room
SDK.user.isUserAccountAvailable / systemInfo ZokoGames.is_user_account_available / ZokoGames.system_info
SDK.user.getUser() await ZokoGames.get_user_async()
SDK.user.getUserToken(opts) await ZokoGames.get_user_token_async(signing_key_type)
SDK.user.showAuthPrompt() await ZokoGames.show_auth_prompt_async(), signal auth_changed
SDK.user.listFriends(opts) await ZokoGames.list_friends_async(page, size)
SDK.user.submitScore(opts) await ZokoGames.submit_score_async(encrypted_score, score)
SDK.data.getItem(k) ZokoGames.data_get_item(key, default) (synchronous)
SDK.data.setItem(k, v) ZokoGames.data_set_item(key, value) (synchronous, returns the result Dictionary)
SDK.analytics.trackOrder(p, o) await ZokoGames.track_order_async(provider, order)

Signals on the autoload: initialized(ok), ad_started, ad_finished, ad_error(error), auth_changed(user), settings_changed(settings), join_room(params).

Examples#

Start-up#

func _ready() -> void:
    var res := await ZokoGames.init_async()
    if not res.ok:
        push_warning("ZokoGames unavailable: %s" % res.error.code)
    ZokoGames.settings_changed.connect(_apply_settings)
    _apply_settings(ZokoGames.settings)
    ZokoGames.loading_stop()

func _apply_settings(s: Dictionary) -> void:
    AudioServer.set_bus_mute(0, s.get("muteAudio", false))

Ads#

Pause and mute in ad_started, resume in ad_finished or ad_error. request_ad_async completes when the ad is over.

func show_midgame() -> void:
    ZokoGames.ad_started.connect(_pause_for_ad, CONNECT_ONE_SHOT)
    var res := await ZokoGames.request_ad_async("midgame")
    get_tree().paused = false
    AudioServer.set_bus_mute(0, ZokoGames.settings.get("muteAudio", false))
    if not res.ok:
        print("ad error: ", res.error.code)

func _pause_for_ad() -> void:
    get_tree().paused = true
    AudioServer.set_bus_mute(0, true)

You can also pass callables: ZokoGames.request_ad("rewarded", {"ad_finished": _grant_reward, "ad_error": _on_ad_error}).

Banners#

Banner rectangles are in window pixels. Drop a ZokoBanner node (a Control) where the banner should be. It reports its own on-screen rectangle, requests on _ready (turn off request_on_ready to control it) and clears itself when it leaves the tree.

Property Meaning
container_id Banner id, default zoko-banner.
size_mode responsive (largest size that fits) or one of 728x90, 300x250, 320x50, 468x60, 320x100.
request_on_ready Request automatically in _ready.

To request by hand, pass a rectangle yourself:

func _ready() -> void:
    var res := await ZokoGames.request_responsive_banner_async("menu", $BannerSlot.get_global_rect())
    if not res.ok:
        $BannerSlot.hide()

Game#

func _on_level_started() -> void:
    ZokoGames.gameplay_start()

func _on_level_ended() -> void:
    ZokoGames.gameplay_stop()
    ZokoGames.report_game_completed_percentage(40.0)

User#

func load_account() -> void:
    var res := await ZokoGames.get_user_token_async()
    if res.ok:
        $HTTPRequest.request(API_URL, ["Authorization: Bearer " + res.result], HTTPClient.METHOD_POST)
    else:
        use_guest()

Data#

Cloud saves are synchronous reads from a preloaded copy; writes upload in the background. Values are Strings, like localStorage, and the total is limited to 1 MiB.

var level := int(ZokoGames.data_get_item("level", "1"))
var res := ZokoGames.data_set_item("level", str(level + 1))
if not res.ok:
    print(res.error.code) # for example dataLimitExceeded

data_has_key, data_remove_item and data_clear are also available.

Analytics#

await ZokoGames.track_order_async("provider-name", {"sku": "gems_100", "price": 0.99})

Tips#

  • Export without threads if you can; the portal iframe does not guarantee the isolation headers that thread support needs.
  • Keep the .pck small and compress textures, see optimisation.
  • Run the exported build in the preview tool to check your calls and the launch requirements.

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