Add comprehensive level progression design document covering difficulty scaling and pattern generation

knowledge-base/game-design/level-progression.md

@@ -1,354 +1,349 @@
 # Level Progression Design
 
-## Difficulty Scaling Framework
+## Difficulty Scaling Philosophy
 
-### Core Progression Principles
+### Core Principles
-1. **Gradual Complexity Introduction**: Each level adds manageable new challenge
+1. **Gradual Learning Curve**: Each level introduces complexity at a manageable pace
-2. **Pattern Recognition Development**: Allow players to learn through repetition
+2. **Flow State Maintenance**: Difficulty increases to match growing player skill
-3. **Flow State Maintenance**: Balance challenge and skill to prevent frustration
+3. **Recovery Levels**: Occasional easier levels to prevent frustration
-4. **Confidence Building**: Occasional easier levels to maintain player motivation
+4. **Skill Validation**: Regular challenges that test mastered concepts
-5. **Skill Transfer**: Later levels build on patterns learned earlier
-
-### Level Structure by Stage
-
-#### Beginner Levels (1-5)
-**Purpose**: Teach core mechanics and build confidence
 
+### Mathematical Progression
 ```javascript
-const beginnerLevels = {
+const levelProgression = {
-  nodeCount: 3-4,
+  // Node count progression
-  connectionCount: 2-3,
+  nodeCount: (level) => Math.min(3 + Math.floor(level / 2), 12),
-  timeLimit: 60,
+  
-  patterns: [
+  // Connection complexity
-    'simple_chain',      // A→B→C
+  connectionCount: (level) => {
-    'triangle',          // A↔B↔C↔A
+    const nodes = nodeCount(level);
-    'star_simple',       // A→B,C,D
+    return Math.min(nodes - 1 + Math.floor(level / 3), nodes * 1.5);
-    'parallel_lines'     // A→B, C→D
-  ],
-  objectives: [
-    'Learn click and drag mechanics',
-    'Understand dotted line targets', 
-    'Develop basic pattern recognition',
-    'Build confidence with success'
-  ]
-};
-```
-
-#### Intermediate Levels (6-15)
-**Purpose**: Develop pattern recognition and spatial reasoning
-
-```javascript
-const intermediateLevels = {
-  nodeCount: 4-7,
-  connectionCount: 3-6,
-  timeLimit: 50-55,
-  patterns: [
-    'hub_networks',      // Central node connects to others
-    'chain_branches',    // Main chain with side branches
-    'symmetric_patterns', // Mirror patterns
-    'grid_subsets'       // Partial grid connections
-  ],
-  objectives: [
-    'Recognize hub and spoke patterns',
-    'Handle multiple connection points',
-    'Develop systematic approach',
-    'Improve time management'
-  ]
-};
-```
-
-#### Advanced Levels (16-25)
-**Purpose**: Challenge spatial reasoning and strategy
-
-```javascript
-const advancedLevels = {
-  nodeCount: 7-10,
-  connectionCount: 6-12,
-  timeLimit: 40-50,
-  patterns: [
-    'complex_webs',      // Highly interconnected
-    'layered_networks',  // Multiple connection layers
-    'asymmetric_designs', // Non-obvious patterns
-    'efficiency_puzzles'  // Optimal path challenges
-  ],
-  objectives: [
-    'Handle complex interconnections',
-    'Develop strategic thinking',
-    'Master time pressure',
-    'Recognize advanced patterns'
-  ]
-};
-```
-
-#### Expert Levels (26+)
-**Purpose**: Master-level challenges for dedicated players
-
-```javascript
-const expertLevels = {
-  nodeCount: 10-12,
-  connectionCount: 8-16,
-  timeLimit: 30-45,
-  patterns: [
-    'maximum_complexity', // Dense interconnections
-    'puzzle_variants',    // Special rules or constraints
-    'artistic_patterns',  // Beautiful but complex designs
-    'speed_challenges'    // Time-focused difficulties
-  ],
-  objectives: [
-    'Perfect pattern recognition',
-    'Master advanced strategies',
-    'Handle maximum complexity',
-    'Achieve expert-level flow'
-  ]
-};
-```
-
-## Pattern Type Definitions
-
-### Basic Patterns (Levels 1-5)
-```javascript
-const basicPatterns = {
-  linear_chain: {
-    description: 'Simple A→B→C→D sequence',
-    difficulty: 1,
-    nodeRange: [3, 4],
-    connectionFormula: 'nodes - 1'
   },
   
-  simple_triangle: {
+  // Time pressure
-    description: 'Three nodes all connected',
+  timeLimit: (level) => Math.max(30, 60 - Math.floor(level / 3) * 2),
-    difficulty: 2, 
+  
-    nodeRange: [3, 3],
+  // Pattern complexity score
-    connectionFormula: '3'
+  complexityScore: (level) => Math.min(level * 0.8 + 2, 10)
+};
+```
+
+## Level Archetypes
+
+### Tutorial Levels (1-3)
+**Purpose**: Teach basic mechanics
+**Node Count**: 3-4
+**Pattern Types**: Simple chains, basic shapes
+**Time Limit**: 60 seconds (generous)
+
+```javascript
+// Example Level 1 pattern
+const level1 = {
+  nodes: 3,
+  pattern: [[0, 1], [1, 2]], // Simple chain A→B→C
+  type: 'linear_chain',
+  tutorial: 'Connect the nodes by dragging from one to another'
+};
+
+// Example Level 2 pattern  
+const level2 = {
+  nodes: 4,
+  pattern: [[0, 1], [0, 2], [0, 3]], // Hub pattern
+  type: 'hub',
+  tutorial: 'One node can connect to multiple others'
+};
+```
+
+### Skill Building Levels (4-10)
+**Purpose**: Develop pattern recognition
+**Node Count**: 4-6
+**Pattern Types**: Hubs, simple networks, parallel chains
+**Time Limit**: 55-60 seconds
+
+```javascript
+// Level design templates
+const skillBuildingTemplates = {
+  doubleHub: {
+    description: 'Two hub nodes with overlapping connections',
+    complexity: 4,
+    example: [[0, 2], [0, 3], [1, 2], [1, 3]]
   },
   
-  basic_star: {
+  parallelChains: {
-    description: 'One central hub with spokes',
+    description: 'Multiple independent connection chains',
-    difficulty: 2,
+    complexity: 3,
-    nodeRange: [4, 5],
+    example: [[0, 1], [1, 2], [3, 4], [4, 5]]
-    connectionFormula: 'nodes - 1'
+  },
+  
+  triangle: {
+    description: 'Basic geometric shape',
+    complexity: 3,
+    example: [[0, 1], [1, 2], [2, 0]]
   }
 };
 ```
 
