Skip to main content

prc-1：Paima Achievement Interface

Abstract​

An open cross-game standard achievement specification to gamify on-chain participation. This specification allows interaction through standard HTTP methods.

Motivation​

Most games have an achievement system, but they are not compatible: vendors and tools have to be adapted to each game. By implementing this standard, developers spend no or less time implementing the format itself, vendors can use the format for gamification apps, explorers, prizes, etc. This open-specification does not depend on any specific platform game host, technology, or language, and can be completely self-hosted.

The achievement content is easily indexable for games and API consumers, in a recognizable format, allowing caching and generating useful tools for end users.

This achievement system can be used by the target game itself for unlocking functionalities such as opening new areas, triggering game progress, or giving away prizes. Third parties may also consume API to expand on its actions, which are compatible with on-chain games.

Format​

HTTP​

  • Network calls are done to any game node via HTTP to BASE_URL
  • All network requests are Method GET
  • All responses ContentType is application/json
  • Standard HTTP codes are used for status. E.g., 200 OK, 500 Internal Server Error, 404 Not Found, etc.
  • Request Accept-Language header with RFC 7231 content may be used to request the content in a specific language.
  • Response Content-Language header with RFC 7231 shall be used to inform the client of the language of the content.

Response Interfaces​

General Game Info

interface Game {
  id: string             // Game ID
  name?: string          // Optional Game Name
  version?: string       // Optional Game Version
}

Data Validity For cross-game on-chain interoperability, this field allows the requester to confirm when the data is valid, and which is the reference blockchain.

interface Validity {
  block: number;         // Data Block height (0 always valid)
  caip2: string;         // CAIP-2 blockchain identifier 
  time: string;          // Optional Date ISO8601 YYYY-MM-DDTHH:mm:ss.sssZ
}

Player Info

interface Player {     
  wallet:                // e.g., addr1234... or 0x1234..,
  walletType?: 'cardano' | 'evm' | 'polkadot' | 'algorand' | string  // (Optional) Wallet-type
  userId?: string;       // (Optional) User ID for a specific player account.
                         // This value should be immutable and define a specific account,
                         // as the wallet might be migrated or updated.
  userName?: string;     // (Optional) Player Display Name
}

Specification​

Get All Available Achievements​

{BASE_URL}/achievements/public/list

Optional: Subset of achievements by category {BASE_URL}/achievements/public/list?category=Silver

Optional: Subset of active achievements {BASE_URL}/achievements/public/list?isActive=true

interface AchievementPublicList extends Game, Validity {
    achievements: {
      name: string;                     // Unique Achievement String
      score?: number;                   // Optional: Relative Value of the Achievement
      category?: string;                // Optional: 'Gold' | 'Diamond' | 'Beginner' | 'Advanced' | 'Vendor'
      percentCompleted?: number         // Percent of players that have unlocked the achievement 
      isActive: boolean                 // If achievement can be unlocked at the time. 
      displayName: string;              // Achievement Display Name
      description: string               // Achievement Description
      spoiler?: 'all' | 'description';  // Hide entire achievement or description if not completed
      iconURI?: string;                 // Optional Icon for Achievement
      iconGreyURI?: string;             // Optional Icon for locked Achievement
      startDate?: string                // Optional Date ISO8601 YYYY-MM-DDTHH:mm:ss.sssZ
      endDate?: string                  // Optional Date ISO8601 YYYY-MM-DDTHH:mm:ss.sssZ
    }[];
}

Get completed Achievements for Wallet or Token​

{BASE_URL}/achievements/wallet/:wallet

  • wallet: Wallet address

{BASE_URL}/achievements/erc/:erc/:cde/:token_id
e.g., /achievements/erc/erc721/cards/20

  • erc: Any supported ERC standard by the game, such as erc721 or erc6551.
  • cde: Chain Data Extension name, can be used by the game to track and identify the contract.
  • token_id: Unique token id defined by the ERC standard.

Optional subset of achievements by name
{BASE_URL}/achievements/wallet/:wallet?name=start_game,end_game,defeat_red_dragon

interface PlayerAchievements extends Validity, Player {
  completed: number;                    // Total number of completed achievements for the game
  achievements: {
    name: string;                       // Unique Achievement String
    completed: boolean;                 // Is Achievement completed
    completedDate?: Date;               // Completed Date ISO8601 YYYY-MM-DDTHH:mm:ss.sssZ
    completedRate?: {                   // If achievement has incremental progress
      progress: number,                 // Current Progress
      total: number                     // Total Progress
    }
  }[];
}

Reference implementation​

Copyright and related rights waived via CC0.