TypeScript game server SDK
Your game server reaches the functions of your modules for a player it names, and it renames a
player or bans it, through a typed client of its project: the server SDK. In TypeScript it
is a small hand-written core, @rudder/server, and one file rudder server generate writes
from a release. There is also a C# client and a Go client.
The server key of an environment is the secret this client holds: keep it on your game server and never ship it with the game.
Install
Section titled “Install”Point the scope @rudder at the Rudder registry in the .npmrc of the game server:
@rudder:registry=https://hub.rudder.build/api/packages/rudder/npm/then install the package:
npm install @rudder/serverGenerate the client
Section titled “Generate the client”In a repository where rudder project use chose the project:
rudder server generate --lang ts --output src/rudder-server.ts \ --game-address https://api.rudder.build [--environment staging|prod]| Flag | Meaning |
|---|---|
--lang | ts. Required. |
--output | The file to write; its directory is created. Required. |
--game-address | The address the game server reaches Rudder at, https://api.rudder.build, written into the client as its default. Without it the address of the CLI is used. |
--environment | staging or prod: the environment whose newest release the client follows. Without it, the environment of rudder.json. |
--project | Another project than the one of rudder.json. |
The client follows a release, not the draft: it matches what players reach. A module gets a
class and a property named after it (stores, Stores), a method per function, and the types
of their arguments and results. The functions marked server are included: your game server
may call every function. Every method names the player first.
Generate it again when a release changes a function or a type, and commit the file with your game server.
import { RudderServer } from './rudder-server';
const rudder = new RudderServer({ serverKey: process.env.RUDDER_SERVER_KEY! });
const granted = await rudder.inventory.grant(playerId, { item: 'potion' }); // a function marked serverawait rudder.wallet.earn(playerId, 100);
await rudder.setPlayerProfile(playerId, { nickname: 'Ada', avatar: 'https://example.com/ada.png' });await rudder.banPlayer(playerId, { until: '2026-12-01T00:00:00Z', reason: 'cheating' });await rudder.unbanPlayer(playerId);The constructor takes the serverKey of the environment, address (the one given to
--game-address when missing), attempts and fetch.
- Environment.
await rudder.environment()answersstagingorprod: the environment of the server key. The header of the generated client names the environment it was generated from, which can be another one. - Calls. A query reads and a mutation changes data, for the player id the method names
first. A mutation sends an
Idempotency-Key(see below). A banned player is refused to the game client only: your game server, timers and events keep working. - Profile.
setPlayerProfilereplaces the nickname (at most 32 characters) and the avatar (an http or https address); an empty one clears it, and the next login of a player that has none sets it again. - Ban.
banPlayerbans until the moment given, with the reason the Dashboard shows; the moment must be in the future, and a far-future one such as9999-12-31T00:00:00Zis a ban forever. A banned player is refused at sign-in and on every call withplayer_banneduntil the ban ends.unbanPlayerlifts it. - Errors. A refused call throws
RudderErrorwith thecode,messageand HTTPstatusof the answer: a code the module declares (such asinsufficient) or one of Rudder (such asplayer_not_found,idempotency_key_reusedorrate_limited). A player that does not exist, or was deleted, answersplayer_not_found. - Retries. A request that got no answer or the answer
try_againis sent again after theRetry-Afterit gave or a short backoff, at mostattemptstimes (5), with the same idempotency key. 429 is not retried. - Idempotency. The SDK generates an
Idempotency-Keyfor each mutation unless you pass one:grant(playerId, input, { idempotencyKey: orderId }). A key that a player already used for another function answers409 idempotency_key_reused. When your game server retries the whole request itself, pass the key that belongs to that request, or the mutation runs twice. - Cancel. Every method takes the option
signal, anAbortSignal.