Achievement System

The DNA Games Platform offers a powerful cross-game achievement system that allows developers to create, verify, and manage achievements. This document provides technical details on implementing and utilizing the achievement system in your games.

Achievement Creation

Creating achievements on the DNA Platform involves defining their properties, verification methods, and rewards.

Achievement Structure

Each achievement consists of the following components:

interface Achievement {
  id: string;                 // Unique identifier for the achievement
  game_id: string;            // ID of the game this achievement belongs to
  name: string;               // Display name of the achievement
  description: string;        // Detailed description
  icon_url?: string;          // URL to the achievement icon
  difficulty?: string;        // Difficulty level (easy, medium, hard, expert, hidden)
  dna_codons?: string[];      // DNA codons associated with this achievement
  hidden?: boolean;           // Whether this is a hidden achievement
  status?: string;            // Achievement status (active, inactive)
  created_at: string;         // Creation timestamp
  updated_at?: string;        // Last update timestamp
}

Registration Process

To create a new achievement:

1. Log in to the Developer Dashboard
2. Navigate to your game's Achievement section
3. Click "Create New Achievement"
4. Fill in the required fields
5. Define verification criteria
6. Set rewards (optional)
7. Publish the achievement

Or use the API:

// Example: Creating an achievement via API
const createAchievement = async () => {
  const response = await fetch('https://api.dna.game/api/v1/partner/games/your_game_id/achievements', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: 'dungeon_master_2025',
      name: 'Dungeon Master',
      description: 'Complete all dungeons on legendary difficulty',
      icon_url: 'https://assets.yourgame.com/achievements/dungeon_master.png',
      difficulty: 'expert', // Options: easy, medium, hard, expert, hidden
      hidden: false,
      dna_codons: ['PERSISTENCE', 'COMPLETIONIST', 'COMBAT_MASTERY']
    })
  });
  
  return response.json();
};

Bulk Achievement Import

For games with many achievements, you can use bulk import:

1. Prepare a JSON file with all your achievements
2. Use the bulk import API endpoint
3. Verify import results

// Example: Bulk achievement import
const bulkImportAchievements = async (gameId, achievementsData) => {
  const response = await fetch(`https://api.dna.game/api/v1/partner/games/${gameId}/achievements/import`, {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      achievements: achievementsData
    })
  });
  
  return response.json();
};

ZK-Proof Verification

The DNA Platform uses zero-knowledge proofs to verify achievements securely without exposing sensitive player data.

How ZK-Proofs Work

1. The game client generates a proof of achievement completion
2. The proof confirms completion without revealing gameplay details
3. The DNA Platform verifies the proof's authenticity
4. The achievement is recorded when verification succeeds

Implementing ZK-Proof Generation

Our SDK provides built-in methods for generating achievement proofs:

// Example: Generating a ZK-proof for an achievement
import { DNAClient } from '@dna-games/web-sdk';

const dnaClient = new DNAClient({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY'
});

const generateAchievementProof = async (playerId, achievementId, achievementData) => {
  // Generate the zero-knowledge proof
  const proof = await dnaClient.generateAchievementProof({
    playerId,
    achievementId,
    timestamp: new Date().toISOString(),
    // Game-specific data used for verification
    gameData: achievementData
  });
  
  return proof;
};

Verification Process

The verification process happens automatically when reporting an achievement:

// Example: Reporting an achievement with ZK-proof
const reportAchievementWithProof = async (gameId, playerId, achievementId, achievementData) => {
  try {
    // Generate the proof
    const proof = await dnaClient.generateAchievementProof({
      game_id: gameId,
      player_id: playerId,
      achievement_id: achievementId,
      timestamp: new Date().toISOString(),
      game_data: achievementData
    });
    
    // Report the achievement with the proof
    const result = await dnaClient.reportAchievement({
      game_id: gameId,
      player_id: playerId,
      achievement_id: achievementId,
      unlock_time: new Date().toISOString(),
      verification_data: {
        proof_type: 'zk',
        proof_data: proof
      }
    });
    
    return result.status === 'success';
  } catch (error) {
    console.error('Achievement verification failed:', error);
    return false;
  }
};

Verification Strategies

The platform supports different verification strategies:

1. Client-Side Verification: For less sensitive achievements
2. Server-Side Verification: For high-value or competitive achievements
3. Multi-Point Verification: Achievements requiring multiple conditions
4. Temporal Verification: Achievements with time-based requirements

Data Structure

Understanding the achievement data model is essential for effective integration.

Achievement Schema

// Achievement definition schema
interface AchievementDefinition {
  id: string;
  game_id: string;
  name: string;
  description: string;
  icon_url?: string;
  difficulty?: string;
  dna_codons?: string[];
  hidden?: boolean;
  status?: string;
  created_at: string;
  updated_at?: string;
}

