Luminari Wilderness Editor

A production-ready full-stack monorepo application for creating and managing wilderness regions, paths, and landmarks in the LuminariMUD game world. Built with React/TypeScript frontend, Python FastAPI backend, and integrated with LuminariMUD's MySQL spatial databases.

✅ System Status: EARLY DEVELOPMENT

🌟 Features

Core Functionality

• Interactive Map Display: Visual representation of the wilderness with zoom and pan capabilities
• Advanced Drawing Tools: Point, polygon, and linestring tools with real-time validation feedback
• Precision Coordinate System: Accurate mouse tracking and coordinate conversion at all zoom levels
• Intelligent Selection: Point-in-polygon and distance-to-line algorithms for precise feature selection
• Layer Management: Toggle visibility of regions, paths, and other map elements
• Visual Drawing Feedback: Color-coded validity indicators and real-time guidance

Editing Capabilities

• Visual Region Creation: Draw geographic areas, encounter zones, and terrain modifiers with validation
• Path Drawing: Create roads, rivers, and other linear features with real-time feedback
• Validated Coordinate Entry: Bounds-checked coordinate input with automatic sanitization
• Smart Drawing Validation: Real-time feedback for minimum point requirements and validity
• Enhanced Properties Panel: Input validation, coordinate bounds checking, and user guidance
• Error Prevention: Comprehensive input validation and bounds checking (-1024 to +1024)

Data Management & User Experience

• Robust Error Handling: User-visible error notifications with auto-dismiss functionality
• Loading States: Visual feedback during API operations and data persistence
• Optimistic Updates: Immediate UI feedback with automatic rollback on failures
• Performance Optimized: Canvas memoization and selective re-rendering for smooth interaction
• Keyboard Shortcuts: Enhanced ESC handling for drawing cancellation and tool switching
• Multi-environment Support: Switch between development and production servers

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm 9+ (for frontend workspace support)
• Python 3.8+ (for FastAPI backend)
• Access to LuminariMUD MySQL database (or compatible MySQL setup)
• Modern web browser with JavaScript enabled
• Git

Installation

1. Clone the repository

   git clone https://github.com/moshehbenavraham/wildeditor.git
   cd wildeditor

2. Install dependencies

   # Install frontend dependencies
   npm install
   
   # Install Python backend dependencies
   cd apps/backend/src
   pip install -r requirements.txt

3. Configure environment

   # Frontend configuration
   cp apps/frontend/.env.example apps/frontend/.env
   # Edit apps/frontend/.env:
   #   VITE_API_URL=http://localhost:8000/api
   
   # Backend configuration  
   cp apps/backend/.env.example apps/backend/.env
   # Edit apps/backend/.env:
   #   MYSQL_DATABASE_URL=mysql+pymysql://username:password@localhost/luminari_mudprod
   #   PORT=8000
   #   HOST=0.0.0.0
   
   # Chat Agent configuration (optional)
   # Edit environment variables:
   #   OPENAI_API_KEY=your-openai-key
   #   DEEPSEEK_API_KEY=your-deepseek-key  
   #   WILDEDITOR_MCP_KEY=your-mcp-key

4. Set up MySQL database Ensure your MySQL database has the required spatial tables:

   -- Ensure spatial support is enabled
   -- Create/verify regions, paths, points tables
   -- (See Database Schema section for details)

5. Start development servers

   # Start frontend (Terminal 1)
   npm run dev:frontend  # Frontend on :5173
   
   # Start Python backend (Terminal 2)
   cd apps/backend/src
   python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
   
   # Start Chat Agent (Terminal 3, optional)
   cd apps/agent/src  
   python -m uvicorn main:app --reload --host 0.0.0.0 --port 8002

6. Access the application

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000/api
   • API Documentation: http://localhost:8000/docs
   • Chat Agent: http://localhost:8002 (if running)

🤖 AI-Powered Chat Assistant

The Wilderness Editor features an integrated Chat Assistant that revolutionizes wilderness building through natural language interaction.

🎯 Core Features

• 🗣️ Natural Language Interface: "Create a forest region between the lake and mountain"
• 🧠 Spatial Intelligence: Analyzes terrain and finds optimal placement for new regions
• 🌿 Organic Region Creation: Generates natural-looking borders using advanced algorithms
• 🛤️ Smart Path Building: Creates curved, terrain-aware paths connecting multiple regions
• 🎛️ Draggable Interface: Resizable window with multi-monitor support and markdown rendering
• 💾 Content Staging: All AI-generated content is staged for review before saving

🚀 Quick Start with Chat Assistant

1. Click the chat icon in the top-right corner
2. Drag the window to your preferred location (even to a second monitor!)
3. Ask natural language questions:
   • "Create a dense forest region northeast of the village"
   • "Make a river connecting the mountains to the ocean"
   • "Find empty space for a new region near coordinates (100, 200)"
   • "Connect these three regions with a dirt road"

🏗️ Technical Architecture

Chat UI (Frontend) → Chat Agent (8002) → MCP Server (8001) → Backend (8000) → MySQL

📖 Learn More

• Complete Chat Assistant Guide - Comprehensive usage guide and examples
• Agent Development Guide - Technical details and API reference

🤖 GitHub Copilot Integration

The project also includes MCP (Model Context Protocol) server integration for enhanced GitHub Copilot capabilities:

