NEXUS ENGINE 3: Pure LLM-Driven Interactive Fiction

The Complete AI Game Engine - Everything Decided by LLM

NEXUS ENGINE 3 represents the ultimate evolution of AI-driven storytelling. Unlike traditional text adventures with hardcoded responses, every aspect of the game world is controlled by advanced Language Learning Models with extensive prompt caching for optimal performance.

🧠 Pure LLM Architecture

NEXUS ENGINE 3 is fundamentally different from other interactive fiction engines:

• No Hardcoded Game Logic: The LLM makes ALL decisions about what you can do, where you can go, and what happens
• Complete World Simulation: Characters, locations, inventory, relationships - everything exists only in the LLM's understanding
• Intelligent State Management: Advanced compression and summarization keeps long stories coherent
• Prompt Caching Optimization: Massive story content cached for 90% cost savings and instant responses

🚀 Quick Start

Launch the engine:

python -m engine.nexus

Or use the entry point script:

./nexus.sh

Requirements:

• Python 3.8+
• API key for Claude Sonnet 4 (recommended) or OpenAI GPT-4.1
• Internet connection

🎮 Pure Neural Gameplay

How It Works

1. Type anything in natural language - the AI decides if it's possible
2. No command restrictions - try "examine the quantum fluctuations in the coffee"
3. Dynamic world creation - the AI can invent new locations and characters on demand
4. Persistent memory - everything you do is remembered and affects future possibilities

Example Interactions

> Ask Elena about her sister's connection to the memory modification experiments
> Carefully examine the corporate executive's neural implant for security vulnerabilities  
> Try to hack into the building's AI system using the stolen authentication codes
> Comfort the frightened AI entity and ask about its experiences with consciousness

The AI has complete creative control within the story framework.

🧠 Included Stories

Digital Shadows 2025

Genre: Modern Cyberthriller
Length: 10-15 hours
Theme: Surveillance, privacy, and digital resistance in near-future America

A investigative journalist discovers a massive surveillance conspiracy involving tech companies, government agencies, and foreign actors. Navigate the dangerous world of digital privacy, corporate espionage, and grassroots resistance.

Features:

• Multiple investigation paths through hacking, journalism, and social engineering
• Complex faction dynamics between privacy advocates, corporations, and government
• Real-world inspired technology and social issues
• Five distinct endings based on your approach and moral choices

Neon Shadows 2030

Genre: Cyberpunk Noir Length: 10-15 hours Theme: AI consciousness, corporate power, and identity in a cyberpunk future

Classic detective noir set in Neo-Francisco where AI consciousness threatens corporate control. Investigate a missing researcher while navigating the complex relationships between humans, AIs, and corporate interests.

Features:

• Deep philosophical exploration of AI consciousness and rights
• Noir atmosphere with cyberpunk technology
• Multiple character relationship paths
• Corporate conspiracy with personal stakes

⚙️ Engine Architecture

Core Components

LLMOrchestrator (engine/orchestrator.py)

• Manages all LLM calls with extensive prompt caching
• Parses LLM decisions and story responses
• Handles conversation context and state updates

LLMState (engine/state.py)

• Intelligent state compression to maintain coherent long stories
• Tracks relationships, discoveries, and world changes
• Automatic context size management for optimal performance

StoryLoader (engine/story.py)

• Loads complete story content into massive cached prompts
• Builds comprehensive system context for consistent world simulation
• Optimizes content for prompt caching efficiency

LLMInterface3 (engine/llm.py)

• Support for Claude Sonnet 4 and GPT-4.1 with prompt caching
• Automatic model selection and optimization
• Usage tracking and cache efficiency monitoring

Configuration

Customize engine behavior via config.json:

{
  "llm_settings": {
    "max_tokens_response": 2000
  },
  "ui_settings": {
    "typewriter_delay": 0.02,
    "box_width": 70
  }
}

LLM Setup

Claude Sonnet 4 (Recommended):

export ANTHROPIC_API_KEY="your_api_key_here"

OpenAI GPT-4.1:

export OPENAI_API_KEY="your_api_key_here"

Demo Mode: Runs without API keys using mock responses to showcase the interface.

🎯 Pure LLM Gameplay

Natural Language Interface

Unlike traditional text adventures, NEXUS ENGINE 3 has no predefined commands. The AI understands and responds to natural language:

> I want to carefully analyze the quantum encryption patterns in the security system
> Try to build trust with the AI by sharing my own experiences with consciousness  
> Search through the abandoned research facility for any clues about the missing scientist
> Attempt to negotiate a peaceful solution between the corporate security and the activists

System Commands

• save - Save your progress
• info - Show AI model and usage statistics
• help - Display help information
• quit - Exit the game

Psychology-Driven Adaptation

The AI analyzes your playing style and adapts the story:

• High Curiosity (7-10): Extra mysteries, hidden areas, deep lore, alternative solutions
• High Empathy (7-10): Character focus, emotional stakes, relationship consequences
• High Risk Tolerance (7-10): Dangerous choices, permanent consequences, high stakes
• High Intellectual Engagement (7-10): Complex puzzles, philosophical themes, technical depth
• High Social Preference (7-10): Rich NPCs, dialogue trees, diplomatic solutions

