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#
- Copy
addons/zokogamesinto your project'sres://addons/folder. - Open Project > Project Settings > Plugins and enable ZokoGames. This registers the autoload
ZokoGamesand the simulator settings. - Open Project > Export, add a Web preset and set HTML > Custom HTML Shell to
res://addons/zokogames/export/zokogames_shell.html. The shell loadszokogames-sdk-v1.jsbefore the engine and creates the bridge object (ZokoBridge) the addon expects. - Call
ZokoGames.init()once at startup, before any other call.
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 dataLimitExceededdata_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
.pcksmall and compress textures, see optimisation. - Run the exported build in the preview tool to check your calls and the launch requirements.