Performance Tuning - ByteSower/qnce-engine GitHub Wiki

โš ๏ธ QNCE Engine is Under Major Reconstruction

Notice (Feb 2026): The QNCE Engine is currently undergoing major reconstruction. Many features, including narrative rules and story flow, may not behave as expected. The engine is transitioning toward broader quantum modeling principles and improved performance. If you require stability, consider waiting for a future release. See GitHub and npm for updates.

Performance Tuning Guide

This guide covers performance optimization techniques for QNCE Engine, including object pooling, background processing, hot-reload optimization, and performance monitoring.

โšก Overview

QNCE Engine v1.2.3 introduces enterprise-grade performance infrastructure designed to handle large-scale interactive narratives with minimal latency and memory usage.

Performance Targets

Metric Target Typical Results
State Transitions โ‰ค5ms ~3ms
Flow Switches โ‰ค20ms ~12ms
Hot-reload Updates <2ms ~1.8ms
Memory Usage โ‰ค50MB ~35MB
Cache Hit Rate โ‰ฅ95% ~98%

๐ŸŠโ€โ™‚๏ธ Object Pooling

What is Object Pooling?

Object pooling reduces garbage collection pressure by reusing objects instead of creating new ones. QNCE Engine implements sophisticated pooling for all frequently allocated objects.

Benefits

  • 90%+ allocation reduction compared to naive implementations
  • Eliminates GC pressure during story execution
  • Consistent frame rates in real-time applications
  • Lower memory fragmentation

Configuration

import { createQNCEEngine } from 'qnce-engine';

const engine = createQNCEEngine(story, {
  enablePerformanceMode: true,
  performanceOptions: {
    objectPooling: {
      enable: true,
      preAllocate: true,           // Pre-allocate common objects
      poolSizes: {
        nodes: 100,                // Pool 100 node objects
        choices: 200,              // Pool 200 choice objects
        flags: 50,                 // Pool 50 flag objects
        events: 150                // Pool 150 event objects
      },
      cleanupInterval: 30000,      // Cleanup unused objects every 30s
      maxPoolSize: 1000            // Maximum total pooled objects
    }
  }
});

Manual Pool Management

// Access object pools directly (advanced usage)
const pools = engine.getObjectPools();

// Check pool statistics
console.log('Node pool usage:', pools.nodes.used, '/', pools.nodes.total);
console.log('Choice pool efficiency:', pools.choices.hitRate);

// Manually trigger cleanup
pools.cleanup();

// Preload pools for known story size
pools.preAllocate({
  estimatedNodes: 500,
  estimatedChoices: 1000,
  estimatedFlags: 100
});

๐Ÿงต Background Processing

ThreadPool Architecture

QNCE Engine uses background processing to handle computationally expensive operations without blocking the main story thread.

const engine = createQNCEEngine(story, {
  enablePerformanceMode: true,
  performanceOptions: {
    backgroundProcessing: {
      enable: true,
      maxWorkers: 4,               // Maximum background workers
      queueSize: 100,              // Task queue size
      priority: 'normal',          // Task priority (low, normal, high)
      timeSlicing: true,           // Time-slice long operations
      maxExecutionTime: 16         // Max execution time per frame (ms)
    }
  }
});

Background Tasks

Analytics Processing

// Analytics are processed in background
engine.enableBackgroundAnalytics({
  playerBehavior: true,
  choicePatterns: true,
  performanceMetrics: true,
  processInterval: 5000,           // Process every 5 seconds
  batchSize: 50                    // Process 50 events at a time
});

// Non-blocking analytics queries
const analytics = await engine.getAnalytics({ background: true });

Cache Preloading

// Intelligent cache preloading
engine.enableSmartCaching({
  preloadDepth: 3,                 // Preload 3 levels ahead
  preloadStrategy: 'adaptive',     // Adapt based on player patterns
  backgroundPreload: true,         // Preload in background
  cacheSize: 100,                  // Maximum cached items
  ttl: 300000                      // Cache TTL (5 minutes)
});

AI Content Generation

// Generate AI content in background
engine.enableBackgroundAI({
  preGenerateChoices: true,        // Pre-generate likely choices
  batchGeneration: true,           // Generate content in batches
  queueSize: 20,                   // AI generation queue size
  fallbackContent: true           // Use cached content as fallback
});

๐Ÿ”ฅ Hot-Reload Optimization

Delta Patching System

Hot-reload uses intelligent delta patching to apply only necessary changes.

// Enable optimized hot-reload
engine.enableHotReload({
  deltaPatching: true,             // Use delta patching
  smartInvalidation: true,         // Intelligent cache invalidation
  preserveState: true,             // Preserve player state
  validateChanges: true,           // Validate changes before applying
  maxPatchSize: 1000,              // Maximum patch size
  timeLimit: 2                     // Target time limit (ms)
});

// Monitor hot-reload performance
engine.on('hotReloadComplete', (metrics) => {
  console.log('Hot-reload time:', metrics.duration);
  console.log('Nodes updated:', metrics.nodesUpdated);
  console.log('Cache invalidations:', metrics.cacheInvalidations);
});

Hot-Reload Best Practices

