Metadata-Version: 2.4
Name: vr-narrative-engine
Version: 0.1.0
Summary: WebXR interactive fiction engine with physics-based narrative triggers
Project-URL: Homepage, https://github.com/yourusername/vr-narrative-engine
Project-URL: Repository, https://github.com/yourusername/vr-narrative-engine
Author-email: Developer <dev@example.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: fastapi>=0.104.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: dev
Requires-Dist: black>=23.11.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
# 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

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

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

# Run tests
pytest tests/
```

### Docker Deployment

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

# Access at http://localhost:8000
```

## Usage

### Basic Story Definition

```javascript
// 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

```javascript
// 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