When a deprecated surface stops working
A handful of the surfaces in this SDK are marked deprecated. The mark tells you there is something better to call. It does not tell you how long the old one has, and that is the question you actually need answered before you can decide what to do about it. This page is the answer, and it is the only place in this documentation that gives it.
Read it when something your game calls is marked deprecated and you are choosing between migrating now and folding the migration into your next major upgrade. If nothing you call is marked, you do not need this page.
1. What this covers#
This policy governs the API surface of @indiegems/gem-web-sdk: the exports, methods, fields and options your game compiles against. A deprecation on one of those is a statement about package releases, and section 2 is the statement.
A deprecated surface still works. The mark removes nothing and changes no behaviour. It is a notice period, and the point of a notice period is that you get to spend it rather than react to it.
Four of the surfaces in section 4 are only half a package question, because the value behind them is pushed to your server bundle by the platform rather than returned by a call you make. Section 3 is that other half. And three separate things on this platform carry a version; section 5 says which of them this is.
2. The rule for the package's API surface#
A surface deprecated in a 3.x release keeps working for every remaining 3.x release, and 4.0.0 is the earliest release that may remove it.
Earliest release that may is the whole of the strength, and it is worth reading twice. It is a floor: it names the soonest a removal could reach you, which is the number a migration plan needs. It is not a schedule. It does not say the surface is removed in 4.0.0, and it does not put a date on 4.0.0.
What the floor buys you is that the removal lands on an upgrade you already control. No minor and no patch release inside 3.x takes a deprecated surface away, so a dependency range that stays inside 3.x cannot lose one underneath you — not on an install, not on a lockfile refresh, not on a transitive bump. The next time you have to think about any of this is the next time you deliberately change a major version.
This is what package-level semver already costs here rather than a new promise: server-bundles.md records the whole package going to 3.0.0 for a single removed export, because that is the price of taking a surface away.
So migrate at the major, not at the mark. A deprecation is worth a note in your backlog the day you read it; it is worth your afternoon only when you are already planning the major upgrade it lands on.
3. Runtime-delivered pushes are a separate question#
Four of the deprecated surfaces are not values this package produces. roomArgs and roster on the server host — and the same two on the match-server wrapper around it — are pushed into your bundle by the dedicated-server runtime image your bundle runs on. That splits the question in two, and the halves are decided in different places.
The member is package surface, and section 2 governs it unchanged. The property keeps compiling for the rest of
3.x, and4.0.0is the earliest release that may take it off the type.Whether a value still arrives is the runtime's decision, and no date has been set for it. This package does not build the runtime image and cannot say when a server stops sending one of these. That is decided where the image is built. Nothing here names a version for it, because a version this package cannot honour would be worse than the silence it replaces.
So treat delivery as something your code checks, not something you can read off a version. That is the advice server-bundles.md already gives and none of it changes: read the room when it is there, and keep the deprecated push as the fallback for a server running an older image. Room args has the shape of both and the check that chooses between them.
4. What is deprecated today#
Every deprecated surface this documentation publishes, with what to call instead. A notice you meet in the reference or in a guide points here; if a surface is not in this table, it is not deprecated.
| Surface | Replacement | Earliest release that may remove it | Governing rule |
|---|---|---|---|
Gem.client | The named surfaces — Gem.rooms, Gem.me, Gem.characters and the rest | 4.0.0 | Package API surface |
ClientVersion.platform | None; drop the field, the SDK reports it | 4.0.0 | Package API surface |
CreateRoomOptions.maxPlayers | The room template's seats | 4.0.0 | Package API surface |
GemServerHost.roomArgs | gem.room?.args() | 4.0.0, for the member | Package API surface, plus runtime delivery |
GemServerHost.roster | gem.room?.get() | 4.0.0, for the member | Package API surface, plus runtime delivery |
GemMatchServer.roomArgs | gem.room?.args() | 4.0.0, for the member | Package API surface, plus runtime delivery |
GemMatchServer.roster | gem.room?.get() | 4.0.0, for the member | Package API surface, plus runtime delivery |
profile(playerId) | The room read's per-member display identity | Not a package release | Runtime delivery only |
"For the member" is the split from section 3, and it is the row's real answer: 4.0.0 is the earliest release that may take the property off the type, and it says nothing about when a server stops putting a value in it.
The last row is the one that is only a guide's. profile(playerId) is marked deprecated in server-bundles.md and carries no mark in the generated reference, so there is no package release to name for it and section 3 is its whole rule.
5. What this is not#
Three separate things on this platform carry a version. This policy is about one of them, and mistaking it for either of the others produces a plan for a rule that does not exist.
Not the bridge protocol version. The handshake between the arcade page and your game negotiates its own version, and
README.md§ "Version negotiation" is the rule that governs it. Different axis, different trigger, and nothing on this page restates or amends it.Not your game's compatibility line. Which builds of your game can meet in a room is derived from your
gameVersion, and the compatibility line is the rule for that.Not a removal schedule. This page names the earliest release that may remove a surface, which is a floor and not a plan. A surface may outlive the release named beside it.