Interactive 3D Narrative Game

A full-stack interactive storytelling game with 3D graphics, dynamic narratives, and MongoDB integration.

🎮 Features

• 3D Interactive World: Built with Three.js featuring 8 unique environments
• Dynamic Storytelling: Branching narratives with player choices that matter
• Player Progression: Health, gold, items, reputation, and level systems
• MongoDB Integration: Persistent story nodes and player data
• Offline Mode: Fallback system when server is unavailable
• Enhanced Graphics: Shadows, lighting, particle effects, and animations

🚀 Quick Start

Backend Setup

1. Install Python dependencies:

pip install -r requirements.txt

2. Set up environment variables in .env:

MONGODB_URI=your_mongodb_connection_string
PORT=5000

3. Populate sample story data:

python populate_story_nodes.py

4. Start the Flask server:

python app.py

Frontend

Open game.html in a web browser or serve it through a local server.

🎯 Game Controls

• WASD/Arrow Keys: Move player character
• Shift: Run faster
• Mouse Drag: Rotate camera around player
• Mouse Wheel: Zoom in/out
• Space: Change environment
• Click Buttons: Make story choices

🌍 Environments

1. Forest - Ancient trees and mystical creatures
2. Desert - Sand dunes and oasis with palm trees
3. Village - Bustling marketplace and friendly NPCs
4. Castle - Medieval fortress with towers and flags
5. Ocean - Ships, islands, and animated waves
6. Mountain - Rocky peaks and snow-capped heights
7. Cave - Glowing crystals and mysterious depths
8. Jungle - Dense vegetation and exotic wildlife

🔧 API Endpoints

• GET /: API status check
• POST /game/start: Initialize new game session
• POST /game/choice: Process player choice
• GET /story/nodes: Get all story nodes
• POST /story/nodes: Create new story node

📁 Project Structure

├── app.py                      # Flask backend server
├── game.html                   # 3D game frontend
├── models/
│   ├── game_models.py         # Data models
│   └── Event.js               # Event model
├── services/
│   ├── database_handler.py    # MongoDB operations
│   ├── game_service.py        # Game logic
│   ├── story_service.py       # Story management
│   ├── player_state_service.py # Player data
│   └── error_handler.py       # Error handling
├── populate_story_nodes.py    # Database seeding
├── judge_demo_guide.md        # Demo instructions
├── MONGODB_EXPLANATION.md     # Database documentation
└── requirements.txt           # Python dependencies

🎪 Demo Guide

For judges and evaluators, see judge_demo_guide.md for a complete demonstration walkthrough.

🗄️ Database

• MongoDB Atlas: Cloud-hosted database
• Collections: story_nodes, players, events
• Features: Persistent game state, multiplayer support
• Fallback: Local offline mode available

🛠️ Technologies Used

• Backend: Python Flask, MongoDB, PyMongo
• Frontend: Three.js, HTML5, CSS3, JavaScript
• Graphics: WebGL, 3D rendering, particle systems
• Architecture: RESTful API, MVC pattern

📝 License

This project is for educational and demonstration purposes.