@indiegems/gem-web-sdk/server

Which game, channel and match this server is running.

The HTTP client underneath GemServer.api, for calls the generated surface does not cover.

PREFER api. It is typed against the platform's description, so a shape that changes becomes a build error in your bundle. This one takes a path and checks nothing — reach for it when you genuinely need something api has no method for, and treat that as worth telling us about.

Every platform operation your server can call. This is the one you want.

See ServerApi.

Ending the match.

end() is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform the match is over; the platform then tells the runtime, and your server winds down through its ordinary shutdown. You do not stop the process yourself.

It always means THIS match — the id is already known, so there is nothing to pass and no way to end someone else's.

Reading the room this match came from — the two calls almost every server makes at startup, already pointed at your own room.

CHECK IT IS THERE. room is absent on older platform images, which is why the type says it might be. gem.room?.get() is the shape to write. When it is absent the same reads are still available through api if you know the room id from somewhere else.

Stop listening for credential updates.

You rarely need it: a bundle built with defineServer is disposed for you when the match ends. Call it in a test, or if you built the server yourself and are tearing it down.

Which size of machine this server was allocated on.

Useful if your game scales what it does to the hardware it got.

The room's settings as they were at match start.

Who was in the room when the server was allocated.

A HINT FOR SIZING, NOT A GUEST LIST. It is never revised, and it is not what decides who may connect — the platform admits players by credential, not by this array.

The players connected right now, as a fresh array each call.

A connected player's display identity, or null if the platform has none for them.

The seat number the platform gave a player — 1-based.

undefined when there is no answer: an id that is not seated, or an older platform image that does not assign seats. You cannot tell those apart and do not need to — handle the absence.

Send to one player.

Send to every connected player.

Disconnect a player.

Write a line to the match's logs.

USE THIS, NEVER console.log. Standard output belongs to the platform — it is how the runtime talks to your server — and writing to it directly corrupts that conversation.

Like GemMatchServer.log, marked as a warning.

Once, before any player arrives. Set your world up here.

YOU HAVE 60 SECONDS. Throwing fails the match, so do not start anything here you are not prepared to have fail loudly.

A player connected, and the platform has already verified who they are.

They are ALREADY in host.players() by the time this runs.

A player's connection closed. They are ALREADY gone from host.players().

A player sent you something.

The match is ending, or the platform is reclaiming the machine. Save what just happened.

YOU HAVE LONGER THAN YOU THINK, and how much depends on which of the two it is. When the match ends: 10 minutes before the process goes — deliberately generous, because writing results is what servers do here. When the platform is reclaiming the machine: up to 2 hours, so a match with players still in it plays out rather than dying mid-game.

Which game, channel and match this server is running.

The HTTP client underneath GemServer.api, for calls the generated surface does not cover.

PREFER api. It is typed against the platform's description, so a shape that changes becomes a build error in your bundle. This one takes a path and checks nothing — reach for it when you genuinely need something api has no method for, and treat that as worth telling us about.

Every platform operation your server can call. This is the one you want.

See ServerApi.

Ending the match.

end() is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform the match is over; the platform then tells the runtime, and your server winds down through its ordinary shutdown. You do not stop the process yourself.

It always means THIS match — the id is already known, so there is nothing to pass and no way to end someone else's.

Reading the room this match came from — the two calls almost every server makes at startup, already pointed at your own room.

CHECK IT IS THERE. room is absent on older platform images, which is why the type says it might be. gem.room?.get() is the shape to write. When it is absent the same reads are still available through api if you know the room id from somewhere else.

Stop listening for credential updates.

You rarely need it: a bundle built with defineServer is disposed for you when the match ends. Call it in a test, or if you built the server yourself and are tearing it down.

The game this server belongs to.

The channel it was allocated on — dev, test or release.

The match it is running.

The room this match came from, when there is one.

CHECK IT BEFORE USING IT. It is absent on older platform images, which is also why GemServer.room can be absent — the two go together.

Where to send API calls, INSTEAD of where the platform said.

The host already names it, and a bundle running for real should not second-guess that. This is for a rig — a tunnel, an API running on your own machine — not for choosing which environment you are in. Setting it in a shipped bundle means your server talks to somewhere the platform did not send it.