-### Intermediate Patterns (Levels 6-15)
+### Challenge Levels (11-20)
+**Purpose**: Test mastery with complex patterns
+**Node Count**: 6-9
+**Pattern Types**: Complex networks, geometric shapes, asymmetric designs
+**Time Limit**: 45-55 seconds
+
 ```javascript
-const intermediatePatterns = {
+const challengeTemplates = {
-  branched_tree: {
+  star: {
-    description: 'Tree structure with multiple branches',
+    description: 'Central hub with outer ring connections',
-    difficulty: 3,
+    complexity: 6,
-    nodeRange: [5, 7],
+    nodeCount: 7,
-    connectionFormula: 'nodes - 1 + Math.floor(nodes/3)'
+    centerNode: true
   },
   
-  partial_mesh: {
+  mesh: {
-    description: 'Partially connected mesh network',
+    description: 'Highly interconnected network',
-    difficulty: 4,
+    complexity: 7,
-    nodeRange: [6, 8],
+    connectionDensity: 0.6 // 60% of possible connections
-    connectionFormula: 'Math.floor(nodes * 1.5)'
   },
   
-  symmetric_design: {
+  symmetrical: {
-    description: 'Symmetrical connection patterns',
+    description: 'Mirror-image patterns',
-    difficulty: 4,
+    complexity: 5,
-    nodeRange: [6, 8],
+    symmetryType: 'vertical' // or 'horizontal', 'rotational'
-    connectionFormula: 'varies by symmetry type'
   }
 };
 ```
 
