Avatar unlock system

For engineers: payloads, fields, the back-office calls and every error.

Auth column: "GameOps" is the existing back-office role, "Senior" the senior GameOps permission.

The shared catalogue. The game asks "has it changed since revision 7?"; if not, the server answers "not modified" and sends nothing (standard HTTP caching: the ETag is the revision, the answer a 304). Every publish raises the revision. Only a Pull and replace takes an avatar out of the catalogue; a retired avatar stays in it as retired.

{ "revision": 7,
  "avatars": [
    { "avatarId": 17, "name": "Golden Cat", "status": "live", "availability": "earnable",
      "mode": "win", "unlockThreshold": 2000000, "imageUrl": "…/golden-cat?v=3" },
    { "avatarId": 9, "name": "Silver Wolf", "status": "retired", "availability": "earnable",
      "mode": "win", "unlockThreshold": 1000000, "imageUrl": "…/silver-wolf?v=1" },
    { "avatarId": 44, "name": "Jade Tiger", "status": "live", "availability": "earnable",
      "mode": "bet", "unlockThreshold": 20000000, "imageUrl": "…/jade-tiger?v=1" } ] }

Revision 7, live before c-311, holds seven avatars: default (1), Silver Wolf (9, retired), Golden Cat (17, win 2,000,000), Blue Owl (21, win 3,000,000), Lucky Dog (30, bet 5,000,000), Phoenix (40, grant only), Jade Tiger (44, bet 20,000,000).

Player state, the success response of GET /v1/me/avatars and of equip:

{ "owned": [ { "avatarId": 1, "source": "default" },
             { "avatarId": 9, "source": "rule_completion" },
             { "avatarId": 17, "source": "rule_completion" } ],
  "equipped": { "avatarId": 9, "selectionVersion": 13 },
  "bars": [ { "mode": "win", "targetAvatarId": 21, "unlockThreshold": 3000000,
              "revision": 8, "amount": 200000 },
            { "mode": "bet", "targetAvatarId": 30, "unlockThreshold": 5000000,
              "revision": 6, "amount": 2100000 } ],
  "notices": [],
  "pausedAvatarIds": [],
  "processedThrough": { "gameId": "slot-42", "settledSpinId": "s-140", "playerSpinSequence": 1220 },
  "catalogueRevision": 8 }

owned leaves out pulled avatars. equipped.avatarId is the stored equippedAvatarId. pausedAvatarIds lists paused rules; it lives here because a pause makes no catalogue revision. A mode with no target returns, for example, { "mode": "win", "nextUpAvatarId": 21, "amount": 0 }; nextUpAvatarId is computed on read and copied into progress_moved. processedThrough is the last settled spin this state includes; its playerSpinSequence is the player's running spin number across games and devices. The game adds only the spins it saw with a higher number, so a spin from another device is never counted twice or missed. A higher catalogueRevision triggers a catalogue refetch.

The game fetches this state after a short delay when a bar's estimate reaches its locked threshold, or on the first spin that adds to a mode with no target, then a few more times with growing gaps, within a fixed budget (say, five tries in a minute) and respecting Retry-After. After that it waits for the next spin, login, app return or avatar screen, so a toast may be late but is never lost. Each answer resets the estimate. Login, app return and the avatar screen also fetch. A noticeId already shown is skipped while local history lasts. No new connection is opened; an existing push channel may notify a closed app (assumed). A newly owned avatar shows NEW until the player equips it or saves a choice after seeing it; the game keeps this mark (assumed), with no new field.

Notices

All model fields.

Two headers keep changes safe:

• If-Match carries the changeVersion the caller last saw, in quotes (If-Match: "5"). It is the value GET /admin/v1/changes/{changeId} returns, also as its ETag. Edit, submit, approve, send back, publish and discard all carry it. If the change moved on since, the call fails with 412 PRECONDITION_FAILED.
• Idempotency-Key is a key the caller picks for one action. A repeat with the same key returns the first result instead of doing it twice. The key is bound to the user, method, path, body and If-Match; reusing it with different input returns 400 INVALID_REQUEST.

An action the change's state does not allow (for example, editing a published change) returns 409 CHANGE_CONFLICT.

Change lifecycle.

1. Every successful edit, submit, approve, send back, discard and publish raises changeVersion by 1 and returns it as the new ETag; publish sends the version that approve returned.
2. A published change is closed and read-only.
3. A draft or in-review change can be discarded with If-Match. It closes as discarded, audited.
4. "Approve and publish" makes two calls: approve, then publish.
5. After an avatar's first publish, its mode and availability are fixed; to change them, create a new avatar and retire the old one. Only the default avatar is default.