• AI-Powered Terrain Analysis: Use natural language to analyze wilderness regions
• Intelligent Landmark Creation: Generate and place landmarks with AI assistance
• Smart Path Generation: Create optimized wilderness paths using AI
• Contextual Code Assistance: Enhanced autocomplete and suggestions for wilderness management code

Quick Setup

# Configure GitHub Copilot with MCP server
.\setup-copilot-mcp.ps1 -McpKey "your-mcp-key" -ApiKey "your-api-key"

Example Usage

Open GitHub Copilot Chat in VS Code and try:

• "Analyze the terrain complexity of region 5"
• "Create a mountain peak landmark in the northern area"
• "Generate an optimal path between the forest and mountains"

📚 Complete Setup Guide

🏗️ Monorepo Structure

wildeditor/
├── apps/
│   ├── frontend/          # React TypeScript frontend
│   │   ├── src/
│   │   ├── public/
│   │   └── package.json
│   ├── backend/           # Python FastAPI backend
│   │   └── src/
│   └── mcp/              # MCP server for AI integration
│       ├── src/
│       └── requirements.txt
├── packages/
│   ├── shared/            # Shared types and utilities
│   │   └── src/types/
│   └── auth/              # Shared authentication
└── docs/                  # Documentation
    └── mcp/              # MCP-specific documentation

📖 Documentation

🚀 Getting Started

• User Guide - How to use the wilderness editor interface and tools
• Setup Guide - Quick start installation and configuration
• Documentation Index - Complete documentation organization and guide

👩‍💻 Development

• Developer Guide - Technical architecture and development workflow
• API Documentation - Backend API reference and endpoints
• Testing Guide - Testing strategy and procedures
• Contributing Guide - How to contribute to the project

🚀 Deployment & Operations

• Deployment Guide - Production deployment instructions
• Migration Guide - Express to Python FastAPI migration
• Integration Guide - LuminariMUD game server integration
• Monitoring Guide - Application monitoring and observability
• Backup Guide - Database backup and recovery procedures
• Disaster Recovery - Emergency response procedures

🔒 Security & Compliance

• Security Policy - Security practices and vulnerability reporting
• Changelog - Version history and release notes
• Code Audit - Security and code quality assessment

🏗️ Architecture & Planning

• Wilderness System - LuminariMUD wilderness architecture
• Project Specifications - Detailed project requirements
• Development TODO - Current tasks and development roadmap
• Architecture Decisions - ADR records for major technical decisions

📋 Reference

• Claude Instructions - AI assistant guidance for this codebase
• Chat Assistant Guide - AI-powered wilderness building companion
• Roadmap - Long-term project vision and milestones

🎮 Integration with LuminariMUD

This editor integrates seamlessly with the LuminariMUD wilderness system:

• Coordinate System: Uses the same -1024 to +1024 coordinate space
• Database Compatibility: Works directly with existing LuminariMUD MySQL spatial tables
• Region Types: Supports all game region types (Geographic, Encounter, Sector Transform, Sector Override)
• Path Types: Compatible with roads, rivers, and other path types
• Real-time Updates: Changes reflect immediately in the game world

🛠️ Technology Stack

Frontend (apps/frontend/)

• React 18.3+ - Modern UI framework
• TypeScript 5.5+ - Type-safe development
• Vite 7.0 - Fast build tool and dev server
• Tailwind CSS - Utility-first styling
• Lucide React - Beautiful icons
• Supabase Auth - User authentication

Backend (apps/backend/)

• FastAPI - Python 3.8+ web framework with automatic OpenAPI documentation
• SQLAlchemy - Database ORM for MySQL integration
• Pydantic - Request/response validation and serialization
• MySQL Integration - Direct connection to LuminariMUD's existing spatial tables
• JWT Authentication - Secure API access (configurable)
• Uvicorn - ASGI server for high-performance async operations

Shared (packages/shared/)

• TypeScript Interfaces - Shared types between frontend and backend
• Common Utilities - Shared helper functions

Development Tools

• Turborepo - Monorepo build orchestration
• npm Workspaces - Package management
• ESLint - Code linting across all packages
• TypeScript - Full-stack type safety

📁 Project Structure

See the Monorepo Structure section above for the high-level organization.

Key Directories

• apps/frontend/src/ - React application source

  • components/ - UI components (MapCanvas, ToolPalette, etc.)
  • hooks/ - Custom React hooks (useEditor, useAuth)
  • services/ - API client and external integrations
  • lib/ - Utility libraries (Supabase client)
  • types/ - TypeScript type imports from shared

• apps/backend/src/ - FastAPI Python backend source

  • routers/ - FastAPI endpoint definitions
  • schemas/ - Pydantic request/response schemas
  • models/ - SQLAlchemy database models
  • config/ - Database configuration and setup
  • main.py - FastAPI application entry point

• packages/shared/src/ - Shared code

  • types/ - TypeScript interfaces used by both frontend and backend

• docs/ - Comprehensive documentation (see Documentation section above)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up the development environment
• Coding standards and best practices
• Submitting pull requests
• Reporting issues

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Wiki

🙏 Acknowledgments

• LuminariMUD Team - For the amazing MUD system and wilderness architecture
• CircleMUD Community - For the foundational MUD codebase
• Open Source Contributors - For the tools and libraries that make this possible

🔗 Related Projects

• LuminariMUD - The main MUD codebase
• Wilderness System Documentation - Detailed system architecture

---

Made with ❤️ for the LuminariMUD community