Crux SDKs

Open-source client SDKs for Crux - Crux. One backend, four first-party SDKs, an OpenAPI spec for the rest.

Crux is the hosted backend behind your game: player auth, persistent documents, seasonal leaderboards, economy, matchmaking, a server registry, and signed config delivery. See crux.supercraft.host for the product, /pricing for tiers, /cost-calculator for sizing, and the SDK landing page for non-technical docs.

This repository ships the four first-party SDKs that bind every supported engine to the Crux HTTP API. All are MIT.

---

The four SDKs

SDK	Status	Channel	Folder	README
JavaScript / TypeScript	stable	npm: crux-sdk	sdks/js/	sdks/js/README.md
Godot 4	stable	Godot Asset Library	sdks/godot/	sdks/godot/README.md
Unity	stable	UPM (Git URL) + Asset Store	sdks/unity/	sdks/unity/README.md
Roblox (Luau)	stable	Wally + Toolbox	sdks/roblox/	sdks/roblox/README.md

Need a language we don't list? The openapi/v1.yaml spec is the source of truth - generate a client with openapi-generator and you're done. See docs/ARCHITECTURE.md#openapi-first.

---

What each SDK covers

Feature	JS	Godot	Unity	Roblox
Anonymous + email auth	✅	✅	✅	⚠️ Roblox-native
JWT refresh / logout	✅	✅	✅	n/a
Player Documents (versioned)	✅	✅	✅	✅ (DataStore-compatible API)
Document patch (JSON-Patch)	❌	✅	✅	✅
Batch document read/write	✅	✅	✅	❌
Seasonal Leaderboards	✅	✅	✅	✅
Player Economy	✅	✅	✅	✅
Matchmaking	✅	✅	✅	✅
Server Registry	✅	✅	✅	n/a (Roblox JobId)
Signed Config Delivery	✅	✅	✅	✅

⚠️ Roblox-native means we use HttpService:GetAsync-based player verification instead of email/password - Roblox already has its own identity layer. The "n/a" rows are intentional, not gaps; see each README's "Roblox differences" section for the why.

---

Quick links into the product

Backend concepts (the same docs across every SDK)

• Cross-progression / cross-save patterns
• Player data schema - NoSQL vs SQL
• Guest login and account upgrade
• Skill-based matchmaking architecture
• Game server orchestration guide
• Dedicated server hosting + backend, unified stack
• Live-ops backend features compared
• Game backend as a service - complete guide

Coming from somewhere else?

• Migrate from PlayFab
• Firebase for games - what to use instead
• Beamable vs Crux
• AccelByte vs Crux
• Nakama (open source) vs managed backend
• Colyseus vs managed backend

Roblox-specific

• Roblox HttpService → external backend
• Roblox DataStore vs external database
• Roblox cross-experience progression

---

Repository layout

crux/
├── README.md             you are here
├── RESEARCH.md           why these SDKs exist, OSS landscape, sources
├── CHANGELOG.md          monorepo-level changes
├── CONTRIBUTING.md       dev setup, PR rules, how to add a new language
├── LICENSE               MIT
├── docs/
│   ├── ARCHITECTURE.md   how the SDKs are organized + OpenAPI-first story
│   ├── AUTH.md           the three auth flows (api key / server token / player jwt)
│   └── ERROR_HANDLING.md error model shared across SDKs
├── openapi/
│   └── v1.yaml           OpenAPI 3.0.3 spec - the source of truth
├── sdks/
│   ├── js/               TypeScript SDK (`crux-sdk`)
│   ├── godot/            Godot 4 GDScript addon
│   ├── unity/            Unity UPM package (`host.supercraft.crux`)
│   └── roblox/           Roblox Luau module
└── examples/
    ├── js/leaderboard.ts
    ├── godot/leaderboard.gd
    ├── unity/Leaderboard.cs
    └── roblox/leaderboard.lua

---

Quick start by stack

Five-minute integrations, in their natural form for each engine. Each points at the SDK's own README for the full surface.

Browser / Node.js - crux-sdk

npm install crux-sdk

import { CruxClient } from "crux-sdk";

const crux = CruxClient.forPlayer(
  "https://crux.supercraft.host",
  "<PROJECT_ID>", "<ENVIRONMENT_ID>", "<API_KEY>"
);
const auth = await crux.loginAnonymous();
await crux.submitScore("weekly", auth.player_id, 9900);
const top = await crux.getTop("weekly", 10);

See sdks/js/README.md.

Godot 4 - drop-in addon

Crux.init_player("https://crux.supercraft.host", "<PROJECT_ID>", "<ENVIRONMENT_ID>", "<API_KEY>")
var auth = await Crux.login_anonymous()
await Crux.submit_score("weekly", auth.player_id, 9900.0)

See sdks/godot/README.md.

Unity - UPM via Git URL

git+https://github.com/supercraft-host/crux.git?path=sdks/unity/Packages/host.supercraft.sdk

var crux = CruxClient.ForPlayer(
    "https://crux.supercraft.host", "<PROJECT_ID>", "<ENVIRONMENT_ID>", "<API_KEY>");
var auth = await crux.LoginAnonymousAsync();
await crux.SubmitScoreAsync("weekly", auth.player_id, 9900);

See sdks/unity/README.md.

Roblox - require() the module

local Crux = require(game.ServerScriptService.Crux)
local crux = Crux.init("<PROJECT_ID>", "<SERVER_TOKEN>", "<ENVIRONMENT_ID>")
crux:SubmitScore("weekly", player.UserId, 9900)

See sdks/roblox/README.md.

---

OpenAPI-first

The HTTP wire format is documented in openapi/v1.yaml. Every first-party SDK in this repo is hand-written against that spec, but nothing stops you from autogenerating one for any language:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli \
    generate -i /local/openapi/v1.yaml -g python -o /local/generated-python

See docs/ARCHITECTURE.md for why we hand-write the four first-party SDKs anyway (ergonomics) and when an autogenerated client is enough (CI scripts, dashboards, batch jobs).

---

Contributing

PRs welcome inside the per-SDK scope. Cross-SDK refactors (renaming a method on all four at once) should land in a single MR. See CONTRIBUTING.md.

Want to add a new language (Unreal, Rust, Python, Defold, Haxe, …)? Open an issue first so we can sketch the directory layout and CI plumbing.

---

License

MIT. Use these SDKs however you like, including in commercial games and in tools that talk to non-Crux backends. The OpenAPI spec is also MIT - autogenerated clients inherit the same terms.