SlateFire developer docs

Everything you need to integrate SlateFire into your Godot 4 project — from the GDScript SDK to the raw HTTP API. Every method, parameter, and response shape documented below comes from the actual addons/slatefire/ source.

Install & setup

1. Install the plugin. Drop the addons/slatefire/ directory into your Godot project, or install from the Asset Library.
2. Enable it. Go to Project → Project Settings → Plugins and toggle SlateFire on. The plugin registers a singleton named SlateFire (extends Node) that is available everywhere in GDScript.

Configure

Call SlateFire.configure() once, typically in your main scene's _ready(). You need a publishable API key from the SlateFire dashboard.

When configure() is called, the SDK automatically:

• Creates all sub-modules (auth, leaderboards, saves, analytics, config)
• Fetches remote config (returns local cache — no backend endpoint yet)
• Sets saves.max_bytes from the save_max_bytes config field (default 245,760 bytes / 240 KB)

set_player_token

Write endpoints (submit score, save data, delete saves) require a player token. Set it after your player authenticates. The SDK does not issue player tokens itself — tokens must be handed to the game client from your own trusted system (or hand-minted for testing).

Make your first call

Here is the full getting-started flow — sign in anonymously, then submit a score and read the leaderboard. All three calls work against the live backend.

All working sign_in_anonymous, leaderboards.submit, leaderboards.top, saves.put, saves.get, and saves.delete all work against the live backend.

SDK Reference

Every public member of the SlateFire singleton and its sub-modules. Methods are tagged by implementation status against the live backend.

SlateFire (singleton)

The autoload registered by the plugin. Extends Node. Created automatically when the plugin is enabled — no manual instantiation.

Properties

configure

Initializes the SDK. Creates sub-modules, fetches config, sets saves.max_bytes. Must be called before any other SDK method. The api_key must not be empty.

Options (all optional):

set_player_token

Sets the HMAC-signed player token sent as x-player-token on write requests. Also notifies SlateFire.auth via _on_token_changed().

Signals

SlateFireResponse

Every await-able SDK call returns one of these.

SlateFireError

SlateFire.auth Working

Player authentication. sign_in_anonymous() works end-to-end: it calls POST /v1/players/anonymous, gets back a signed player token, and automatically sets it on the HTTP client for all subsequent requests. Other sign-in methods (register_email, sign_in_email, etc.) return not_implemented — the backend doesn't have those routes yet.

Properties

Signals

Methods

POSTs to /v1/players/anonymous. On success, automatically sets the returned player token via set_player_token(), populates current_player, sets is_signed_in = true, and emits signed_in.

not_implemented

not_implemented

Where provider is e.g. "steam", "google", "discord", "apple".

not_implemented

not_implemented

not_implemented

Clears current_player, sets is_signed_in = false, and emits signed_out. Works locally only — no network call.

not_implemented

SlateFire.leaderboards

Submit and read leaderboard scores. Boards are created in the developer dashboard. Methods below are tagged with their backend status.

Submits a score for the current player. The server keeps the best score per player (uses ON CONFLICT ... DO UPDATE SET score = MAX(score, excluded.score)).

Success: data is a Dictionary with rank, player_id, display_name, score, metadata, is_current_player.

Errors: invalid_api_key, unauthorized, rate_limited, mau_quota, write_quota, service_paused, score_required (400 if score is missing or not a number).

Returns the top entries for a leaderboard. The count parameter is accepted by the SDK but the backend hard-codes a LIMIT 100 and ignores the count — you always get up to 100 entries regardless of what you pass.

Success: data is an Array of Dictionaries with rank, player_id, display_name, score, metadata, is_current_player.

Errors: invalid_api_key, not_found.

not_implemented — no backend endpoint exists.

not_implemented — no backend endpoint exists.

not_implemented — no friends/social system exists on the backend.

SlateFire.saves

Per-player key/value JSON blobs. The SDK caches reads to user://slatefire/saves/ for offline access.

Writes a JSON save slot. The SDK serializes the Dictionary to JSON, checks the byte size against max_bytes before uploading, and returns save_too_large immediately if it exceeds the limit.

Success: data is a Dictionary with key, data, version, updated_at.

Errors: save_too_large (413, checked client-side before request), invalid_api_key, unauthorized, rate_limited, service_paused.

Reads a save slot. On success, the SDK caches the result to user://slatefire/saves/{key}.json. On failure, it falls back to the cached copy if available.

Success: data is a Dictionary with key, data (parsed JSON Dictionary), version, updated_at. Returns ok: true, data: null if the slot doesn't exist? Actually, the backend returns 404 for missing saves, which the SDK propagates as an error. If cached, it returns the cached copy.

Errors: invalid_api_key, not_found (404).

not_implemented — no backend endpoint exists to list saves.

Deletes a save slot. Also removes the local cache. On success, data is true.

Errors: invalid_api_key, unauthorized, not_found.

SlateFire.analytics Coming soon

Fire-and-forget event tracking. Events queue to user://slatefire/analytics/queue.json but are never flushed — the backend has no analytics endpoint yet.

Appends an event to the local queue with the current timestamp. No network call. The queue persists across sessions.

No-op. Stubbed for future use.

SlateFire.config Local only

Remote feature flags and game balance values. The backend has no config endpoint — config.fetch() returns whatever is cached locally (an empty Dictionary until you populate it).

Signals

Returns a copy of the cached flags. data is a Dictionary.

Each getter checks the cached flags. If the key is missing or the type doesn't match, the default is returned.

HTTP API Reference

For developers integrating without the GDScript SDK, or who want to understand the wire protocol. All endpoints are under the base URL https://slatefire-guard.john-malmin.workers.dev/v1.

Authentication

Every request requires x-api-key (the publishable key). Write operations (POST, PUT, DELETE) also require x-player-token (a signed HMAC token identifying the player).

CORS is open (access-control-allow-origin: *) so browsers can call the API directly.

Error codes

The backend returns error responses as JSON with an error field. The SDK maps these to SlateFireError.code values.

Concepts

API key vs Player token

SlateFire uses a two-key authentication model:

Why two keys? The API key identifies the project. The player token identifies who is acting. Reads (leaderboard top, save load) need only the project key. Writes (score submit, save put) need both, so the server can enforce per-player rate limits, MAU counting, and panic gating.

Plan limits

Every project has a plan that governs resource limits. The backend enforces them server-side — these are walls, not suggestions.

There is also a hard global ceiling of 8 MB per request body, enforced before any plan check. Beyond that, a global monthly write budget of 20 million acts as a circuit breaker — if crossed, the panic flag is set automatically and free-tier projects are blocked from writing (the cron backstop auto-recovers when the count drops below 50% of budget).