Where time comes from. Defaults to the real clock.

Pass a Clock in a test so token refresh and retry backoff happen when you say rather than when a real second passes.

The fetch used for every call. Defaults to the runtime's own.

For tests: a stub here is how you assert what your bundle sends without a network.

Called whenever the server's ability to make authenticated calls changes.

The same signal the browser half delivers to a game, for the same reason: the token is refreshed for you, and this is how you find out when that stops working. See AuthState for what to branch on and AuthFailure for the cause.

The client every operation sends through.

The game this server is running — taken from its credential.

The match this server was allocated for.

The game it belongs to.

The channel it was allocated on — dev, test or release.

The room this match came from. MAY BE ABSENT on older platform images, so check before using it — that absence is also why GemServer.room can be missing.

Where to send API calls. Absent on older platform images, which is the case createGemServer refuses at startup.

The credential held right now, if the platform delivered one.

Be told when the credential is replaced.

Called straight away if one is already held, and again on every refresh. Returns a function that stops the notifications.

You rarely call this. createGemServer subscribes for you.

Called first, handing over the host object. This is where the SDK takes it and where your own init runs.

Forwarded from your bundle, when you defined a join.

Forwarded from your bundle, when you defined a leave.

Forwarded from your bundle, when you defined a message.

Always defined, even if your bundle has no shutdown — the SDK has teardown of its own to do, and it runs whether or not yours threw.

The name the player chose — so it is PlayerText, not a plain string.

The type is the reminder: this is text a stranger wrote. text.toPlain is the one way to turn it into a string, and on a server the honest answer is usually that you never need to.

The platform-assigned tag beside the name. Not player-authored, so it is an ordinary string.

The disambiguating suffix, when the player has one.

Ask for the message to arrive. Defaults to true.

false says you would rather it be dropped than delayed — position updates that a later one supersedes. A transport is free to deliver it reliably anyway; the receiver is still told what you asked for.

Ask for messages to arrive in the order you sent them. Defaults to true.

A player to leave out — usually the one whose action caused the broadcast.

Ask for the message to arrive. Defaults to true.

false says you would rather it be dropped than delayed — position updates that a later one supersedes. A transport is free to deliver it reliably anyway; the receiver is still told what you asked for.

Ask for messages to arrive in the order you sent them. Defaults to true.

The match this server was allocated for.

The game it belongs to.

The channel it was allocated on — dev, test or release.

The room this match came from. MAY BE ABSENT on older platform images, so check before using it — that absence is also why GemServer.room can be missing.

Where to send API calls. Absent on older platform images, which is the case createGemServer refuses at startup.

The credential held right now, if the platform delivered one.

Be told when the credential is replaced.

Called straight away if one is already held, and again on every refresh. Returns a function that stops the notifications.

You rarely call this. createGemServer subscribes for you.

Which size of machine this server was allocated on.

The room's settings as they were at match start.

undefined covers two cases you cannot tell apart and do not need to: the room type declares no settings, or the platform image is older than this member.

Who was in the room when this server was allocated.

A SIZING HINT, NOT A GUEST LIST. It is never revised, and it does not decide who may connect — the platform admits players by credential. A player who joined after allocation holds a valid one and is not in here.

The player ids connected right now, as a fresh array each call.

A player's display identity, if the platform resolved one.

OPTIONAL TWICE OVER: the method itself may be absent on an older platform image, and it may answer undefined for a player it has nothing for. GemMatchServer.profile collapses both into one null.

The 1-based seat the platform gave a connected player.

May be absent as a method on an older platform image, and answers undefined for an id it has not seated.

Send to one player. A string goes as text; bytes go as binary, and the receiver is told which.

Send to every connected player. See BroadcastOptions for how, and for leaving one out.

Disconnect a player. reason is shown to them and recorded in the logs.

Write a line to the match's logs.

THE ONLY ROUTE. console.log writes to standard output, which is how the runtime talks to your server — a line written there arrives as a complaint about your bundle rather than as a log.

Like GemServerHost.log, marked as a warning.

The credential itself.

NEVER LOG IT AND NEVER FORWARD IT. Anything holding it can act as this session until it expires.