Opening a change, POST /admin/v1/changes, sends { "baseRevision": 7 } and returns 201 with changeId, changeVersion 1 and status draft. An edit sends the whole item list: PUT /admin/v1/changes/c-311 with If-Match: "2" and { "items": [ { "action": "edit", "avatarId": 17, "unlockThreshold": 3000000 } ] } returns 200 with the change and ETag: "3". A create item sends name, availability, assetId and imageVersion, plus mode and unlockThreshold when earnable, and no avatarId; the server assigns the avatarId on the first save, later edits and retries keep it, and IDs are never reused. Send back sends { "comment" }; acknowledging a notice returns 204. A correction, POST /admin/v1/corrections, is one of two operations. { "operation": "apply_revision", "avatarId", "revision", "playerIds", "reason" } lowers those players' locked thresholds to that revision's value and keeps their amounts. { "operation": "adjust_progress", "avatarId", "reason", "players": [ { "playerId", "lockedRevision", "delta" } ] } adds each delta once, in that player's processing order, so spins credited meanwhile stay. Either returns 201 with its correctionId and status proposed and runs after a second senior approves it; a player whose target or locked revision changed since is skipped and listed for a new review.

Errors. Every error is { "error": { "code", "message", "requestId", "details"? } }; message is a short English sentence for logs and support, never shown to players.

details: SELECTION_CONFLICT → equipped {avatarId, selectionVersion}; VALIDATION_FAILED → a list of {avatarId, field, reason}; other codes have none.

Retries. Each repeat below is matched by its key ("keyed by"), so it never applies twice.

1. Settled spins are keyed by (gameId, settledSpinId). Each counts once.
2. Equip is keyed by selectionVersion. A stale retry that passes the earlier checks gets SELECTION_CONFLICT with the current choice. The game treats it as success if that is the requested avatar, and otherwise redraws.
3. Acknowledgements are keyed by noticeId, admin edits by changeVersion.
4. Admin POSTs are keyed by Idempotency-Key.
5. Only publish creates a revision.

Versions. /v1 changes only for breaking changes; the game ignores unknown fields and renders an unknown equipped avatar as the default.

For GameOps: what the review screen shows below the diff and approval.

Version history, one table per environment, newest first. Columns: revision, published at, publishedBy, approvedBy, kind (publish, republish), avatars touched, and "View" (the full revision and its diff with the one before). Republish on a row opens a change that restores that revision, diffed against live, with normal review and lifecycle validation. It never brings back a pulled avatar or its image. An avatar missing from that revision is retired the normal way (owners keep it, progress moves), never deleted. A banner says: "Republishing changes future assignments only. Players already chasing an avatar keep their locked target unless it is retired, and owned avatars stay owned."

Audit log. Columns: time, user, action (create, edit, retire, pull and replace, submit, approve, send back, discard, publish, republish, pause, resume, correction), object (avatar or change), field, before, after, revision. Filters: avatar, user, action, date range. Read-only. Kill-switch use is audited in the feature-flag tool. Looking up one player's avatars is out of scope for now.

For GameOps and engineers: what Retire, Pull and replace and Rule pause do, how players see them, and rare cases.

Retire (a reviewed change item).

1. The avatar stays in the catalogue as retired. Owners keep it and can equip it. The picker shows it only to owners.
2. It is no longer assigned or credited. A spin settled before the Retire went live still credits, and can complete, the retired target, even if processed later.
3. After those spins, the unfinished amount moves to that mode's bar, seeds the next target and sends progress_moved.
4. A Pull applies to every spin processed after it commits, so it never completes the pulled avatar.

Pull and replace (rare: legal or offensive content).

1. It is a change item with a pullReason and a live grant_only replacementAvatarId. It needs a second approval, as any production change does, and is audited.
2. On publish, the avatar becomes retired with its pullReason and leaves everyone's catalogue. Its image stops being served, controlled copies are removed (assumed asset process), and clients stop showing it once they load the new catalogue revision.
3. Its ID, name, status, ownership and audit history stay.
4. One step per owner, keyed by player, pulled avatar and revision, runs once, and before that owner's next read or equip if it has not run yet. It:
   • grants the replacement (one ownership row per player, so never twice);
   • sends one replacement notice instead of owned, even if the replacement was already owned, without naming the pulled avatar;
   • equips the replacement with selectionVersion + 1 only if the pulled avatar is still equipped, so a newer choice stays;
   • drops any undelivered owned notice for the pulled avatar; a game that already received one stops showing it once it loads the new catalogue revision.
5. Progress moves as for Retire.
6. No coin compensation. Deleting offline copies is not promised.
7. In an emergency before approval, the kill switch hides the whole feature.

Rule pause (senior, audited).

1. It applies to spins processed after it takes effect.
2. A paused rule still credits progress, but grants nothing and is not assigned as a new target. The picker shows it greyed as "Paused".
3. Audited corrections run during the pause.
4. At resume, one step per player, keyed by player, avatar and resume, makes the due grants against the corrected record, in the player's processing order, never twice.
5. Each grant is one save, as for a completing spin: ownership, the owned notice, the cleared target and the discarded overflow.

Rule changes and removals, as players see them:

Health signals and what to do:

More edge cases