// Optimize story structure for hot-reload
const optimizedStory = {
  // Use stable IDs for nodes
  nodes: [
    { id: 'stable-node-1', /* ... */ },
    { id: 'stable-node-2', /* ... */ }
  ],
  
  // Group related content
  chapters: [
    {
      id: 'chapter-1',
      // Related nodes in same chapter reload faster
      nodes: [/* related nodes */]
    }
  ],
  
  // Separate data from logic
  metadata: {
    // Metadata changes don't trigger full reload
    version: '1.2.3'
  }
};

๐Ÿ“Š Performance Monitoring

Built-in Profiling

// Enable comprehensive profiling
engine.enableProfiling({
  trackAllOperations: true,        // Track all engine operations
  memoryTracking: true,            // Monitor memory usage
  performanceMarks: true,          // Use Performance API marks
  exportFormat: 'json',            // Export format for reports
  reportInterval: 60000,           // Generate reports every minute
  alertThresholds: {
    stateTransition: 5,            // Alert if >5ms
    flowSwitch: 20,                // Alert if >20ms
    memoryUsage: 50                // Alert if >50MB
  }
});

// Access real-time metrics
const metrics = engine.getPerformanceMetrics();
console.log('Current memory usage:', metrics.memoryUsage);
console.log('Average transition time:', metrics.avgTransitionTime);
console.log('Cache efficiency:', metrics.cacheHitRate);

CLI Performance Monitoring

# Real-time performance dashboard
qnce-perf dashboard --live

# Monitor specific metrics
qnce-perf monitor --metric state-transitions --threshold 5ms

# Generate performance report
qnce-perf report --format json --output performance.json

# Performance profiling session
qnce-perf profile --duration 5m --verbose

Custom Performance Tracking

// Add custom performance markers
engine.startPerformanceTimer('custom-operation');
// ... your code ...
const duration = engine.endPerformanceTimer('custom-operation');

// Track custom metrics
engine.recordMetric('customMetric', value, {
  category: 'gameplay',
  subcategory: 'choices',
  unit: 'milliseconds'
});

// Set up performance alerts
engine.addPerformanceAlert('high-memory', {
  condition: 'memoryUsage > 100MB',
  action: 'cleanup',
  notify: true
});

๐ŸŽฏ Optimization Strategies

Story Size Optimization

Large Story Handling

// Configuration for large stories (1000+ nodes)
const largeStoryConfig = {
  enablePerformanceMode: true,
  performanceOptions: {
    lazyLoading: true,             // Load content on demand
    chunkSize: 50,                 // Load 50 nodes at a time
    memoryLimit: 100,              // 100MB memory limit
    gcStrategy: 'aggressive',      // Aggressive garbage collection
    cacheStrategy: 'lru',          // LRU cache eviction
    backgroundProcessing: {
      enable: true,
      maxWorkers: 6,               // More workers for large stories
      priority: 'high'
    }
  }
};

Memory-Efficient Story Structure

// Optimize story structure for memory efficiency
const memoryEfficientStory = {
  // Use shared objects for common data
  sharedChoices: {
    'continue': { text: 'Continue', action: 'continue' },
    'back': { text: 'Go back', action: 'back' }
  },
  
  // Reference shared choices instead of duplicating
  nodes: [
    {
      id: 'node1',
      text: 'Story text...',
      choices: ['continue', 'back'] // Reference shared choices
    }
  ],
  
  // Use efficient data structures
  flags: new Map(),                // Use Map for better performance
  metadata: Object.freeze({        // Freeze immutable data
    author: 'Author Name'
  })
};

Runtime Optimization

Efficient Choice Processing

// Optimize choice evaluation
const optimizedChoiceEvaluation = {
  // Pre-compile conditions for faster evaluation
  preCompileConditions: true,
  
  // Cache condition results
  cacheConditions: true,
  
  // Use efficient data structures
  choiceIndex: new Map(),          // Index choices for fast lookup
  
  // Batch operations
  batchSize: 10,                   // Process choices in batches
  
  // Early exit optimizations
  shortCircuit: true               // Stop evaluating when result is determined
};

Flag System Optimization

// Efficient flag management
const flagOptimization = {
  // Use typed flags for better performance
  typedFlags: {
    booleans: new Set(),           // Use Set for boolean flags
    numbers: new Map(),            // Use Map for numeric flags
    strings: new Map()             // Use Map for string flags
  },
  
  // Batch flag updates
  batchUpdates: true,
  
  // Use efficient serialization
  serialization: 'binary',         // Binary serialization for speed
  
  // Limit flag history for memory efficiency
  maxHistory: 100
};

๐Ÿ”ง Platform-Specific Optimizations

Web Browser Optimizations

// Browser-specific optimizations
const browserConfig = {
  performanceOptions: {
    // Use Web Workers for background processing
    useWebWorkers: true,
    
    // Optimize for 60fps
    targetFrameRate: 60,
    
    // Use requestIdleCallback for background tasks
    useIdleCallback: true,
    
    // Minimize DOM updates
    batchDOMUpdates: true,
    
    // Use efficient event handling
    passiveEventListeners: true
  }
};