When this credential stops working, in seconds since the Unix epoch.

Routine — the SDK renews before this, and you do not see it happen.

When renewal stops being possible, in seconds since the Unix epoch.

Past this the session cannot be extended by anything. Watch AuthState rather than this number.

The player's chosen name, as a plain string.

PREFER GemMatchServer.profile, which gives you the same name as PlayerText — a type that reminds you a stranger wrote it.

The platform-assigned tag beside the name.

The disambiguating suffix, when the player has one.

Where time comes from — used for expiry and for the wait below. Pass a Clock in a test.

How long to wait for the platform to deliver a credential before giving up on a call. Defaults to 10 seconds.

Called when the ability to make authenticated calls changes. See AuthState for what to branch on.

The credential to present. Never log it and never send it on.

When it expires, in seconds since the Unix epoch.

Stop refreshing the credential.

CALL IT AT SHUTDOWN. A pending refresh timer keeps the process alive, so a bundle that skips this looks like it has hung rather than exited.

Build a client. You normally do not — createGemServer builds one and hands it to you as gem.client.

Read something.

Read something AND get its version back — or find out it has not changed.

The read half of optimistic concurrency: keep the version this returns, pass it as ifMatch on your write, and the write is refused rather than overwriting somebody. Pass it as ifNoneMatch here and an unchanged resource comes back with no body at all.

SEPARATE FROM GemClient.get on purpose — get answers with the value and nothing else, which is what most calls want.

Replace something.

NOT RETRIED. A write that timed out may already have been applied.

Create something, or perform an action.

NOT RETRIED, for the same reason as GemClient.put.

Change part of something.

NOT RETRIED, for the same reason as GemClient.put.

Remove something.

NOT RETRIED, for the same reason as GemClient.put.

The HTTP method.

The path, from the API root — /v1/players/me/settings. Never a full URL: where it is sent is not a call's decision.

The request body, if there is one. Encoded as JSON.

See ConditionalRequestHeaders — nothing else may be set.

Cancels the request. Timeouts are the caller's policy, not the SDK's.

Let the request outlive the page.

For the write fired as a player leaves. Without this, a request started while the page is unloading is simply cancelled — it looks like it was sent, and nothing arrives.

NOT ON EVERYTHING, because browsers cap how much can be in flight this way (64 KB across all such requests). Use it for the write that matters.

The HTTP status.

The decoded response body.

The resource's version, parsed out of the response.

Absent when the server sent none — not every resource is versioned. If you are writing a transport for a test, set it: leaving it out makes every conditional read look unversioned.

How long the server asked you to wait, in WHOLE SECONDS.

Seconds, not milliseconds — do not divide it by anything.

ABSENT MEANS "NO ESTIMATE", NEVER "DO NOT RETRY". Whether a refusal is worth repeating is GemApiError.retryable's answer, not this field's.

How requests actually leave. Substitute one to test without a network — see Transport.

Where time comes from, for retry backoff. See Clock.

How many times to retry a read that failed. Defaults to 2 — three attempts in all.

ONLY READS ARE RETRIED, whatever you set. A write that timed out may already have been applied, and repeating it is how a client charges someone twice. Whether your write is safe to repeat is something only you know, so the SDK does not guess.

Let the request finish even if the page goes away.

For the last write before a player closes the tab. Browsers cap how much can be in flight this way, so use it for the write that matters, not for every write.

Only apply this write if nothing has changed since you read.

Pass the version that came back with the read your write is based on. If someone else wrote in between, the call fails with precondition_failed instead of overwriting them — re-read, decide again against the new state, and write again.

Cancel the read. An aborted call rejects rather than resolving.

Ask "has this changed?" instead of "give me this".

Pass the version from your last read. If nothing has changed you get back { modified: false } and no body — cheaper for you and for the platform.

Send one request and resolve with what came back.

The plain string, safe for textContent, canvas fillText and interpolation.

The one call you make, and it belongs at your model boundary rather than scattered through your render code:

const name = text.toPlain(profile.displayName);

Safe for text; NOT pre-escaped for HTML. Do not put the result into innerHTML, a URL, a style or a script — convert at the boundary and let your framework escape, which is what it already does.

