vr-narrative-engine 0.1.0

WebXR interactive fiction engine with physics-based narrative triggers

VR Narrative Engine

Interactive fiction meets spatial interaction—craft branching stories in WebXR where physical gameplay drives the narrative.

What is this?

VR Narrative Engine is a WebXR-powered interactive fiction system that transforms narrative gameplay through embodied interaction. Instead of selecting dialogue from a menu, players physically pick up story objects, perform gesture sequences (like drum patterns), and use spatial positioning to unlock choices and trigger plot beats. It bridges physics-based VR experiences with branching narrative, enabling developers to build story-driven games where the how of interaction matters as much as the what.

Features

• Spatial Story Objects — Items in the VR environment that trigger narrative branches when picked up or manipulated
• Gesture-Based Plot Triggers — Rhythm patterns, hand movements, and physical sequences unlock story beats
• Position-Aware Dialogue — NPC responses and story paths change based on player location in the scene
• Branching Narrative Graph — Full support for complex story trees with multiple endings and convergence points
• WebXR Compatible — Works with Meta Quest, Apple Vision Pro, and WebXR-enabled browsers
• Physics Integration — Built to work seamlessly with existing physics engines (Phantom Rack, SplitScreen)
• Real-Time State Sync — Backend tracks narrative state, choices, and player progress
• Developer Tooling — Simple APIs for story authors and game developers

Quick Start

Installation

# Clone the repository
git clone <repo-url>
cd vr-narrative-engine

# Install dependencies
pip install -r pyproject.toml
npm install  # if frontend dependencies exist

# Set up environment
cp .env.example .env

Running Locally

# Start backend (FastAPI)
python backend/main.py

# Start frontend (separate terminal)
cd frontend
npm run dev

# Run tests
pytest tests/

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Access at http://localhost:8000

Usage

Basic Story Definition

// Define a narrative node with spatial triggers
const storyNode = {
  id: "cabin_discovery",
  text: "You find an old journal on the shelf.",
  triggers: {
    spatial: { position: [1.5, 1.2, 0.8], radius: 0.5 },
    gesture: "drum_pattern_abc",
    item_pickup: "journal"
  },
  choices: [
    { text: "Read the journal", next: "journal_content" },
    { text: "Leave it", next: "cabin_exit" }
  ]
};

Connecting to Your VR Scene

// In your WebXR application
const engine = new NarrativeEngine("ws://localhost:8000/narrative");

engine.on("objectInteraction", (objectId, interactionType) => {
  // Trigger story progression
  engine.advancePlot(objectId);
});

engine.on("narrativeUpdate", (newState) => {
  // Update UI, NPC behavior, environmental state
  updateDialogueDisplay(newState.currentText);
  triggerAudioNarration(newState.currentAudio);
});

Tech Stack

• Backend: Python FastAPI, WebSocket support for real-time state sync
• Frontend: JavaScript/WebXR (vanilla or framework-agnostic)
• Database: PostgreSQL for narrative state and user progress
• Deployment: Docker, Railway, Render (config files included)
• Testing: pytest for backend, Jest for frontend
• CI/CD: GitHub Actions for automated testing and deployment

Deployment

Pre-configured deployment files for:

• Railway: railway.json — One-click deployment with auto-scaling
• Render: render.yaml — Full-stack hosting with managed databases
• Docker: Dockerfile + docker-compose.yml — Self-hosted option

License

MIT