AndersPier/neural-nexus-claude-project
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive level progression system documentation

Browse Source
This commit is contained in:
Anders Lehmann Pier
2025-06-13 10:49:10 +02:00
parent c50c9fc496
commit efcdd50b00
1 changed files with 271 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

552
knowledge-base/game-design/level-progression.md
View File

@@ -1,349 +1,327 @@
# Level Progression Design # Level Progression System - Neural Nexus
## Difficulty Scaling Philosophy ## Overview
### Core Principles The level progression system in Neural Nexus is designed to provide a smooth learning curve that gradually introduces complexity while maintaining player engagement. The system balances challenge escalation with skill development to create optimal flow state.
1. **Gradual Learning Curve**: Each level introduces complexity at a manageable pace
2. **Flow State Maintenance**: Difficulty increases to match growing player skill
3. **Recovery Levels**: Occasional easier levels to prevent frustration
4. **Skill Validation**: Regular challenges that test mastered concepts
### Mathematical Progression ## Progression Algorithm
### Node Count Scaling
```javascript ```javascript
const levelProgression = { const nodeCount = Math.min(5 + Math.floor(level * 0.7), 12);
// Node count progression
nodeCount: (level) => Math.min(3 + Math.floor(level / 2), 12),
// Connection complexity
connectionCount: (level) => {
const nodes = nodeCount(level);
return Math.min(nodes - 1 + Math.floor(level / 3), nodes * 1.5);
},
// Time pressure
timeLimit: (level) => Math.max(30, 60 - Math.floor(level / 3) * 2),
// Pattern complexity score
complexityScore: (level) => Math.min(level * 0.8 + 2, 10)
};
``` ```
## Level Archetypes **Progression Curve:**
- **Levels 1-3**: 5-6 nodes (learning phase)
- **Levels 4-7**: 6-8 nodes (skill building)
- **Levels 8-12**: 8-10 nodes (competency development)
- **Levels 13-20**: 10-12 nodes (mastery phase)
- **Levels 21+**: 12 nodes (expert challenge)
### Tutorial Levels (1-3) **Design Rationale:**
**Purpose**: Teach basic mechanics - Exponential growth prevents overwhelming new players
**Node Count**: 3-4 - Cap at 12 nodes maintains visual clarity on mobile devices
**Pattern Types**: Simple chains, basic shapes - Gradual increase allows pattern recognition skill development
**Time Limit**: 60 seconds (generous) - Consistent maximum ensures predictable complexity ceiling
### Connection Complexity
```javascript ```javascript
// Example Level 1 pattern const connectionCount = Math.min(
const level1 = { nodeCount - 1 + Math.floor(level / 2),
nodes: 3, nodeCount * 2
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) **Connection Density:**
**Purpose**: Develop pattern recognition - **Early Levels**: Minimum spanning tree (nodeCount - 1 connections)
**Node Count**: 4-6 - **Mid Levels**: Additional parallel paths (+1-3 connections)
**Pattern Types**: Hubs, simple networks, parallel chains - **Advanced Levels**: Near-complete graphs (approaching nodeCount * 2)
**Time Limit**: 55-60 seconds
**Complexity Examples:**
- Level 1: 5 nodes, 4 connections (simple chain)
- Level 5: 6 nodes, 6 connections (basic network)
- Level 10: 9 nodes, 13 connections (complex web)
- Level 20: 12 nodes, 19 connections (dense network)
### Time Limit Progression
```javascript ```javascript
// Level design templates const timeLimit = Math.max(45, 60 - Math.floor(level / 3) * 2);
const skillBuildingTemplates = {
doubleHub: {
description: 'Two hub nodes with overlapping connections',
complexity: 4,
example: [[0, 2], [0, 3], [1, 2], [1, 3]]
},
parallelChains: {
description: 'Multiple independent connection chains',
complexity: 3,
example: [[0, 1], [1, 2], [3, 4], [4, 5]]
},
triangle: {
description: 'Basic geometric shape',
complexity: 3,
example: [[0, 1], [1, 2], [2, 0]]
}
};
``` ```
### Challenge Levels (11-20) **Time Allocation:**
**Purpose**: Test mastery with complex patterns - **Levels 1-2**: 60 seconds (generous learning time)
**Node Count**: 6-9 - **Levels 3-5**: 58 seconds (slight pressure introduction)
**Pattern Types**: Complex networks, geometric shapes, asymmetric designs - **Levels 6-8**: 56 seconds (building urgency)
**Time Limit**: 45-55 seconds - **Levels 9-11**: 54 seconds (moderate pressure)
- **Levels 12+**: Continues decreasing by 2 seconds every 3 levels
- **Minimum**: 45 seconds (maintains playability)
```javascript ## Level Design Philosophy
const challengeTemplates = {
star: {
description: 'Central hub with outer ring connections',
complexity: 6,
nodeCount: 7,
centerNode: true
},
mesh: { ### Phase 1: Introduction (Levels 1-5)
description: 'Highly interconnected network', **Objective**: Teach core mechanics without frustration
complexity: 7,
connectionDensity: 0.6 // 60% of possible connections
},
symmetrical: { **Pattern Characteristics:**
description: 'Mirror-image patterns', - Simple linear chains (A→B→C)
complexity: 5, - Clear source and target nodes
symmetryType: 'vertical' // or 'horizontal', 'rotational' - Obvious connection paths
} - Minimal branching
}; - Forgiving time limits
**Example Patterns:**
```
Level 1: O---O---O (3 nodes, 2 connections)
Level 2: O---O---O---O (4 nodes, 3 connections)
Level 3: O (5 nodes, 4 connections)
/|\
O-O-O
``` ```
### Master Levels (21+) **Success Criteria:**
**Purpose**: Ultimate skill test - 95% completion rate for levels 1-3
**Node Count**: 9-12 - Average completion time under 30 seconds
**Pattern Types**: Complex geometric shapes, dense networks, multi-hub systems - Players understand connection mechanics
**Time Limit**: 30-45 seconds - No confusion about objectives
### Phase 2: Skill Building (Levels 6-15)
**Objective**: Develop pattern recognition and strategic thinking
**Pattern Characteristics:**
- Hub-and-spoke patterns
- Simple symmetrical designs
- Multiple valid solution paths
- Introduction of parallel connections
- Moderate time pressure
**Example Patterns:**
```
Level 8: O-O-O (6 nodes, 7 connections)
|/|\|
O-O-O
Level 12: O (8 nodes, 11 connections)
/ | \
O--O--O
\ | /
\|/
O
```
**Success Criteria:**
- 80% completion rate for levels 6-10
- Players develop efficient connection strategies
- Reduced hesitation in pattern recognition
- Consistent improvement in completion times
### Phase 3: Challenge (Levels 16-30)
**Objective**: Test mastery and provide satisfying difficulty
**Pattern Characteristics:**
- Complex interconnected networks
- Near-optimal path planning required
- High connection density
- Increased time pressure
- Multiple interdependent components
**Example Patterns:**
```
Level 20: O-O-O-O (10 nodes, 16 connections)
|X|X|X| (X represents crossing connections)
O-O-O-O
|X|X|
O-O
```
**Success Criteria:**
- 60% completion rate for levels 16-20
- Players demonstrate advanced pattern recognition
- Strategic planning becomes evident
- High replay value for optimization
### Phase 4: Mastery (Levels 31+)
**Objective**: Provide endless challenge for expert players
**Pattern Characteristics:**
- Maximum complexity within constraints
- Algorithmic pattern generation
- Emphasis on optimization
- Tight time constraints
- Pattern variations to prevent memorization
**Design Principles:**
- Every level should be solvable within time limit
- Patterns avoid pure trial-and-error approaches
- Visual clarity maintained despite complexity
- Reward efficient solutions with better scores
## Pattern Generation Algorithm ## Pattern Generation Algorithm
### Basic Algorithm ### Basic Generation Process
```javascript ```javascript
function generateLevelPattern(levelNumber) { function generateLevel(level) {
const config = getLevelConfig(levelNumber); // 1. Calculate parameters
const nodes = generateNodePositions(config.nodeCount); const nodeCount = calculateNodeCount(level);
const pattern = generateConnectionPattern(nodes, config); const connectionCount = calculateConnectionCount(level, nodeCount);
const timeLimit = calculateTimeLimit(level);
return { // 2. Place nodes in circular arrangement with variation
nodes, const nodes = generateNodePositions(nodeCount);
targetConnections: pattern,
timeLimit: config.timeLimit, // 3. Generate valid connection pattern
complexity: calculateComplexity(pattern) const pattern = generateConnectionPattern(nodes, connectionCount);
};
// 4. Ensure pattern is solvable
validatePattern(pattern, timeLimit);
return { nodes, pattern, timeLimit };
}
```
### Node Placement Strategy
```javascript
function generateNodePositions(count) {
const positions = [];
const centerX = canvas.width / 2;
const centerY = canvas.height / 2;
const radius = Math.min(canvas.width, canvas.height) * 0.3;
for (let i = 0; i < count; i++) {
const angle = (i / count) * Math.PI * 2;
const x = centerX + Math.cos(angle) * radius + randomVariation();
const y = centerY + Math.sin(angle) * radius + randomVariation();
positions.push({ x, y, id: i, type: determineNodeType(i, count) });
} }
function getLevelConfig(level) { return positions;
if (level <= 3) return tutorialConfig(level);
if (level <= 10) return skillBuildingConfig(level);
if (level <= 20) return challengeConfig(level);
return masterConfig(level);
} }
``` ```
### Pattern Validation ### Pattern Validation
```javascript ```javascript
function validatePattern(nodes, connections) { function validatePattern(pattern, timeLimit) {
const checks = { // Ensure pattern is connected
isConnected: validateConnectivity(nodes, connections), if (!isConnectedGraph(pattern)) {
hasReasonableComplexity: validateComplexity(connections), throw new Error('Pattern must form connected graph');
isAesthetic: validateAesthetics(nodes, connections),
isSolvable: validateSolvability(connections)
};
return Object.values(checks).every(check => check === true);
} }
function validateConnectivity(nodes, connections) { // Estimate solution time
// Ensure all nodes are part of the pattern (no isolated nodes) const estimatedTime = estimateSolutionTime(pattern);
const connectedNodes = new Set(); if (estimatedTime > timeLimit * 0.8) {
connections.forEach(([a, b]) => { throw new Error('Pattern too complex for time limit');
connectedNodes.add(a); }
connectedNodes.add(b);
});
return connectedNodes.size === nodes.length; // Check visual clarity
if (hasOverlappingConnections(pattern)) {
throw new Error('Pattern has unclear visual elements');
}
return true;
} }
``` ```
## Difficulty Balancing ## Difficulty Balancing
### Complexity Factors ### Player Skill Metrics
The system tracks implicit player skill indicators:
- **Completion Time**: Average time to complete levels
- **Accuracy**: Ratio of valid to invalid connection attempts
- **Efficiency**: Optimal vs actual connection sequence
- **Consistency**: Variance in performance across similar levels
### Dynamic Adjustment (Future Feature)
```javascript ```javascript
const complexityFactors = { function adjustDifficulty(playerMetrics, level) {
nodeCount: { const skillLevel = calculateSkillLevel(playerMetrics);
weight: 2.0, const baseComplexity = getBaseComplexity(level);
calculate: (nodes) => nodes
},
connectionDensity: { // Adjust complexity based on player performance
weight: 1.5, if (skillLevel > 1.2) {
calculate: (connections, nodes) => connections.length / (nodes * (nodes - 1) / 2) return baseComplexity * 1.1; // Increase challenge
}, } else if (skillLevel < 0.8) {
return baseComplexity * 0.9; // Reduce challenge
patternSymmetry: {
weight: -0.5, // Symmetric patterns are easier
calculate: (connections) => calculateSymmetryScore(connections)
},
crossingConnections: {
weight: 1.0,
calculate: (connections, nodePositions) => countCrossings(connections, nodePositions)
} }
};
function calculateLevelComplexity(level) { return baseComplexity; // Maintain standard progression
let totalComplexity = 0;
Object.entries(complexityFactors).forEach(([factor, config]) => {
const value = config.calculate(level);
totalComplexity += value * config.weight;
});
return totalComplexity;
} }
``` ```
### Dynamic Difficulty Adjustment ### Balancing Principles
```javascript 1. **Fail-Forward Design**: Failure teaches rather than punishes
class DifficultyAdjuster { 2. **Multiple Success Paths**: Avoid single "correct" solutions when possible
constructor() { 3. **Predictable Escalation**: Players can anticipate difficulty increases
this.playerPerformance = []; 4. **Skill Transfer**: Patterns teach techniques useful in later levels
this.adjustmentThreshold = 3; // Adjust after 3 consecutive fails/successes 5. **Recovery Opportunities**: Difficult levels followed by easier consolidation
}
recordPerformance(level, completed, timeRemaining) { ## Testing and Iteration
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 ### Playtesting Metrics
```javascript - **Completion Rates**: Target 70%+ for each difficulty phase
const playtestingMetrics = { - **Time Distribution**: Histogram of completion times per level
completionRate: { - **Abandonment Points**: Where players stop playing
target: '>80% for levels 1-10, >60% for levels 11-20, >40% for levels 21+', - **Replay Patterns**: Which levels players retry most
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 ### A/B Testing Framework
```javascript ```javascript
class LevelTester { const levelVariants = {
constructor() { control: generateStandardLevel(level),
this.variants = {}; variant: generateAlternativeLevel(level),
this.results = {}; test: generateExperimentalLevel(level)
}
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; function trackLevelPerformance(variant, playerResults) {
} // Record completion rate, time, satisfaction
analytics.track('level_performance', {
variant,
level,
completed: playerResults.completed,
time: playerResults.completionTime,
attempts: playerResults.attempts
});
} }
``` ```
## Special Level Types ### Continuous Improvement
- **Weekly Analysis**: Review player performance data
- **Monthly Balancing**: Adjust difficult outlier levels
- **Quarterly Evolution**: Introduce new pattern types
- **Annual Overhaul**: Comprehensive progression review
### Bonus Levels ## Future Enhancements
**Frequency**: Every 10 levels
**Purpose**: Reward progress with fun, creative challenges
**Characteristics**: Unique mechanics, relaxed time pressure, special visual effects
### Recovery Levels ### Adaptive Progression
**Frequency**: After 3 consecutive failures - Machine learning-based difficulty adjustment
**Purpose**: Rebuild confidence and momentum - Personalized level generation based on player strengths
**Characteristics**: Slightly easier than expected, familiar patterns, generous time - Dynamic time limits based on individual performance
- Skill-based matchmaking for competitive modes
### Skill Check Levels ### Content Expansion
**Frequency**: Levels 10, 20, 30, etc. - Themed level packs with unique mechanics
**Purpose**: Validate mastery before advancing to next tier - Community-generated level sharing
**Characteristics**: Comprehensive challenge using all learned concepts - Seasonal events with special progression tracks
- Achievement-based unlock system for advanced levels
This progression system ensures players remain engaged while being appropriately challenged throughout their journey. ### Accessibility Options
- Colorblind-friendly pattern variations
- Simplified patterns for cognitive accessibility
- Extended time limits for motor accessibility
- Tutorial replay system for learning reinforcement
## Success Metrics
### Player Retention Indicators
- **Session Length**: Average time spent per play session
- **Return Rate**: Percentage of players returning within 24 hours
- **Progression Rate**: Average levels completed per session
- **Satisfaction Score**: Implicit satisfaction based on play patterns
### Difficulty Curve Validation
- **Completion Rate Curve**: Smooth decline from 90% to 60% across levels
- **Time Investment Curve**: Gradual increase in average completion time
- **Replay Frequency**: Higher replay on challenging but fair levels
- **Abandonment Analysis**: Minimal dropoff at any single difficulty spike
The level progression system serves as the backbone of player engagement, ensuring that Neural Nexus provides a consistently challenging and rewarding experience that grows with the player's developing skills.
Last Updated: June 2025
Next Review: July 2025 (Monthly progression analysis)