Locale-aware comparison, for sorting rosters and leaderboards.

Use this rather than converting to strings and comparing with <, which sorts by code point and gets accented and non-Latin names wrong.

players.sort((a, b) => text.compare(a.displayName, b.displayName, locale));

Accepts plain strings as well as player text, because real leaderboards mix player names with rows your game authored. Pass the player's locale from GemPrefs.locale; without one it uses the runtime's. A malformed locale tag falls back rather than throwing — this is a comparator, and a throw here would take the whole sort down with it.

Whether two names are the same name, without unwrapping either.

Compares normalised forms, so two spellings of the same name — one composed, one decomposed — come out equal. That matters because a name may reach your game from somewhere other than the arcade.

KEY YOUR ROWS ON THE PLAYER'S ID, NEVER ON A NAME. Names are not identifiers: two players can choose the same one, and a player can change theirs. Use this for display-level comparisons, not for identity.

A sentinel that names its own fix, never the player's text.

If you see [gem: use gem.text.toPlain()] on screen, something rendered the wrapper instead of converting it. That is the gate working — the alternative was shipping an unescaped player name.

⚠️ THE SENTINEL NAMES gem.text, WHICH DOES NOT EXIST. text is reached from the SDK global — const { text } = window.GemWebSdkGame; — not from your gem instance. Follow that rather than the message.

The same sentinel, so putting a player name into a save blob or a telemetry payload cannot silently store unescaped text.

Convert with text.toPlain before serialising anything you intend to keep.

What went wrong, in terms you can act on — invalid, forbidden, not_found, conflict, precondition_failed, not_modified, insufficient_funds, too_large, rate_limited or unavailable.

This is the field to branch on. Two refusals can share a status and mean different things; they do not share a reason.

The HTTP status the server answered with.

Carried for logs and bug reports. Prefer GemApiError.reason for decisions: several distinct refusals map onto one status, so branching here treats different problems as the same one.

The server's own sentence, without the reason (status): prefix that message carries.

Use this when you want to quote the platform — in a log line, or a bug report. It is not written for players, so do not put it on screen.

How long the server asked you to wait, in whole seconds.

ABSENT MEANS "NO ESTIMATE GIVEN", NEVER "DO NOT RETRY" — GemApiError.retryable is what answers that. A refusal can be worth repeating and still name no wait, so treat absence as "pick your own backoff" rather than as a stop signal. The platform estimates a wait for capacity and for rate limits, and sends none for the refusals it cannot put a number on.

The platform's own error code, when it sent one — too_many_concurrent_matches, cluster_target_required, no_compatible_server.

Finer-grained than GemApiError.reason, and the only way to tell apart two refusals that share both a reason and a status. Absent on most refusals, so treat it as extra information rather than something to depend on.

Whether another attempt could plausibly succeed.

True for unavailable and rate_limited and false for everything else — a forbidden or not_found will refuse identically however many times you send it. Check this before retrying, and wait GemApiError.retryAfterSeconds if the server named one.

Why the token could not be produced. See AuthFailure — it is the cause, and not a signal about whether to try again.

Whether a caught value is an AuthError.

Prefer this to instanceof. Two copies of the SDK can coexist on a page — the arcade vendors one build and games install another — and an error from one copy fails instanceof in the other. This check does not care which copy minted it.

try {
  await somePlatformCall();
} catch (err) {
  if (AuthError.isAuthError(err)) {
    // the session is the problem; watch onAuthStateChange for whether it recovers
  }
}

The call is left unnamed on purpose: this error reaches a game and a server bundle alike, and the two have no call in common.

Always false.

Present so that code branching on retryable across the errors this SDK throws reads a real false here rather than undefined. A refusal is deterministic; retrying cannot change it.

Whether a caught value is a TransportRefusal.

Prefer this to instanceof. Two copies of the SDK can coexist on a page — the arcade vendors one build and games install another — and an error from one copy fails instanceof in the other.

The current time, in milliseconds — the same scale as Date.now().

Run fn after ms milliseconds. Return whatever identifies it; the SDK only ever hands that value back to Clock.clearTimeout.

Cancel a timer created by Clock.setTimeout.