GSB SDK Quickstart

Pick your engine. Copy the snippet. Authenticate a player and write a save in under 5 minutes. No SDK download, no auth backend to spin up.

Roblox Unity Godot JavaScript curl / any HTTP

Before you start (2 minutes)

  1. Sign up at gsb.supercraft.host/signup/
  2. Create a project and an environment (e.g. dev)
  3. Copy your publishable API key (starts with gsb_pub_) and the environment ID

🎮 Roblox (Lua) — guest auth + save state

Place this in a ServerScriptService script. Calls go through HttpService, which must be enabled in Game Settings → Security. 

local HttpService = game:GetService("HttpService")
local Players = game:GetService("Players")

local GSB_BASE = "https://gsb.supercraft.host/v1"
local PUB_KEY  = "gsb_pub_REPLACE_ME"
local ENV_ID   = "env_REPLACE_ME"

local function gsbCall(path, payload)
    return HttpService:RequestAsync({
        Url = GSB_BASE .. path,
        Method = "POST",
        Headers = {
            ["Content-Type"]   = "application/json",
            ["X-GSB-Key"]      = PUB_KEY,
            ["X-GSB-Env"]      = ENV_ID,
        },
        Body = HttpService:JSONEncode(payload),
    })
end

Players.PlayerAdded:Connect(function(player)
    -- 1. Mint a guest session for this Roblox player
    local sess = gsbCall("/auth/guest", {
        external_id = "roblox:" .. player.UserId,
        display_name = player.Name,
    })
    local body = HttpService:JSONDecode(sess.Body)
    local token = body.access_token

    -- 2. Read or create their save document
    local save = gsbCall("/players/me/state", {
        token = token,
        patch = { lastSeen = os.time(), level = 1 },
    })
    print("GSB save synced for", player.Name, save.Body)
end)