AI Decision Making

The LLM controls everything:

• What locations you can access and when
• How characters react to your choices
• What items and clues you discover
• Which story paths become available
• How relationships develop over time

📁 Project Structure

adventure002/
├── engine/                      # Pure LLM Engine Core
│   ├── __init__.py             # NexusEngine3 and component exports
│   ├── core.py                 # Main engine (NexusEngine3 class)
│   ├── config.py               # ConfigManager for engine settings
│   ├── llm.py                  # LLMInterface3 with prompt caching
│   ├── orchestrator.py         # LLMOrchestrator for decision processing
│   ├── state.py                # LLMState with intelligent compression  
│   ├── story.py                # StoryLoader for content caching
│   ├── ui.py                   # TerminalUI with 80s aesthetic
│   └── nexus.py                # Entry point script
├── config.json                 # Engine configuration
├── requirements.txt            # Python dependencies  
├── nexus.sh                    # Launch script
├── STORIES.md                  # Complete story creation guide
├── stories/                    # Story content directory
│   ├── digital_shadows_2025/   # Modern cyberthriller story
│   │   ├── story.json         # Story config and AI instructions
│   │   ├── characters/        # 12 character JSON files
│   │   ├── worlds/            # 11 location JSON files  
│   │   ├── events/            # 4 major event JSON files
│   │   └── endings/           # 5 ending JSON files
│   └── neon_shadows_2030/     # Cyberpunk noir story
│       ├── story.json         # Story config and AI instructions
│       ├── characters/        # 7 character JSON files
│       ├── worlds/            # 4 location JSON files
│       ├── events/            # 3 major event JSON files
│       └── endings/           # 5 ending JSON files
└── saves/                     # Player save files
    └── [username]/
        └── [story]/
            └── state.json     # Complete game state

🎨 Engine Features

Pure LLM Decision Making

• No Hardcoded Logic: Every game interaction decided by AI
• Dynamic World Creation: AI can invent new content on demand
• Intelligent State Tracking: Automatic context compression for long stories
• Psychology Adaptation: Story adapts to player behavior patterns

Advanced Prompt Caching

• Massive Story Content: Complete stories cached for instant access
• 90% Cost Savings: Anthropic prompt caching optimization
• Consistent World Simulation: AI has complete story knowledge always available
• Smart Context Management: Automatic compression when approaching token limits

Retro Terminal Interface

• 80s Aesthetic: Classic cyberpunk visual styling
• Typewriter Effects: Nostalgic text animation
• Box Drawing: Clean terminal UI with ASCII art
• Color Schemes: Neon green/cyan terminal colors

🛠 Technical Requirements

• Python 3.8+
• Internet connection for LLM API calls
• API Key for Claude Sonnet 4 or OpenAI GPT-4.1
• Terminal with Unicode and color support

Dependencies

All automatically installed:

• anthropic>=0.7.0 (Claude Sonnet 4 support)
• openai>=1.0.0 (GPT-4.1 support)
• python-dotenv (environment variable loading)

📖 Story Creation

NEXUS ENGINE 3 is designed for story creators who want to leverage pure LLM decision-making. See STORIES.md for the complete creation guide.

Story Structure

Each story contains:

1. story.json: Core configuration with comprehensive AI instructions
2. characters/: Complete NPC profiles with psychology adaptations
3. worlds/: Location descriptions with interactive elements
4. events/: Major story beats and revelation timing
5. endings/: Five distinct conclusions based on player choices

Psychology-Driven Content

Stories must adapt to five psychology dimensions:

• Curiosity (1-10): Hidden content, secret areas, deep mysteries
• Empathy (1-10): Character focus, emotional stakes, relationships
• Risk Tolerance (1-10): Dangerous choices, permanent consequences
• Intellectual (1-10): Complex puzzles, philosophical themes
• Social (1-10): NPC relationships, dialogue trees, diplomacy

Content Requirements

• 10-15 hours of adaptive gameplay
• 15-25 locations with psychology-specific content
• 8-15 characters with complete relationship arcs
• 5 endings reflecting different player approaches
• 200+ interactive elements for thorough exploration

🐛 Troubleshooting

LLM not responding?

• Verify API key: echo $ANTHROPIC_API_KEY or echo $OPENAI_API_KEY
• Check internet connection
• Use demo mode (runs without API keys)

State compression issues?

• Engine automatically compresses context when approaching limits
• Check info command for context size and token usage
• Large stories may need periodic summarization

Performance problems?

• Prompt caching reduces costs by 90% on supported models
• First story load builds cache (may take 10-15 seconds)
• Subsequent interactions use cached content (near-instant)

🚀 Advanced Usage

Usage Monitoring

Use the info command during gameplay to see:

• AI model and token usage
• Cache hit rate and efficiency
• Context size and compression status
• Session statistics

State Management

• Auto-save every 5 interactions
• Manual save with save command
• Intelligent context compression maintains story coherence
• State includes complete conversation history and LLM decisions

Development Mode

For story creators testing new content:

• Use demo mode to test story structure without API costs
• Monitor context size to optimize content volume
• Test all five psychology profiles for complete coverage

---

Trust the AI - it's running the entire game world.