Godot SDK

Refer to the Installation section for installation information.

The SDK is an editor addon written in GDScript. Its entry point is the Gamebeast autoload, registered when you enable the addon, so there is one SDK per running game. Every service hangs off it: Gamebeast.markers, Gamebeast.configs, Gamebeast.experiments and Gamebeast.cohorts.

Calling into Gamebeast from GodotCopy Anchor Link

extends Node

func _ready() -> void:
	var options := GamebeastOptions.with_api_key("abcd-efgh-1234-5678")
	options.configurations = ["MyConfig"]
	Gamebeast.setup(options)

The SDK can also start itself from Project Settings, with no setup code. See Automatic initialization below.

From C#Copy Anchor Link

The SDK is GDScript, so C# calls it through Godot's dynamic API on the autoload node:

var gamebeast = GetNode("/root/Gamebeast");
var markers = gamebeast.Get("markers").AsGodotObject();
markers.Call("send_marker", "LevelCompleted", new Godot.Collections.Dictionary { { "Level", 3 } });

var configs = gamebeast.Get("configs").AsGodotObject();
float speed = configs.Call("get_float", "MyConfig.PlayerSpeed", 16.0f).AsSingle();

Autoload methodsCopy Anchor Link

setup(options)Copy Anchor Link

→voidreturn type

Starts the SDK. If it's already running, the call is ignored with a warning (call shutdown first). Before setup, services log a warning and do nothing. The initialized signal fires once it's set up.

TypesCopy Anchor Link

class_name GamebeastOptions

# Your project's SDK Key. Required.
var api_key: String

# Optional id for the local player. When empty, the SDK generates an anonymous id on first
# launch and saves it on the device, so the same player is reported across sessions.
var distinct_id: String

# Optional: "production" or "development". Leave it unset and the SDK resolves it:
# development in the editor and debug exports, production in release exports.
var environment: String

# Optional: configurations to load at startup, by alias. They gate configs_ready.
var configurations: PackedStringArray

# Optional targeting properties for experiments: strings, numbers, booleans, or arrays of
# one of those.
var user_properties: Dictionary

# How often the SDK talks to Gamebeast. -1 is automatic. See Settings below.
var marker_flush_interval_sec: float
var marker_batch_size: int
var status_poll_interval_sec: float
var config_refresh_interval_sec: float

# Start a new session after this many seconds in the background.
var session_timeout_sec: float

# Warnings for API misuse and failed requests. Errors always print.
var warnings_enabled: bool

# Verbose logs.
var debug_logging: bool

# Override the Gamebeast API base URL. Leave empty.
var api_url: String

UsageCopy Anchor Link

var options := GamebeastOptions.with_api_key("abcd-efgh-1234-5678")
options.distinct_id = "player-123"
options.configurations = ["MyConfig"]
options.user_properties = {"vip": true}
Gamebeast.setup(options)

identify(distinct_id)Copy Anchor Link

→voidreturn type

Switches the local player's distinct id, for example after a login. Configurations are re-evaluated for the new player right away, and experiment assignments update with them. Markers recorded before the switch keep the id they were recorded under. The identity_changed signal fires with the new id.

The id is not saved. Call identify again on the next launch once your login state is restored, or pass it in GamebeastOptions.distinct_id.

UsageCopy Anchor Link

Gamebeast.identify("player-123")

reset_identity()Copy Anchor Link

→voidreturn type

Goes back to the device's anonymous distinct id, for example after a logout.

set_user_properties(properties) and set_user_property(key, value)Copy Anchor Link

→voidreturn type

Replaces the targeting properties, or sets one of them (null removes it). Configurations are re-evaluated right away, so a player who becomes eligible for a targeted experiment is enrolled without waiting for the next check. get_user_properties() returns the current ones.

UsageCopy Anchor Link

Gamebeast.set_user_property("vip", true)

update_settings(settings)Copy Anchor Link

→voidreturn type

Changes settings while the game runs: the marker, refresh, session and logging settings. The key, environment and API URL are fixed at setup. Values out of range are clamped with a warning.

UsageCopy Anchor Link

Gamebeast.update_settings({"status_poll_interval_sec": 120.0})

shutdown()Copy Anchor Link

→voidreturn type

Saves buffered markers to the device (they're sent on the next launch) and stops the SDK. setup may be called again afterwards.

get_distinct_id(), get_session_id(), get_environment(), is_initialized()Copy Anchor Link

The effective distinct id (the one supplied, or the anonymous one), the current session id, the environment alias the SDK reports to (production, development, or a custom alias), and whether setup has run. The strings are empty before setup.

Automatic initializationCopy Anchor Link

Instead of calling setup, let the SDK start itself:

1. Open Project > Project Settings > Gamebeast > General.
2. Paste your SDK Key into Api Key, set any other options, and leave Auto Initialize on.

The SDK starts on the first frame after the main scene loads. A setup call in your main scene's _ready runs before that, so it takes precedence. distinct_id and user_properties aren't in Project Settings: use setup or identify for those.

SettingsCopy Anchor Link

How often the SDK talks to Gamebeast. Set them under Project Settings > Gamebeast > Advanced (turn on Advanced Settings to see them), in GamebeastOptions, or at runtime with update_settings. -1 is automatic: quick in the editor and debug exports so your changes show up while you test, lighter in release exports.

With status_poll_interval_sec at 0, the release default of config_refresh_interval_sec is 60 seconds. A value out of range is clamped, with a warning in the log.

EnvironmentsCopy Anchor Link

One setting picks the environment: Environment under Project Settings > Gamebeast > General, or GamebeastOptions.environment. Leave it unset and the SDK resolves it; set production or development and that environment is used everywhere.

Custom environments are coming soon. Until then, any other value logs a warning and the SDK resolves the environment as if it were unset.

Web exportsCopy Anchor Link

• When the tab is hidden or closed, waiting markers are handed to fetch(..., {keepalive: true}) requests, which the browser completes after the page unloads. What doesn't fit the browser's 64 KiB keepalive budget is saved and sent on the next visit.
• Markers saved while the browser is offline are sent once it's back online.
• UTM parameters on the page URL are attached to every marker, and a utm_id=gb_<slug> link is recorded as a Gamebeast deeplink.

HeatmapsCopy Anchor Link

The Gamebeast dock (right side of the editor) manages heatmaps and uploads the image they're drawn over:

1. Enter an SDK Key with the heatmaps permissions and press Fetch heatmaps, then pick one or press New.
2. Select a node at one corner of the area in your scene and press Use selected for corner A, then do the same for corner B. Use Node3Ds in 3D scenes and Node2Ds in 2D scenes.
3. Press Render preview, then Upload. This saves the region and uploads the top-down image.

At runtime, send positions with send_position. The key is saved in the project's editor metadata (.godot/), not in project.godot.

Saved dataCopy Anchor Link

The SDK keeps a few files under user://gamebeast/: the anonymous player id, a cache of each configuration, and markers waiting to be sent. On Web, user:// lives in the browser's IndexedDB. Delete the folder to start over as a new player.