Node.js Server Optimizations

// Server-specific optimizations
const serverConfig = {
  performanceOptions: {
    // Use cluster mode for multiple processes
    cluster: {
      enable: true,
      workers: require('os').cpus().length
    },
    
    // Enable V8 optimizations
    v8Optimizations: true,
    
    // Use streaming for large responses
    streaming: true,
    
    // Optimize garbage collection
    gcSettings: {
      maxOldSpaceSize: 4096,       // 4GB max heap
      maxNewSpaceSize: 1024        // 1GB new generation
    }
  }
};

Mobile Device Optimizations

// Mobile-specific optimizations
const mobileConfig = {
  performanceOptions: {
    // Reduce memory usage for mobile devices
    lowMemoryMode: true,
    
    // Optimize for touch interactions
    touchOptimization: true,
    
    // Reduce background processing
    reducedProcessing: true,
    
    // Use efficient rendering
    lightweightRendering: true,
    
    // Battery optimization
    batteryOptimization: true
  }
};

๐Ÿ“ˆ Performance Testing

Automated Performance Tests

// Set up performance testing
const performanceTester = engine.createPerformanceTester();

// Test state transition performance
performanceTester.testStateTransitions({
  iterations: 1000,
  targetTime: 5,                   // 5ms target
  storySize: 'large',
  concurrent: true
});

// Test memory usage
performanceTester.testMemoryUsage({
  duration: 300000,                // 5 minutes
  operations: ['navigate', 'choice', 'flag-update'],
  memoryLimit: 50                  // 50MB limit
});

// Test hot-reload performance
performanceTester.testHotReload({
  changes: 100,                    // 100 story changes
  targetTime: 2,                   // 2ms target
  preserveState: true
});

Load Testing

// Simulate high load scenarios
const loadTester = engine.createLoadTester();

// Test concurrent users
loadTester.simulateConcurrentUsers({
  userCount: 1000,
  duration: 600000,                // 10 minutes
  userBehavior: 'realistic',
  rampUpTime: 60000               // 1 minute ramp-up
});

// Stress test
loadTester.stressTest({
  maxUsers: 5000,
  incrementRate: 100,              // Add 100 users every second
  targetMetrics: {
    avgResponseTime: 100,          // 100ms average
    errorRate: 0.1                 // 0.1% error rate
  }
});

๐Ÿšจ Performance Troubleshooting

Common Performance Issues

High Memory Usage

// Diagnose memory issues
const memoryDiagnostics = engine.diagnoseMemory();

if (memoryDiagnostics.usage > 50) {
  // Enable aggressive cleanup
  engine.enableAggressiveCleanup();
  
  // Reduce cache sizes
  engine.reduceCacheSizes(0.5);
  
  // Force garbage collection
  engine.forceGarbageCollection();
}

Slow State Transitions

// Diagnose slow transitions
const transitionDiagnostics = engine.diagnoseTransitions();

if (transitionDiagnostics.avgTime > 5) {
  // Enable faster transition mode
  engine.enableFastTransitions();
  
  // Precompile conditions
  engine.precompileConditions();
  
  // Optimize choice evaluation
  engine.optimizeChoiceEvaluation();
}

Poor Cache Performance

// Optimize cache performance
const cacheStats = engine.getCacheStatistics();

if (cacheStats.hitRate < 0.9) {
  // Increase cache size
  engine.increaseCacheSize(1.5);
  
  // Improve cache strategy
  engine.setCacheStrategy('adaptive');
  
  // Enable predictive caching
  engine.enablePredictiveCache();
}

๐Ÿ“Š Performance Monitoring Dashboard

CLI Dashboard

# Launch real-time performance dashboard
qnce-perf dashboard

# Dashboard shows:
# - Real-time memory usage
# - State transition times
# - Cache hit rates
# - Background task queue status
# - Performance alerts

Custom Dashboard Integration

// Integrate with custom monitoring systems
engine.enableMetricsExport({
  format: 'prometheus',            // Prometheus metrics format
  endpoint: '/metrics',            // Metrics endpoint
  interval: 10000,                 // Export every 10 seconds
  customMetrics: [
    'story_navigation_time',
    'choice_evaluation_time',
    'flag_update_time'
  ]
});

// Integration with popular monitoring tools
engine.integrateWith('grafana', {
  dashboardId: 'qnce-performance',
  apiKey: process.env.GRAFANA_API_KEY
});

Ready to optimize your narrative engine?

CLI Usage โ†’ | Performance Docs โ†’ | Get Support โ†’

Built with โค๏ธ by the QNCE development team


๐Ÿ“ Wiki Navigation

โ† Previous: Branching Guide | You are here: Performance Tuning | Next: CLI Usage โ†’

All Pages: Home โ€ข Getting Started โ€ข Branching Guide โ€ข Performance Tuning โ€ข CLI Usage โ€ข API Reference โ€ข Contributing โ€ข Release Notes


This documentation is maintained for QNCE Engine v1.2.3 with advanced feature set including Choice Validation, State Persistence, Conditional Choices, Autosave & Undo/Redo, and UI Components.

โš ๏ธ **GitHub.com Fallback** โš ๏ธ