// Player achievement record schema
interface PlayerAchievement {
  player_id: string;
  achievement_id: string;
  game_id: string;
  unlocked: boolean;
  unlock_date?: string;
  verification_data?: object; // Additional verification data
}

Achievement Categories

The platform supports these standard achievement categories:

• Progression: Story or level completion
• Collection: Gathering items or resources
• Challenge: Difficult or skill-based feats
• Hidden: Secret or easter egg achievements
• Social: Multiplayer or community interactions
• Meta: Platform-specific achievements
• Custom: Game-specific categories

Achievement Metadata

You can attach custom metadata to achievements:

// Example: Achievement with custom metadata
const achievementWithMetadata = {
  id: 'speed_demon',
  gameId: 'your_game_id',
  title: 'Speed Demon',
  description: 'Complete the race in under 2 minutes',
  category: 'Challenge',
  metadataSchema: {
    type: 'object',
    properties: {
      trackId: { type: 'string' },
      completionTime: { type: 'number' },
      vehicleId: { type: 'string' }
    },
    required: ['trackId', 'completionTime']
  }
};

// When reporting the achievement
const reportAchievement = async () => {
  await dnaClient.reportAchievement({
    playerId: 'player123',
    achievementId: 'speed_demon',
    metadata: {
      trackId: 'monaco',
      completionTime: 118.5, // seconds
      vehicleId: 'super_car_1'
    }
  });
};

Best Practices

Follow these guidelines to create an effective achievement system:

Achievement Design

1. Varied Difficulty: Include both easy and challenging achievements
2. Progressive Disclosure: Use achievements to guide players through game mechanics
3. Meaningful Rewards: Tie achievements to in-game benefits when possible
4. Balanced Distribution: Space achievements throughout the gameplay experience
5. Clear Requirements: Make achievement criteria transparent to players

Technical Implementation

1. Efficient Verification: Use the appropriate verification strategy for each achievement
2. Metadata Utilization: Include relevant metadata for analytics and cross-game recognition
3. Error Handling: Implement robust error handling for achievement reporting
4. Batched Reporting: Use batch reporting for achievements earned offline
5. Caching Strategy: Cache achievement data locally to reduce API calls

// Example: Implementing an achievement cache
class AchievementCache {
  private cache: Map<string, PlayerAchievement> = new Map();
  
  // Add an achievement to the cache
  addAchievement(achievement: PlayerAchievement): void {
    const key = `${achievement.playerId}:${achievement.achievementId}`;
    this.cache.set(key, achievement);
  }
  
  // Check if a player has an achievement
  hasAchievement(playerId: string, achievementId: string): boolean {
    const key = `${playerId}:${achievementId}`;
    return this.cache.has(key);
  }
  
  // Sync the cache with the server
  async syncWithServer(dnaClient, playerId: string): Promise<void> {
    try {
      // Get all achievements from server
      const serverAchievements = await dnaClient.getPlayerAchievements(playerId);
      
      // Update cache with server data
      serverAchievements.forEach(achievement => {
        const key = `${playerId}:${achievement.achievementId}`;
        this.cache.set(key, achievement);
      });
      
      console.log('Achievement cache synced successfully');
    } catch (error) {
      console.error('Failed to sync achievement cache:', error);
    }
  }
}

Cross-Game Recognition

When designing achievements for cross-game recognition:

1. Use the platform's trait system to categorize achievements
2. Include detailed metadata that other games can interpret
3. Follow naming conventions for standard achievement types
4. Implement proper rewards for recognizing external achievements

// Example: Recognizing achievements from other games
const checkExternalAchievements = async (playerId) => {
  try {
    // Get all player achievements across games
    const allAchievements = await dnaClient.getPlayerCrossGameAchievements(playerId);
    
    // Filter for relevant external achievements
    const relevantExternalAchievements = allAchievements.filter(
      achievement => achievement.gameId !== 'your_game_id' && 
                     (achievement.category === 'Boss' || 
                      achievement.category === 'PvP')
    );
    
    // Grant rewards based on external achievements
    if (relevantExternalAchievements.length > 0) {
      grantExternalAchievementRewards(playerId, relevantExternalAchievements);
    }
    
    return relevantExternalAchievements;
  } catch (error) {
    console.error('Failed to check external achievements:', error);
    return [];
  }
};

Achievement Verification Technical Implementation

The DNA Platform employs a sophisticated zero-knowledge proof system to create trustable achievement records without exposing sensitive player data. This architecture balances security, privacy, and performance through careful cryptographic design.

Verification Architecture

Our implementation uses a specialized variant of zk-SNARKs optimized specifically for gaming achievement verification:

1. Game-Side Proof Generation:

   • Game client securely collects achievement completion evidence (e.g., boss defeat, score threshold, completion time)
   • Local computation transforms gameplay evidence into a compressed mathematical proof using our SDK
   • Only the generated proof and minimal required metadata are transmitted, never raw gameplay data or player inputs
   • Proof generation is optimized for minimal computational overhead (typically <5% CPU utilization)

