Achievements

#Create achievements

In Creator studio, open your game and choose Achievements & integration. Each achievement has a stable lowercase key, a title, a description, an optional HTTPS icon, a target and an award source.

• Target 1 is a binary unlock. Larger targets are cumulative progress.
• Secret achievements hide their details until earned.
• Definitions start as drafts. Publish each one when your game's integration is ready.

Keys, targets and award sources lock after the first progress event. Create a new key for different rules, and disable obsolete achievements instead of deleting them.

#Unlock from the browser

const platform = await Peerless.init();
if (platform.mode === "peerless" && platform.capabilities.achievements) {
  await Peerless.analytics.gameplayReady();
  // After a real victory:
  await Peerless.achievements.unlock({ key: "first_victory", eventId: victoryEventId });
  await Peerless.achievements.setProgress({
    key: "win_10_matches",
    value: lifetimeWins,
    eventId: progressEventId,
  });
}

• setProgress takes an absolute cumulative value, never an increment. Lower values never erase progress.
• Use a new event UUID for each result and reuse it when retrying that same result. Retries are idempotent; a reused ID with different content is rejected.
• Unlock notifications appear only once, on the first transition to earned.

achievements.list() returns the catalog with your progress, and ui.open("achievements") shows the hosted panel.

#Award from your server

Choose Game server required for achievements a client could fake. Generate a game credential in Creator studio, keep it on your server, validate the accomplishment there, and submit:

POST /api/achievements/server-award
Authorization: Bearer GAME_SERVER_CREDENTIAL
Content-Type: application/json

{"game_id":"GAME_UUID","grant_id":"CURRENT_GRANT_UUID","player_id":"GAME_SCOPED_PLAYER_UUID","key":"first_victory","event_id":"RESULT_UUID","action":"unlock"}

For progress, send "action":"progress","value":7. Confirm gameplay first with POST /api/play/server-telemetry (action ready). See HTTP endpoints.

#Visibility

Achievements appear on the game page, in the player, in the library and, if the player chooses, on their profile showcase. They never grant PEERLESS Points and need no membership. The Three.js starter includes a working movement pilot with three sample achievements.