Skip to content

README.md

Latest commit

 

History

History
207 lines (161 loc) · 8.41 KB

README.md

File metadata and controls

207 lines (161 loc) · 8.41 KB
Raw

Crux SDKs

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

License: MIT

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)

Coming from somewhere else?

Roblox-specific

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.