DNA Evolution System (Developer Documentation)

This document provides a technical overview of the DNA Evolution system, detailing its structure, logic, and integration points for game developers and advanced users.

1. Core Concepts

The DNA Evolution system is designed to track and evolve player profiles based on cross-game actions. It uses a game-agnostic system to generate a unique DNA profile.

1.1 Gamer DNA Structure

interface PlayerDNA {
    player_id: string; // Platform UUID
    traits: {
        [traitId: string]: {
            trait_id: string;
            name: string;
            confidence: number; // 0-1 for how strong the trait is
        }
    };
    meta: {
        total_games: number;
        achievement_count: number;
        total_playtime: number;
        dominant_traits: string[];
    };
}

player_id

Platform-wide unique identifier for the user.

traits

A set of traits expressed based on the sequence.

meta

A set of high-level information about the player, such as total playtime, favorite genres, and number of achievements.

1.2 Codons

Smallest unit of DNA. Represents abstract actions or tendencies (e.g., STRATEGIC).

The platform defines a universal set of codons, and games map their actions to the appropriate codons.

1.3 Genes

Sequences of codons that are used to form the overall sequence.

Games can introduce new genes based on actions and events that happen within their games.

2. DNA Mutation System

2.1 Mutation Triggers

The following actions cause a DNA mutation:

• Achievements unlocked in-game.
• Time spent in a game.
• Participation in cross-game campaigns.
• Specific actions in DeFi protocols.
• Participation in community events.
• Game-specific events.

2.2 Mutation Process

1. Event Trigger: An in-game or DeFi action is recorded by the platform.
2. Codon Mapping: The platform retrieves the codons mapped to that event.
3. Gene Injection: The codons are used to generate a gene sequence, which is then injected into the appropriate gene_block.
4. Sequence Update: The platform recalculates the underlying sequence based on the new gene_blocks.
5. Mutation History: Mutations are logged but not directly exposed to users.
6. Trait Evaluation: The platform recalculates the player's traits.

2.3 Mutation Interface

interface DNAMutation {
    playerId: string;
    gameId: string;
    mutationType: 'ACHIEVEMENT' | 'PLAYTIME' | 'COLLABORATION' | 'DEFI' | 'COMMUNITY' | 'GAME_EVENT';
    timestamp: Date;
    data: {
        achievement?: string;
        playtime?: number;
        collaboration?: string;
        defi?: string;
        community_event?: string;
        game_event?: string;
    };
}

3. Trait Expression

3.1 Trait Definition

Traits represent player skills and tendencies, e.g., Strategic Thinker, Completionist.

Each trait has requirements (codon sequence, contexts) and expression_rules (additive/decay, boost conditions).

3.2 Trait Expression Rules

• Confidence Score: (0-1) based on the frequency and context of relevant codons.
• Context Requirements: Traits can have game-specific contexts that determine when the trait is active.
• Additive/Decay: Traits may grow with consistent use or decay over time.
• Boost Conditions: Achievements/collaborations can temporarily boost a trait.

3.3 Trait Expression Interface

interface TraitExpression {
    trait_id: string; // Unique ID of the trait
    confidence: number; // 0-1 Confidence in the trait
    last_updated: Date; // Timestamp of the last update
    requirements: { // Requirements for a trait to be expressed
        codon_sequence: string; // Codon sequences associated with a trait
        minimum_occurrences: number; // Min occurrences of a codon sequence
        context_requirements?: { // Game-specific contexts
            game_id: string; // Specific game ID required
            achievement?: string; // Specific achievement required
        }[];
    };
    expression_rules: { // Rules on how to express traits
        additive: boolean; // Is it additive
        decay_factor?: number; // How much does it decay
        boost_conditions?: { // Boost conditions
            game_id: string; // Game where boosts can occur
            achievement?: string; // Achievement that triggers the boost
            boost_factor: number; // Boost Factor
            decay_amount: number; // Boost decay
        }[];
    };
}

4. Game Integration

4.1 Codon Mapping

