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", "thresholdsByTier": { "T1": 2000000, "T2": 200000000, "T3": 20000000000 },
      "imageUrl": "…/golden-cat?v=3" },
    { "avatarId": 9, "name": "Silver Wolf", "status": "retired", "availability": "earnable",
      "mode": "win", "thresholdsByTier": { "T1": 1000000, "T2": 100000000, "T3": 10000000000 },
      "imageUrl": "…/silver-wolf?v=1" },
    { "avatarId": 44, "name": "Jade Tiger", "status": "live", "availability": "earnable",
      "mode": "bet", "thresholdsByTier": { "T1": 20000000, "T2": 2000000000, "T3": 200000000000 },
      "imageUrl": "…/jade-tiger?v=1" } ],
  "tiers": [ { "tierId": "T1", "minLevel": 1, "maxLevel": 20 },
             { "tierId": "T2", "minLevel": 21, "maxLevel": 50 },
             { "tierId": "T3", "minLevel": 51 } ] }

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). Amounts are tier 1; tiers 2 and 3 are 100 and 10,000 times higher in these samples.

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 },
  "currentTierId": "T1",
  "bars": [ { "mode": "win", "targetAvatarId": 21, "tierId": "T1", "unlockThreshold": 3000000,
              "revision": 8, "amount": 200000 },
            { "mode": "bet", "targetAvatarId": 30, "tierId": "T1", "unlockThreshold": 5000000,
              "revision": 6, "amount": 2100000 } ],
  "notices": [],
  "pausedAvatarIds": [],
  "processedThrough": { "gameId": "slot-42", "settledSpinId": "s-140", "playerSpinSequence": 1220 },
  "catalogueRevision": 8 }

owned leaves out pulled avatars. The picker labels avatars not yet chased with currentTierId's thresholds and each target with its bar's locked one; the two bars can hold different tiers. 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. Keys, their bound requests and their original results are kept permanently, alongside the audit history. An exact repeat returns the original result before checking the current version or state, and never runs the action again.

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.
6. The review returns threshold warnings as {avatarId, tierId, field, reason}. Approve sends the ones the approver ticked; for c-311 both: { "acknowledgedWarnings": [ { "avatarId": 17, "tierId": "T1", "field": "thresholdsByTier", "reason": "LARGE_THRESHOLD_CHANGE" }, { "avatarId": 17, "tierId": "T1", "field": "thresholdsByTier", "reason": "THRESHOLD_TIE" } ] }. The server works the warnings out again for that changeVersion; a missing one returns 422 VALIDATION_FAILED with WARNING_NOT_ACKNOWLEDGED and nothing is approved. The approval records the ticks, an edit clears them, and publish checks them again.

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, "thresholdsByTier": { "T1": 3000000, "T2": 200000000, "T3": 20000000000 } } ] } returns 200 with the change and ETag: "3". A create item sends name, availability, assetId and imageVersion, plus mode and thresholdsByTier 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 for each bar's locked tier 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, tierId (for threshold checks), field, reason}; other codes have none.

Threshold checks, run for every tier on submit and again on publish against the catalogue that would result. A block stops the change; a warning shows on the review, and the approver must tick it before approving (an edit clears the ticks). Players already chasing an avatar keep their locked target (#3).

Another player's avatar. GET /v1/players/{playerId}/avatar uses the game session and the game's existing friend and leaderboard visibility; a player the caller may not see returns 404 NOT_FOUND. A pulled avatar resolves to its replacement or the default.

{ "avatarId": 17, "imageUrl": "https://cdn.example/avatars/golden-cat/v3.png", "imageVersion": 3 }

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. Threshold entries name the tier (for example thresholdsByTier.T1). 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. That next target and its tier are chosen and locked at the next spin that assigns one (#1), not at the Retire.
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

For GameOps and engineers: who can do what, and where roles come from. The module reuses the existing back-office login and GameOps role. Senior GameOps is a permission on top of it, for pause, resume and player-state corrections. Assumed: the existing back-office access system assigns both and audits the assignments.

Admin screens show an error next to the field it concerns, with a copyable request ID; operational error logs stay in the existing monitoring tools (assumed).

For engineers: what is cached, where, and how it is cleared. Caches make reads faster; grants and equips always use the server's stored state.