🎯 Unity (C#) — email auth + leaderboard write

Drop this on any GameObject. Uses UnityWebRequest; works in dedicated server builds, standalone, and WebGL. 

using System.Collections;
using System.Text;
using UnityEngine;
using UnityEngine.Networking;

public class GsbClient : MonoBehaviour
{
    const string GsbBase = "https://gsb.supercraft.host/v1";
    const string PubKey  = "gsb_pub_REPLACE_ME";
    const string EnvId   = "env_REPLACE_ME";

    string accessToken;

    IEnumerator Start()
    {
        // 1. Sign in (or sign up) with email/password
        yield return Login("player@example.com", "secret");

        // 2. Submit a leaderboard score
        yield return SubmitScore("weekly_solo", 12750);
    }

    IEnumerator Post(string path, string body, System.Action<string> onOk)
    {
        var req = new UnityWebRequest(GsbBase + path, "POST");
        req.uploadHandler   = new UploadHandlerRaw(Encoding.UTF8.GetBytes(body));
        req.downloadHandler = new DownloadHandlerBuffer();
        req.SetRequestHeader("Content-Type", "application/json");
        req.SetRequestHeader("X-GSB-Key", PubKey);
        req.SetRequestHeader("X-GSB-Env", EnvId);
        if (!string.IsNullOrEmpty(accessToken))
            req.SetRequestHeader("Authorization", "Bearer " + accessToken);
        yield return req.SendWebRequest();
        if (req.result == UnityWebRequest.Result.Success) onOk(req.downloadHandler.text);
        else Debug.LogError("GSB error: " + req.error + " " + req.downloadHandler.text);
    }

    IEnumerator Login(string email, string password)
    {
        var json = "{\"email\":\"" + email + "\",\"password\":\"" + password + "\"}";
        yield return Post("/auth/login", json, resp => {
            accessToken = JsonUtility.FromJson<TokenResp>(resp).access_token;
        });
    }

    IEnumerator SubmitScore(string boardId, int score)
    {
        var json = "{\"board_id\":\"" + boardId + "\",\"score\":" + score + "}";
        yield return Post("/leaderboards/submit", json, resp => Debug.Log(resp));
    }

    [System.Serializable] class TokenResp { public string access_token; public string player_id; }
}

🤖 Godot (GDScript) — server registry + heartbeat

Server-side script. Registers your dedicated server with GSB so a matchmaker can hand sessions to clients. 

extends Node

const GSB_BASE = "https://gsb.supercraft.host/v1"
const PUB_KEY  = "gsb_pub_REPLACE_ME"
const ENV_ID   = "env_REPLACE_ME"

var http := HTTPRequest.new()
var server_id := ""

func _ready() -> void:
    add_child(http)
    register_server()

func register_server() -> void:
    var headers = [
        "Content-Type: application/json",
        "X-GSB-Key: %s" % PUB_KEY,
        "X-GSB-Env: %s" % ENV_ID,
    ]
    var payload = JSON.stringify({
        "name": "MyGodotServer-EU",
        "region": "eu-west",
        "host": "203.0.113.42",
        "port": 8910,
        "max_players": 16,
        "tags": ["pve", "modded"],
    })
    http.request_completed.connect(_on_register_done)
    http.request("%s/servers/register" % GSB_BASE, headers, HTTPClient.METHOD_POST, payload)

func _on_register_done(_result, _code, _hdr, body) -> void:
    var data = JSON.parse_string(body.get_string_from_utf8())
    server_id = data.id
    print("Registered with GSB as ", server_id)
    # Start a heartbeat timer (every 30s) using server_id

func heartbeat(current_players: int) -> void:
    var headers = [
        "Content-Type: application/json",
        "X-GSB-Key: %s" % PUB_KEY,
        "X-GSB-Env: %s" % ENV_ID,
    ]
    var payload = JSON.stringify({
        "server_id": server_id,
        "current_players": current_players,
    })
    http.request("%s/servers/heartbeat" % GSB_BASE, headers, HTTPClient.METHOD_POST, payload)

📦 JavaScript / TypeScript (any web client)

Works in browser games, Electron, Node tools, and Cloudflare Workers. 

const GSB_BASE = "https://gsb.supercraft.host/v1";
const PUB_KEY  = "gsb_pub_REPLACE_ME";
const ENV_ID   = "env_REPLACE_ME";

async function gsb(path, body, token) {
  const res = await fetch(GSB_BASE + path, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-GSB-Key": PUB_KEY,
      "X-GSB-Env": ENV_ID,
      ...(token ? { Authorization: \`Bearer \${token}\` } : {}),
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(\`GSB \${res.status}: \${await res.text()}\`);
  return res.json();
}

// 1. Guest auth
const session = await gsb("/auth/guest", { display_name: "Player1" });

// 2. Save state (player-scoped JSON document)
await gsb("/players/me/state", {
  patch: { progression: { level: 4, xp: 12500 } },
}, session.access_token);

// 3. Read leaderboard
const board = await gsb("/leaderboards/get", {
  board_id: "weekly_solo",
  top: 50,
});
console.log(board.entries);

🌐 curl / any HTTP client

For C++ engines, custom dedicated servers, scripting from CI, or anything not in the list above. The API is plain HTTP+JSON. 

# 1. Mint a guest session
curl -X POST https://gsb.supercraft.host/v1/auth/guest \
  -H "Content-Type: application/json" \
  -H "X-GSB-Key: gsb_pub_REPLACE_ME" \
  -H "X-GSB-Env: env_REPLACE_ME" \
  -d '{"display_name":"Tester"}'

# Response: {"access_token":"eyJ...","player_id":"plr_..."}

# 2. Write player state
curl -X POST https://gsb.supercraft.host/v1/players/me/state \
  -H "Content-Type: application/json" \
  -H "X-GSB-Key: gsb_pub_REPLACE_ME" \
  -H "X-GSB-Env: env_REPLACE_ME" \
  -H "Authorization: Bearer eyJ..." \
  -d '{"patch":{"unlocks":["sword","shield"],"coins":250}}'

# 3. Submit a leaderboard score
curl -X POST https://gsb.supercraft.host/v1/leaderboards/submit \
  -H "Content-Type: application/json" \
  -H "X-GSB-Key: gsb_pub_REPLACE_ME" \
  -H "X-GSB-Env: env_REPLACE_ME" \
  -H "Authorization: Bearer eyJ..." \
  -d '{"board_id":"weekly_solo","score":12750}'