Games configure their in-game events to specific platform-defined codons.

Each mapping can have custom weighting and context.

4.2 Trait Reading

Games use the platform's API to retrieve a player's expressed_traits, including a confidence score and timestamp.

Games can use these traits to customize in-game rewards and experiences.

4.3 API Endpoints

Games can use the following API endpoints to interact with the DNA evolution system:

• /api/v1/partner/achievements/report: For reporting achievements, which will then trigger the appropriate DNA mutations.
• /api/v1/partner/players/{playerId}/dna: For fetching a specific player's DNA profile.
• /api/v1/partner/games/{gameId}/players/{playerId}/dna: For fetching a player's DNA profile in the context of a specific game.

5. Proprietary Algorithm (Overview)

Our proprietary DNA evolution algorithm is designed to be:

• Deterministic: Each mutation produces a deterministic result that is both consistent and repeatable.
• Scalable: Designed to scale to a very large amount of users without causing issues.
• Context Aware: Mutation logic considers the game context when making a change.
• Secure: It uses proprietary hashing and encryption to ensure that player DNA is secure and cannot be reverse-engineered.
• Dynamic: Designed to be evolved in the future.
• One Way Function: Once the sequence is created, it will not be reversible.

Codon Mapping

Codons are the fundamental building blocks of the DNA Evolution System, representing abstract gaming actions and tendencies.

What Are Codons?

Codons are game-agnostic representations of player behaviors and actions. They form the smallest units of the DNA sequence and are combined to create genes that express player traits.

// Example codon structure
interface Codon {
  id: string;         // Unique identifier
  name: string;       // Human-readable name
  description: string; // Description of the behavior this codon represents
  category: string;   // Behavioral category
}

Standard Codon Categories

The platform provides a standard set of codons across these categories:

• Strategy: Strategic thinking and planning
• Exploration: Tendencies to explore and discover
• Completion: Drive to complete objectives and collect items
• Social: Preferences for social interactions
• Combat: Combat style and proficiency
• Progression: Rate and style of game progression
• Creativity: Creative expression and customization
• Risk: Risk-taking behavior and preferences

Mapping Game Actions to Codons

To integrate with the DNA system, map your game-specific actions to platform codons:

// Example codon mapping configuration
const codonMappings = {
  achievements: {
    'complete_tutorial': ['PROGRESSION_BASIC'],
    'defeat_boss_without_damage': ['COMBAT_MASTERY', 'STRATEGIC_PLANNING'],
    'find_all_secrets': ['EXPLORATION_COMPLETIONIST'],
    'win_pvp_tournament': ['COMBAT_COMPETITIVE', 'SOCIAL_COMPETITIVE']
  },
  
  playtime: {
    'tutorial': ['PROGRESSION_BASIC'],
    'open_world': ['EXPLORATION_OPEN'],
    'puzzle_solving': ['STRATEGIC_PUZZLE'],
    'multiplayer': ['SOCIAL_COOPERATIVE', 'SOCIAL_COMPETITIVE']
  },
  
  in_game_actions: {
    'customize_character': ['CREATIVE_CUSTOMIZATION'],
    'help_new_player': ['SOCIAL_HELPFUL'],
    'take_high_risk_path': ['RISK_TAKER']
  }
};

// Register your codon mappings
const registerCodonMappings = async () => {
  try {
    await dnaClient.registerCodonMappings('your_game_id', codonMappings);
    console.log('Codon mappings registered successfully');
  } catch (error) {
    console.error('Failed to register codon mappings:', error);
  }
};

Codon Weighting

Different actions can have varying impacts on a player's DNA:

// Example weighted codon mapping
const weightedCodonMappings = {
  achievements: {
    'complete_game': {
      codons: ['PROGRESSION_ADVANCED', 'COMPLETIONIST_DEDICATED'],
      weight: 5.0 // Higher weight for major achievements
    },
    'discover_easter_egg': {
      codons: ['EXPLORATION_CURIOUS'],
      weight: 1.0 // Standard weight
    }
  }
};