-### Advanced Patterns (Levels 16+)
+### Master Levels (21+)
-```javascript
+**Purpose**: Ultimate skill test
-const advancedPatterns = {
+**Node Count**: 9-12
-  dense_network: {
+**Pattern Types**: Complex geometric shapes, dense networks, multi-hub systems
-    description: 'Highly interconnected nodes',
+**Time Limit**: 30-45 seconds
-    difficulty: 5,
-    nodeRange: [8, 12],
-    connectionFormula: 'Math.floor(nodes * 2)'
-  },
-  
-  layered_structure: {
-    description: 'Multiple connection layers',
-    difficulty: 5,
-    nodeRange: [9, 12],
-    connectionFormula: 'complex algorithm'
-  },
-  
-  efficiency_puzzle: {
-    description: 'Optimal path challenges',
-    difficulty: 6,
-    nodeRange: [10, 12],
-    connectionFormula: 'maximum complexity'
-  }
-};
-```
 
-## Difficulty Adjustment Algorithm
+## Pattern Generation Algorithm
 
-### Dynamic Difficulty
+### Basic Algorithm
 ```javascript
-function calculateLevelDifficulty(level) {
+function generateLevelPattern(levelNumber) {
-  const baseNodeCount = 3;
+  const config = getLevelConfig(levelNumber);
-  const nodeGrowthRate = 0.3;
+  const nodes = generateNodePositions(config.nodeCount);
-  const maxNodes = 12;
+  const pattern = generateConnectionPattern(nodes, config);
-  
-  // Gradually increase node count
-  const nodeCount = Math.min(
-    Math.floor(baseNodeCount + level * nodeGrowthRate),
-    maxNodes
-  );
-  
-  // Connection count scales with nodes and level
-  const connectionMultiplier = 1 + (level * 0.05);
-  const baseConnections = nodeCount - 1;
-  const connectionCount = Math.floor(baseConnections * connectionMultiplier);
-  
-  // Time limit decreases gradually
-  const baseTime = 60;
-  const timeReduction = Math.floor(level / 3) * 2;
-  const timeLimit = Math.max(30, baseTime - timeReduction);
   
   return {
-    nodeCount,
+    nodes,
-    connectionCount: Math.min(connectionCount, nodeCount * 2),
+    targetConnections: pattern,
-    timeLimit,
+    timeLimit: config.timeLimit,
-    complexityScore: calculateComplexity(nodeCount, connectionCount)
+    complexity: calculateComplexity(pattern)
   };
 }
-```
 
