Package Exports
- qnce-engine
- qnce-engine/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (qnce-engine) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
QNCE Engine
Quantum Narrative Convergence Engine - A framework-agnostic TypeScript library for creating interactive narrative experiences with quantum-inspired mechanics.
๐ NEW in v1.2.0: Advanced Branching API with AI integration, dynamic content management, and comprehensive analytics. Plus enterprise-grade performance optimization.
Core Concepts
- Superposition: Multiple narrative outcomes exist simultaneously until a choice is made
- Collapse: Player choices "collapse" the narrative to a specific path, updating state and flags
- Entanglement: Early decisions affect later outcomes, enabling complex, interconnected stories
โจ Advanced Features (v1.2.0)
๐ฟ Advanced Branching System
- Multi-path narratives with conditional logic and flag-based branching
- AI-driven content generation for dynamic story expansion
- Real-time branch insertion/removal for live content updates
- Comprehensive analytics for narrative optimization
โก Performance Infrastructure
- ๐โโ๏ธ Object Pooling: 90%+ allocation reduction, eliminating GC pressure
- ๐งต Background Processing: Non-blocking cache preloading and telemetry writes
- ๐ฅ Hot-Reload: <3.5ms live story updates with delta patching
- ๐ Real-time Profiling: Comprehensive event instrumentation and analysis
- ๐ฅ๏ธ Live Monitoring:
qnce-perfCLI dashboard with performance alerts
Performance Dashboard
# Real-time performance monitoring
qnce-perf dashboard
# Live monitoring with updates
qnce-perf live 1000
# Export performance data
qnce-perf export > performance-report.json๐ Complete Performance Guide โ
Installation
npm install qnce-engine
# Global CLI installation for performance monitoring
npm install -g qnce-engineQuick Start
Basic Usage
import { createQNCEEngine, DEMO_STORY } from 'qnce-engine';
// Create engine instance with demo story
const engine = createQNCEEngine(DEMO_STORY);
// Get current narrative state
const currentNode = engine.getCurrentNode();
console.log(currentNode.text);
// Get available choices
const choices = engine.getAvailableChoices();
console.log(choices);
// Make a choice
if (choices.length > 0) {
engine.selectChoice(choices[0]);
}
// Check narrative flags
const flags = engine.getFlags();
console.log('Current flags:', flags);Performance Mode (Recommended for Production)
import { createQNCEEngine, DEMO_STORY } from 'qnce-engine';
// Enable performance optimizations
const engine = createQNCEEngine(DEMO_STORY, {}, true, {
maxWorkers: 4,
enableProfiling: true
});
// Background cache preloading happens automatically
// Object pooling reduces memory allocations by 90%+
// Performance events are collected for monitoring
// Get performance statistics
const poolStats = engine.getPoolStats();
console.log(`Pool efficiency: ${poolStats.flow.hitRate}%`);Live Performance Monitoring
# Real-time performance dashboard
qnce-perf dashboard
# Live monitoring with updates every 2 seconds
qnce-perf live
# Export performance data
qnce-perf export > performance-report.json๐ฟ Advanced Branching & AI Integration
Basic Branching
import { createQNCEEngine, createBranchingEngine } from 'qnce-engine';
// Create core engine
const engine = createQNCEEngine(storyData);
// Enable advanced branching
const branchingEngine = engine.enableBranching(advancedStoryData);
// Evaluate available branches
const branches = await branchingEngine.evaluateAvailableBranches();
console.log(`Available paths: ${branches.length}`);
// Execute a narrative branch
await branchingEngine.executeBranch(branches[0].id);AI-Driven Content Generation
// Set AI context for personalized content
branchingEngine.setAIContext({
playerProfile: {
playStyle: 'explorer',
preferences: { adventure: 0.8, mystery: 0.6 },
historicalChoices: ['brave-path', 'investigate-clue']
},
narrativeContext: {
currentTone: 'mysterious',
thematicElements: ['exploration', 'discovery'],
plotTension: 0.7
}
});
// Generate AI-enhanced branches
const aiBranches = await branchingEngine.generateAIBranches(3);
console.log('AI-generated options:', aiBranches.map(b => b.displayText));Dynamic Content Management
// Insert new branch at runtime
const dynamicBranch = {
type: 'insert',
branchId: 'special-event',
targetLocation: { chapterId: 'main', nodeId: 'crossroads' },
payload: {
name: 'Special Event',
branchOptions: [{
id: 'event-choice',
displayText: 'Investigate the mysterious sound',
flagEffects: { event_discovered: true }
}]
}
};
await branchingEngine.insertDynamicBranch(dynamicBranch);
// Remove branch when no longer needed
await branchingEngine.removeDynamicBranch('special-event');Analytics & Monitoring
// Get branching analytics
const analytics = branchingEngine.getBranchingAnalytics();
console.log(`Branches traversed: ${analytics.totalBranchesTraversed}`);
console.log(`Popular choices: ${analytics.mostPopularBranches}`);
// Export comprehensive data
const exportData = branchingEngine.exportBranchingData();
// Contains: story structure, session data, player behavior, performance metricsLive Performance Monitoring
# Real-time performance dashboard
qnce-perf dashboard
# Live monitoring with updates every 2 seconds
qnce-perf live
# Export performance data
qnce-perf export > performance-report.json๐ Performance Guide
QNCE v1.2.0-sprint2 includes advanced performance infrastructure for production applications.
Performance Benchmarks
| Feature | Performance Gain | Impact |
|---|---|---|
| Object Pooling | 90%+ allocation reduction | Eliminates GC hitches |
| Hot-Reload | 68% improvement (3.35ms) | Near-instant story updates |
| Background Processing | Non-blocking operations | Smooth user experience |
| Performance Monitoring | Real-time metrics | Production visibility |
CLI Performance Dashboard
# Install CLI globally
npm install -g qnce-engine
# Real-time performance monitoring
qnce-perf live
# Performance dashboard output:
๐ QNCE Performance Dashboard
=====================================
๐ Session Duration: 45.2s
๐ข Total Events: 1,247
๐พ Cache Performance:
โ
Hit Rate: 92.3% (threshold: 80%)
โ
Avg Cache Time: 0.8ms (threshold: 50ms)
๐ฅ Hot-Reload Performance:
โ ๏ธ Avg Time: 3.35ms (threshold: 2ms)
๐ Max Time: 4.1ms
๐ Total Reloads: 12
๐งต ThreadPool Status:
๐ Completed Jobs: 445
โณ Queued Jobs: 3
๐ Active Workers: 2Performance Mode Usage
// Enable all performance optimizations
const engine = createQNCEEngine(storyData, {}, true, {
maxWorkers: 4, // Background processing
enableProfiling: true // Performance monitoring
});
// Object pooling and background caching happen automatically
// Monitor performance in real-time with CLI dashboard๐ Complete Performance Guide: docs/PERFORMANCE_GUIDE.md
Core API
QNCEEngine Class
The main engine class for managing narrative state.
Methods
getCurrentNode(): Get the current narrative nodegetState(): Get the complete engine stategetFlags(): Get current narrative flagsgetHistory(): Get choice historyselectChoice(choice): Make a narrative choiceresetNarrative(): Reset to initial stateloadState(state): Load a saved statecheckFlag(name, value?): Check flag conditionsgetAvailableChoices(): Get filtered available choices
Factory Functions
createQNCEEngine(storyData, initialState?): Create a new engine instanceloadStoryData(jsonData): Load and validate story data from JSON
Story Format
Stories are defined using JSON with the following structure:
{
"initialNodeId": "start",
"nodes": [
{
"id": "start",
"text": "You stand at a crossroads...",
"choices": [
{
"text": "Go left",
"nextNodeId": "left_path",
"flagEffects": { "direction": "left" }
}
]
}
]
}CLI Tools
qnce-audit
Validate your story structure:
qnce-audit story.jsonFeatures:
- Checks for missing node references
- Identifies unreachable nodes
- Finds dead ends
- Validates story structure
qnce-init
Scaffold a new QNCE project:
qnce-init my-storyCreates:
- Basic story template
- package.json with QNCE dependencies
- README with usage instructions
Integration Examples
React Hook
import { createQNCEEngine } from 'qnce-engine';
import { useState, useEffect } from 'react';
function useQNCE(storyData) {
const [engine] = useState(() => createQNCEEngine(storyData));
const [currentNode, setCurrentNode] = useState(engine.getCurrentNode());
const [flags, setFlags] = useState(engine.getFlags());
const selectChoice = (choice) => {
engine.selectChoice(choice);
setCurrentNode(engine.getCurrentNode());
setFlags(engine.getFlags());
};
return { currentNode, flags, selectChoice };
}Vue Composition API
import { createQNCEEngine } from 'qnce-engine';
import { ref, reactive } from 'vue';
export function useQNCE(storyData) {
const engine = createQNCEEngine(storyData);
const currentNode = ref(engine.getCurrentNode());
const flags = reactive(engine.getFlags());
const selectChoice = (choice) => {
engine.selectChoice(choice);
currentNode.value = engine.getCurrentNode();
Object.assign(flags, engine.getFlags());
};
return { currentNode, flags, selectChoice };
}Node.js CLI
import { createQNCEEngine, loadStoryData } from 'qnce-engine';
import { readFileSync } from 'fs';
import * as readline from 'readline';
const storyData = loadStoryData(JSON.parse(readFileSync('story.json', 'utf-8')));
const engine = createQNCEEngine(storyData);
async function playStory() {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
while (true) {
const node = engine.getCurrentNode();
console.log('\n' + node.text);
if (node.choices.length === 0) break;
node.choices.forEach((choice, i) => {
console.log(`${i + 1}. ${choice.text}`);
});
// Get user input and make choice...
}
}๐ Examples & Demos
The repository includes comprehensive examples demonstrating all features:
๐ Quickstart Example
- File:
examples/branching-quickstart.ts - Features: Basic branching, AI integration, dynamic operations
- Run:
npm run build && node dist/examples/branching-quickstart.js
๐ญ Advanced Demo
- File:
examples/branching-advanced-demo.ts - Features: Complex narrative flows, conditional branching, analytics
- Story: "The Mysterious Library" - Interactive mystery with multiple paths
๐งช Validation Scripts
- Real-world testing:
scripts/validation-real-world.ts - Comprehensive testing:
scripts/validation-comprehensive.ts
# Run the quickstart example
npm run build
node dist/examples/branching-quickstart.js
# Run validation tests
npm run build
node dist/scripts/validation-real-world.jsDevelopment
# Clone and setup
git clone https://github.com/ByteSower/qnce-engine.git
cd qnce-engine
npm install
# Build
npm run build
# Watch mode
npm run build:watch
# Lint
npm run lintLicense
MIT - See LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
QNCE Engine - Empowering interactive narratives with quantum-inspired mechanics.