Trait Expression

Player traits are derived from codon patterns in the DNA sequence, representing long-term player tendencies and preferences.

Understanding Traits

Traits are high-level player characteristics expressed with confidence scores:

// Trait structure
interface Trait {
  id: string;           // Unique identifier
  name: string;         // Human-readable name
  description: string;  // Description of the trait
  confidence: number;   // 0.0-1.0 confidence score
  lastUpdated: string;  // Timestamp of last update
}

Core Trait Categories

The platform provides these core trait categories:

1. Playstyle Traits: How players approach gameplay (e.g., "Strategist", "Explorer")
2. Skill Traits: Player proficiency levels (e.g., "Combat Expert", "Puzzle Master")
3. Social Traits: Social interaction preferences (e.g., "Team Player", "Solo Adventurer")
4. Progression Traits: How players progress through games (e.g., "Completionist", "Speedrunner")
5. Engagement Traits: Player engagement patterns (e.g., "Dedicated Player", "Casual Gamer")

Accessing Player Traits

Retrieve player traits to personalize your game:

// Example: Accessing player traits
const getPlayerTraits = async (playerId) => {
  try {
    // Get the player's DNA profile
    const dnaProfile = await dnaClient.getPlayerDNA(playerId);
    
    // Extract traits from the DNA profile
    const traits = Object.values(dnaProfile.traits);
    
    // Find traits with high confidence (>0.7)
    const strongTraits = traits.filter(trait => trait.confidence > 0.7);
    
    // Find specific traits
    const isStrategist = traits.some(
      trait => trait.trait_id === 'STRATEGIST' && trait.confidence > 0.6
    );
    
    return {
      traits,
      strongTraits,
      isStrategist
    };
  } catch (error) {
    console.error('Failed to get player traits:', error);
    return null;
  }
};

Trait Confidence Scores

Confidence scores indicate how strongly a trait is expressed:

• 0.0 - 0.3: Weak or uncertain trait expression
• 0.3 - 0.7: Moderate trait expression
• 0.7 - 1.0: Strong trait expression

These scores evolve based on continued player behavior.

Trait Evolution

Traits evolve over time as players engage with games:

// Example: Tracking trait evolution
const trackTraitEvolution = async (playerId, traitId) => {
  try {
    // Get trait history over time
    const traitHistory = await dnaClient.getTraitHistory(playerId, traitId);
    
    // Analyze how the trait has changed
    const initialConfidence = traitHistory[0].confidence;
    const currentConfidence = traitHistory[traitHistory.length - 1].confidence;
    const evolution = currentConfidence - initialConfidence;
    
    console.log(`Trait ${traitId} evolution: ${evolution > 0 ? 'increased' : 'decreased'} by ${Math.abs(evolution).toFixed(2)}`);
    
    return traitHistory;
  } catch (error) {
    console.error('Failed to track trait evolution:', error);
    return null;
  }
};

Integration with Game Logic

Integrate DNA traits into your game to provide personalized experiences.

Personalization Framework

// Example: Personalization framework
class DNAPersonalizationEngine {
  // Initialize with player traits
  constructor(playerTraits) {
    this.playerTraits = playerTraits;
    this.traitThreshold = 0.6; // Confidence threshold
  }
  
  // Check if player has a specific trait
  hasTrait(traitId, minConfidence = this.traitThreshold) {
    const trait = this.playerTraits.find(t => t.id === traitId);
    return trait && trait.confidence >= minConfidence;
  }
  
  // Get strongest traits
  getStrongTraits(limit = 3) {
    return [...this.playerTraits]
      .sort((a, b) => b.confidence - a.confidence)
      .slice(0, limit);
  }
  
  // Customize game difficulty
  recommendDifficulty() {
    if (this.hasTrait('COMBAT_EXPERT', 0.8)) {
      return 'HARD';
    } else if (this.hasTrait('COMBAT_PROFICIENT', 0.6)) {
      return 'MEDIUM';
    } else {
      return 'EASY';
    }
  }
  