-### Complexity Scoring
+function getLevelConfig(level) {
-```javascript
+  if (level <= 3) return tutorialConfig(level);
-function calculateComplexity(nodeCount, connectionCount) {
+  if (level <= 10) return skillBuildingConfig(level);
-  const nodeFactor = nodeCount * 0.3;
+  if (level <= 20) return challengeConfig(level);
-  const connectionFactor = connectionCount * 0.5;
+  return masterConfig(level);
-  const densityFactor = (connectionCount / nodeCount) * 0.2;
-  
-  return Math.floor(nodeFactor + connectionFactor + densityFactor);
 }
 ```
 
-## Player Progression Metrics
+### Pattern Validation
-
-### Success Indicators
-- **Completion Rate**: >80% for current difficulty tier
-- **Time Efficiency**: Consistent improvement in completion times
-- **Pattern Recognition**: Faster start times (less hesitation)
-- **Error Rate**: Fewer invalid connection attempts
-
-### Progression Gates
 ```javascript
-const progressionGates = {
+function validatePattern(nodes, connections) {
-  beginnerToIntermediate: {
+  const checks = {
-    criteria: [
+    isConnected: validateConnectivity(nodes, connections),
-      'Complete levels 1-5 with >80% success rate',
+    hasReasonableComplexity: validateComplexity(connections),
-      'Average completion time <45 seconds',
+    isAesthetic: validateAesthetics(nodes, connections),
-      'Less than 2 invalid attempts per level'
+    isSolvable: validateSolvability(connections)
-    ]
+  };
-  },
   
-  intermediateToAdvanced: {
+  return Object.values(checks).every(check => check === true);
-    criteria: [
+}
-      'Complete levels 6-15 with >70% success rate',
+
-      'Handle 6+ node networks confidently',
+function validateConnectivity(nodes, connections) {
-      'Demonstrate pattern recognition speed'
+  // Ensure all nodes are part of the pattern (no isolated nodes)
-    ]
+  const connectedNodes = new Set();
-  },
+  connections.forEach(([a, b]) => {
+    connectedNodes.add(a);
+    connectedNodes.add(b);
+  });
   
-  advancedToExpert: {
+  return connectedNodes.size === nodes.length;
-    criteria: [
+}
-      'Complete levels 16-25 with >60% success rate',
-      'Master complex interconnected patterns',
-      'Maintain performance under time pressure'
-    ]
-  }
-};
 ```
 
-## Balancing and Tuning
+## Difficulty Balancing
 
-### Playtesting Feedback Loops
+### Complexity Factors
-1. **Immediate Feedback**: Success/failure rates per level
-2. **Completion Analytics**: Time distributions and attempt counts  
-3. **Frustration Points**: Levels with high abandonment rates
-4. **Flow Breaks**: Sudden difficulty spikes or boring plateaus
-
-### Adjustment Parameters
 ```javascript
-const tuningParameters = {
+const complexityFactors = {
-  tooEasy: {
+  nodeCount: {
-    indicators: ['>95% completion rate', 'Average time <20 seconds'],
+    weight: 2.0,
-    adjustments: ['Add 1-2 connections', 'Reduce time limit by 5s', 'Increase pattern complexity']
+    calculate: (nodes) => nodes
   },
   
-  tooHard: {
+  connectionDensity: {
-    indicators: ['<50% completion rate', 'High abandonment rate'],
+    weight: 1.5,
-    adjustments: ['Remove 1-2 connections', 'Add 10s to time limit', 'Simplify pattern type']
+    calculate: (connections, nodes) => connections.length / (nodes * (nodes - 1) / 2)
   },
   
-  justRight: {
+  patternSymmetry: {
-    indicators: ['70-85% completion rate', 'Engaged retry behavior'],
+    weight: -0.5, // Symmetric patterns are easier
-    actions: ['Maintain current parameters', 'Use as template for similar levels']
+    calculate: (connections) => calculateSymmetryScore(connections)
+  },
+  
+  crossingConnections: {
+    weight: 1.0,
+    calculate: (connections, nodePositions) => countCrossings(connections, nodePositions)
+  }
+};
+
+function calculateLevelComplexity(level) {
+  let totalComplexity = 0;
+  
+  Object.entries(complexityFactors).forEach(([factor, config]) => {
+    const value = config.calculate(level);
+    totalComplexity += value * config.weight;
+  });
+  
+  return totalComplexity;
+}
+```
+
+### Dynamic Difficulty Adjustment
+```javascript
+class DifficultyAdjuster {
+  constructor() {
+    this.playerPerformance = [];
+    this.adjustmentThreshold = 3; // Adjust after 3 consecutive fails/successes
+  }
+  
+  recordPerformance(level, completed, timeRemaining) {
+    this.playerPerformance.push({
+      level,
+      completed,
+      timeRemaining,
+      timestamp: Date.now()
+    });
+    
+    this.considerAdjustment();
+  }
+  
+  considerAdjustment() {
+    const recent = this.playerPerformance.slice(-this.adjustmentThreshold);
+    
+    if (recent.length < this.adjustmentThreshold) return;
+    
+    const allFailed = recent.every(p => !p.completed);
+    const allSucceeded = recent.every(p => p.completed && p.timeRemaining > 10);
+    
+    if (allFailed) {
+      this.suggestEasierLevel();
+    } else if (allSucceeded) {
+      this.suggestHarderLevel();
+    }
+  }
+  
+  suggestEasierLevel() {
+    // Reduce complexity by decreasing connections or increasing time
+    console.log('Player struggling - suggest reducing complexity');
+  }
+  
+  suggestHarderLevel() {
+    // Increase complexity or reduce time
+    console.log('Player excelling - suggest increasing complexity');
+  }
+}
+```
+
+## Level Testing and Validation
+
+### Playtesting Metrics
+```javascript
+const playtestingMetrics = {
+  completionRate: {
+    target: '>80% for levels 1-10, >60% for levels 11-20, >40% for levels 21+',
+    measure: (attempts, completions) => completions / attempts
+  },
+  
+  averageTime: {
+    target: '50-80% of time limit used',
+    measure: (completionTimes, timeLimit) => completionTimes.reduce((a, b) => a + b) / completionTimes.length / timeLimit
+  },
+  
+  retryRate: {
+    target: '<30% of players retry level',
+    measure: (retries, attempts) => retries / attempts
+  },
+  
+  engagementScore: {
+    target: 'Players continue to next level >90% of time',
+    measure: (continuations, completions) => continuations / completions
   }
 };
 ```
 
 ### A/B Testing Framework
 ```javascript
-const abTestingLevels = {
+class LevelTester {
-  testVariants: [
+  constructor() {
-    {
+    this.variants = {};
-      name: 'standard_progression',
+    this.results = {};
-      description: 'Current difficulty curve'
-    },
-    {
-      name: 'gentler_slope', 
-      description: 'Slower difficulty increase'
-    },
-    {
-      name: 'steeper_challenge',
-      description: 'Faster ramp to complexity'
-    }
-  ],
-  
-  metrics: [
-    'level_completion_rate',
-    'session_length', 
-    'player_return_rate',
-    'user_satisfaction_score'
-  ]
-};
-```
-
-## Recovery and Flow Management
-
-### Difficulty Relief Valves
-- **Confidence Boosters**: Easier levels every 5-7 levels
-- **Pattern Variety**: Mix familiar and new pattern types
-- **Time Flexibility**: Slightly longer time limits after difficulty spikes
-- **Visual Clarity**: Ensure complex levels have clear visual hierarchy
-
-### Player Journey Optimization
-```javascript
-const playerJourney = {
-  onboarding: {
-    levels: '1-3',
-    focus: 'Mechanics mastery',
-    successRate: '>90%'
-  },
-  
-  engagement: {
-    levels: '4-15', 
-    focus: 'Skill development',
-    successRate: '70-85%'
-  },
-  
-  mastery: {
-    levels: '16+',
-    focus: 'Expert challenges', 
-    successRate: '60-75%'
   }
-};
+  
+  addVariant(levelNumber, variantName, pattern) {
+    if (!this.variants[levelNumber]) {
+      this.variants[levelNumber] = {};
+    }
+    this.variants[levelNumber][variantName] = pattern;
+  }
+  
+  getVariantForPlayer(levelNumber, playerId) {
+    const variants = Object.keys(this.variants[levelNumber] || {});
+    if (variants.length === 0) return null;
+    
+    // Deterministic assignment based on player ID
+    const variantIndex = hashPlayerId(playerId) % variants.length;
+    return variants[variantIndex];
+  }
+  
+  recordResult(levelNumber, variantName, result) {
+    const key = `${levelNumber}-${variantName}`;
+    if (!this.results[key]) {
+      this.results[key] = [];
+    }
+    this.results[key].push(result);
+  }
+  
+  analyzeResults(levelNumber) {
+    const variants = this.variants[levelNumber];
+    const analysis = {};
+    
+    Object.keys(variants).forEach(variant => {
+      const results = this.results[`${levelNumber}-${variant}`] || [];
+      analysis[variant] = {
+        completionRate: results.filter(r => r.completed).length / results.length,
+        averageTime: results.reduce((sum, r) => sum + r.timeUsed, 0) / results.length,
+        playerFeedback: results.map(r => r.satisfaction).filter(Boolean)
+      };
+    });
+    
+    return analysis;
+  }
+}
 ```
 
-This progression system should be continuously refined based on player data and feedback to maintain optimal challenge and engagement throughout the player's journey.
+## Special Level Types
+
+### Bonus Levels
+**Frequency**: Every 10 levels
+**Purpose**: Reward progress with fun, creative challenges
+**Characteristics**: Unique mechanics, relaxed time pressure, special visual effects
+
+### Recovery Levels
+**Frequency**: After 3 consecutive failures
+**Purpose**: Rebuild confidence and momentum
+**Characteristics**: Slightly easier than expected, familiar patterns, generous time
+
+### Skill Check Levels
+**Frequency**: Levels 10, 20, 30, etc.
+**Purpose**: Validate mastery before advancing to next tier
+**Characteristics**: Comprehensive challenge using all learned concepts
+
+This progression system ensures players remain engaged while being appropriately challenged throughout their journey.