2. Platform Verification:

   • The DNA Platform receives and verifies the mathematical validity of the proof through our verification nodes
   • Verification cryptographically confirms the achievement was earned according to defined rules without revealing how
   • Successful verification triggers achievement recording, DNA codon updates, and any associated rewards
   • Failed verifications are logged with error codes for troubleshooting without exposing sensitive data

3. On-Chain Anchoring (Optional):

   • Achievement verification records can be anchored to various blockchains through our chain-agnostic architecture
   • Merkle roots of verification batches are posted periodically to selected chains for immutable timestamping
   • This approach creates tamper-proof verification history without requiring per-achievement transactions
   • Games can select anchoring frequency and blockchain based on their specific requirements

Data Isolation Implementation

The ZK verification system implements strict data isolation through our privacy-by-design architecture:

Accessible to Game	Accessible to DNA Platform	Accessible to Other Games	Accessible On-Chain
Full gameplay data	Proof validity	Achievement completion status	Verification timestamp
Player inputs	Achievement metadata	Associated DNA codons	Proof integrity hash
Context-specific details	Confidence scores	Trait implications	Null
Game state information	Statistical aggregation	Verification status	Null

This compartmentalized approach ensures data minimization and purpose limitation at each stage of the verification process.

ZK-Proof Technical Specifications

Our current implementation leverages cutting-edge cryptographic techniques:

• Proving System: Groth16 with specialized gaming circuits optimized for common achievement patterns
• Curve: BN254 for efficient mobile verification with 128-bit security level
• Proof Size: ~200 bytes per standard achievement, enabling efficient network transmission
• Generation Time: ~1.2 seconds on mid-range devices, optimized for minimal gameplay interruption
• Verification Time: ~8ms on platform servers, allowing for high-throughput validation at scale
• Circuit Complexity: Customized based on achievement complexity with optimized constraint systems

Relationship to DNA Codons

The verification system connects to DNA codons through a privacy-preserving mapping system:

1. Achievement verification proves completion without revealing gameplay details or strategies
2. Pre-defined achievement-to-codon mappings update player DNA profile based on the achievement's behavioral significance
3. Codon updates influence trait confidence scores through our proprietary evolution algorithm
4. Neither the game nor other platform participants can manipulate this mapping, ensuring data integrity

This creates an encrypted, tamper-proof progression from achievement → codons → traits, maintaining privacy while enabling the information value chain that powers the DNA Platform's unique personalization capabilities.

Implementation Best Practices

For optimal integration with the verification system:

1. Selective Verification: Apply ZK-proofs to high-value achievements with competitive or progression significance
2. Batched Submissions: Group related achievements for more efficient verification processing
3. Appropriate Circuit Selection: Choose from our library of achievement-specific circuits based on verification needs
4. Verification Planning: Design achievement conditions with verification in mind for optimal performance
5. Cached Verification: Implement local caching of verification status for frequently checked achievements

Following these practices ensures efficient verification without compromising security or player experience.

Advanced Topics

Achievement Analytics

The platform provides analytics on achievement completion rates:

// Example: Getting achievement analytics
const getAchievementAnalytics = async (gameId, achievementId) => {
  try {
    const analytics = await dnaClient.getAchievementAnalytics(gameId, achievementId);
    
    console.log('Completion rate:', analytics.completionRate);
    console.log('Average time to unlock:', analytics.avgTimeToUnlock);
    console.log('Unlock distribution:', analytics.unlockDistribution);
    
    return analytics;
  } catch (error) {
    console.error('Failed to get achievement analytics:', error);
    return null;
  }
};

Achievement Migration

When migrating achievements from another system:

1. Map your existing achievements to the DNA Platform schema
2. Use the bulk import API
3. Implement a migration strategy for player progress
4. Consider legacy achievement recognition

Localization

Support for multiple languages:

// Example: Creating localized achievements
const createLocalizedAchievement = async () => {
  const response = await fetch('https://api.dna.game/v1/partner/achievements', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: 'treasure_hunter',
      gameId: 'your_game_id',
      // Default English version
      title: 'Treasure Hunter',
      description: 'Find all hidden treasures',
      // Localized versions
      localizations: {
        'es': {
          title: 'Cazador de Tesoros',
          description: 'Encuentra todos los tesoros ocultos'
        },
        'fr': {
          title: 'Chasseur de Trésors',
          description: 'Trouvez tous les trésors cachés'
        },
        'ja': {
          title: '宝探し',
          description: '隠された宝物をすべて見つける'
        }
      }
    })
  });
  
  return response.json();
};

Next Steps

Now that you understand the achievement system, you might want to:

• Learn about the DNA Evolution System
• Explore Campaign Creation
• Understand Player Insights
• Review the Integration Guide