  // Customize game content
  recommendContentFocus() {
    if (this.hasTrait('EXPLORER')) {
      return 'EXPLORATION';
    } else if (this.hasTrait('STRATEGIST')) {
      return 'PUZZLES';
    } else if (this.hasTrait('SOCIAL_PLAYER')) {
      return 'MULTIPLAYER';
    } else {
      return 'BALANCED';
    }
  }
  
  // Generate personalized gameplay recommendations
  generateRecommendations() {
    return {
      difficulty: this.recommendDifficulty(),
      contentFocus: this.recommendContentFocus(),
      strongTraits: this.getStrongTraits()
    };
  }
}

Integration Examples

Difficulty Adjustment

// Example: Dynamic difficulty adjustment
const adjustDifficulty = async (playerId) => {
  try {
    const traits = await dnaClient.getPlayerTraits(playerId);
    const personalization = new DNAPersonalizationEngine(traits);
    
    // Set game difficulty based on player traits
    const recommendedDifficulty = personalization.recommendDifficulty();
    
    console.log(`Setting difficulty to ${recommendedDifficulty} for player ${playerId}`);
    game.setDifficulty(recommendedDifficulty);
    
    return recommendedDifficulty;
  } catch (error) {
    console.error('Failed to adjust difficulty:', error);
    return 'MEDIUM'; // Default fallback
  }
};

Content Generation

// Example: Personalized content generation
const generatePersonalizedContent = async (playerId) => {
  try {
    const traits = await dnaClient.getPlayerTraits(playerId);
    const personalization = new DNAPersonalizationEngine(traits);
    
    // Generate quests based on player traits
    let questTypes = [];
    
    if (personalization.hasTrait('EXPLORER')) {
      questTypes.push('exploration', 'discovery');
    }
    
    if (personalization.hasTrait('COMBAT_FOCUSED')) {
      questTypes.push('combat', 'boss');
    }
    
    if (personalization.hasTrait('COMPLETIONIST')) {
      questTypes.push('collection', 'achievement');
    }
    
    if (personalization.hasTrait('SOCIAL_PLAYER')) {
      questTypes.push('cooperative', 'community');
    }
    
    // Fallback if no strong traits or error occurred
    if (questTypes.length === 0) {
      questTypes = ['balanced', 'tutorial'];
    }
    
    console.log(`Generating quests of types: ${questTypes.join(', ')}`);
    return questTypes;
  } catch (error) {
    console.error('Failed to generate personalized content:', error);
    return ['balanced']; // Default fallback
  }
};

NPC Behavior

// Example: NPC behavior adaptation
const adaptNPCBehavior = (npc, playerTraits) => {
  const personalization = new DNAPersonalizationEngine(playerTraits);
  
  // Adapt dialogue based on player traits
  if (personalization.hasTrait('STRATEGIC_THINKER')) {
    npc.dialogueStyle = 'INTELLECTUAL';
    npc.providesHints = true;
  }
  
  // Adapt assistance level
  if (personalization.hasTrait('EXPLORER')) {
    npc.providesMapInfo = true;
    npc.pointsOutSecrets = true;
  }
  
  // Adapt combat behavior
  if (personalization.hasTrait('COMBAT_EXPERT')) {
    npc.combatDifficulty = 'CHALLENGING';
    npc.usesAdvancedTactics = true;
  }
  
  return npc;
};

Personalization Examples

Real-world examples of how to leverage DNA traits for game personalization.

Example: Tutorial Adaptation

