Gamification

The Gamification service turns what your players do into progress. You describe the activity you care about as events, author missions that react to those events, and send the events as they happen. Tanitar counts progress, completes missions, grants XP, advances levels and streaks, fills battle-pass tiers, hands out chests and ranks players on leaderboards. Anything that moves value, such as currency or a badge, is paid through Rewards so it lands in the same ledger as every other reward.

Every route on this page is called with an API key against GAMIFICATION_API_URL. Everything is scoped to your tenant: the tenant comes from the key, never from a request body.

The building blocksCopy Anchor Link

How the pieces fitCopy Anchor Link

flowchart LR
  A["Organizer backend"] -->|"POST event"| B["Event ingestion"]
  B --> C["Mission progress"]
  C -->|"mission completed"| D["XP, level, streak"]
  C -->|"battle-pass XP"| E["Battle-pass season"]
  C -->|"chest reward"| F["Chest inventory"]
  C -->|"currency or badge"| G["Rewards grant"]
  E -->|"tier claim"| G
  F -->|"chest opened"| G
  D --> H["Leaderboards"]
  G -->|"settled outcome"| C

1. You register an event and publish it, then author missions against it. See Catalog authoring.
2. Your backend sends each occurrence with an Idempotency-Key. See Event ingestion.
3. Tanitar advances every matching mission for that player in one transaction. A mission that reaches its target completes exactly once and pays its rewards.
4. You read a player's level, XP, streak and mission progress, and can replay retained history when you publish a mission late. See Progress, XP and levels.
5. Seasons, chests and leaderboards build on the same completions. See Seasons and chests and Leaderboards.

How mission rewards settleCopy Anchor Link

A mission declares one or more rewards. Each type is paid in a different place:

nft and token are accepted by the request shape but refused when the mission is written.

A completion that pays currency is held until Rewards answers. When the grant is applied or rejected, the completion is published with the outcome. If no answer arrives within the grant timeout (15 minutes by default), the completion is settled as a terminal failure; a late answer is still recorded and published as a correction rather than dropped. A rejected grant is a settled outcome, never a lost reward. See Grants.

A completion that was itself caused by a gamification payout does not request a second grant: if a mission reacts to the reward:granted event that another mission's payout produced, its currency reward is recorded as rejected instead of being sent. This stops reward loops.

ScopesCopy Anchor Link

Issue the authoring and approving scopes to different API keys: an approval made by the principal that last wrote the mission is refused. See API keys and scopes.

What your players seeCopy Anchor Link

Players reach their own gamification data through the hosted experience, on the Player plane (routes under /player/v1/gamification), authenticated with their own player credential rather than your API key. They see published missions, their progress, level and streak, their chest inventory and pity meter, the active battle-pass season, and the leaderboards; they open chests and claim tiers themselves. See Player identity.

Events you can receiveCopy Anchor Link

Gamification publishes gamification.mission.completed, gamification.progress.updated, gamification.xp.granted, gamification.streak.advanced, gamification.chest.opened, gamification.battle-pass.progressed and gamification.battle-pass.tier-claimed. Subscribe to them with a webhook endpoint; the payloads are in the event catalog.