Skip to content

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.

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:

Terminal window
npm install @rudder/server

In a repository where rudder project use chose the project:

Terminal window
rudder server generate --lang ts --output src/rudder-server.ts \
--game-address https://api.rudder.build [--environment staging|prod]
FlagMeaning
--langts. Required.
--outputThe file to write; its directory is created. Required.
--game-addressThe 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.
--environmentstaging or prod: the environment whose newest release the client follows. Without it, the environment of rudder.json.
--projectAnother 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 server
await 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() answers staging or prod: 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. setPlayerProfile replaces 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. banPlayer bans until the moment given, with the reason the Dashboard shows; the moment must be in the future, and a far-future one such as 9999-12-31T00:00:00Z is a ban forever. A banned player is refused at sign-in and on every call with player_banned until the ban ends. unbanPlayer lifts it.
  • Errors. A refused call throws RudderError with the code, message and HTTP status of the answer: a code the module declares (such as insufficient) or one of Rudder (such as player_not_found, idempotency_key_reused or rate_limited). A player that does not exist, or was deleted, answers player_not_found.
  • Retries. A request that got no answer or the answer try_again is sent again after the Retry-After it gave or a short backoff, at most attempts times (5), with the same idempotency key. 429 is not retried.
  • Idempotency. The SDK generates an Idempotency-Key for each mutation unless you pass one: grant(playerId, input, { idempotencyKey: orderId }). A key that a player already used for another function answers 409 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, an AbortSignal.