// Example: Adaptive tutorial system
const configureTutorial = async (playerId) => {
  try {
    const traits = await dnaClient.getPlayerTraits(playerId);
    const personalization = new DNAPersonalizationEngine(traits);
    
    const tutorialConfig = {
      // Basic configuration
      enabled: true,
      
      // Adapt detail level based on experience
      detailLevel: personalization.hasTrait('EXPERIENCED_GAMER') 
        ? 'MINIMAL' 
        : 'DETAILED',
      
      // Skip combat tutorial for combat experts
      includeCombatTutorial: !personalization.hasTrait('COMBAT_EXPERT'),
      
      // Include advanced mechanics for strategists
      includeAdvancedMechanics: personalization.hasTrait('STRATEGIST'),
      
      // Adapt pace based on progression traits
      pace: personalization.hasTrait('SPEEDRUNNER') 
        ? 'FAST' 
        : 'NORMAL',
      
      // Add exploration guidance for non-explorers
      includeExplorationGuidance: !personalization.hasTrait('EXPLORER')
    };
    
    console.log('Configured tutorial:', tutorialConfig);
    return tutorialConfig;
  } catch (error) {
    console.error('Failed to configure tutorial:', error);
    return { enabled: true, detailLevel: 'DETAILED' }; // Default fallback
  }
};

Example: Reward Customization

// Example: Personalized reward system
const personalizeRewards = (availableRewards, playerTraits) => {
  const personalization = new DNAPersonalizationEngine(playerTraits);
  let prioritizedRewards = [...availableRewards];
  
  // Prioritize rewards based on traits
  if (personalization.hasTrait('COLLECTOR')) {
    // Prioritize unique items and collectibles
    prioritizedRewards.sort((a, b) => {
      if (a.type === 'COLLECTIBLE' && b.type !== 'COLLECTIBLE') return -1;
      if (a.type !== 'COLLECTIBLE' && b.type === 'COLLECTIBLE') return 1;
      return 0;
    });
  }
  
  if (personalization.hasTrait('COMBAT_FOCUSED')) {
    // Prioritize weapons and combat gear
    prioritizedRewards.sort((a, b) => {
      if (a.category === 'WEAPON' && b.category !== 'WEAPON') return -1;
      if (a.category !== 'WEAPON' && b.category === 'WEAPON') return 1;
      return 0;
    });
  }
  
  if (personalization.hasTrait('CUSTOMIZER')) {
    // Prioritize cosmetic items
    prioritizedRewards.sort((a, b) => {
      if (a.category === 'COSMETIC' && b.category !== 'COSMETIC') return -1;
      if (a.category !== 'COSMETIC' && b.category === 'COSMETIC') return 1;
      return 0;
    });
  }
  
  return prioritizedRewards.slice(0, 3); // Return top 3 personalized rewards
};

Example: Level Design

// Example: Dynamic level generation
const generateDynamicLevel = (levelConfig, playerTraits) => {
  const personalization = new DNAPersonalizationEngine(playerTraits);
  
  // Base level configuration
  const dynamicLevel = {
    difficulty: 'MEDIUM',
    enemyDensity: 0.5, // 0.0 to 1.0
    puzzleDensity: 0.3,
    treasureDensity: 0.4,
    secretPassages: true,
    layout: 'BALANCED'
  };
  
  // Modify for explorer traits
  if (personalization.hasTrait('EXPLORER')) {
    dynamicLevel.layout = 'OPEN_WORLD';
    dynamicLevel.secretPassages = true;
    dynamicLevel.treasureDensity += 0.2;
  }
  
  // Modify for combat traits
  if (personalization.hasTrait('COMBAT_FOCUSED')) {
    dynamicLevel.enemyDensity += 0.2;
    dynamicLevel.difficulty = personalization.hasTrait('COMBAT_EXPERT') 
      ? 'HARD' 
      : 'MEDIUM';
  }
  
  // Modify for strategic traits
  if (personalization.hasTrait('STRATEGIST')) {
    dynamicLevel.puzzleDensity += 0.2;
    dynamicLevel.layout = 'COMPLEX';
  }
  
  // Modify for social traits
  if (personalization.hasTrait('SOCIAL_PLAYER')) {
    dynamicLevel.coopOpportunities = true;
    dynamicLevel.tradingPosts = true;
  }
  
  return dynamicLevel;
};

Next Steps

Now that you understand the DNA Evolution System, you might want to:

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