MosswartMassacre/README.md

# MosswartMassacre - Advanced DECAL Plugin for Asheron's Call

> **Status**: Production Ready | VVS Direct Integration | Navigation Visualization Complete

A comprehensive DECAL plugin for Asheron's Call that tracks monster kills, rare item discoveries, and provides advanced navigation route visualization with 3D rendering.

## 🚀 Features

### Core Functionality
- **Kill Tracking**: Real-time monster kill counting with rate calculations (kills/5min, kills/hour)
- **Rare Item Discovery**: Automatic rare detection and counter with optional meta state control
- **Statistics Dashboard**: Detailed session statistics with best hourly performance tracking
- **Multi-System Integration**: WebSocket streaming, HTTP command server, and telemetry support

### 🗺️ Navigation Visualization
**Advanced VTank route visualization with 3D rendering capabilities**
- **3D Route Display**: Renders VTank .nav files as red lines in the game world
- **Route Comparison**: Side-by-side visualization with UtilityBelt's active navigation
- **Full Format Support**: All VTank nav types (Circular, Linear, Target, Once) and waypoint types
- **Auto-Discovery**: Automatically detects VTank installation and scans for .nav files
- **Performance Optimized**: Smart rendering limits and memory management

### 🎛️ User Interface
**Modern tabbed interface using direct VirindiViewService integration**
- **Main Tab**: Live kill stats, rare counts, elapsed time, and status indicators
- **Settings Tab**: Plugin configuration with real-time updates
- **Statistics Tab**: Enhanced analytics and session management
- **Navigation Tab**: Route selection, visualization controls, and status display

## 📥 Installation

### Prerequisites
- Windows with .NET Framework 4.8
- Asheron's Call with DECAL Adapter installed
- VirindiViewService (included in lib/ folder)

### Quick Setup
1. Download the latest release from the releases page
2. Extract to your DECAL plugins directory
3. Restart DECAL and enable the plugin
4. Configure settings through the in-game UI

### Building from Source
```bash
# Clone the repository
git clone [repository-url]
cd MosswartMassacre

# Restore packages and build
nuget restore packages.config
msbuild MosswartMassacre.csproj /p:Configuration=Release /p:Platform=AnyCPU
```

## 🎮 Usage

### Basic Commands
Access all features through the `/mm` command interface:

```
/mm help             - Show available commands
/mm report           - Display current kill statistics  
/mm loc              - Show current map coordinates
/mm reset            - Reset kill counters and timers
/mm meta             - Toggle automatic rare meta state
/mm http <on/off>    - Control HTTP command server (port 8085)
/mm telemetry <on/off> - Control telemetry streaming
```

### Navigation Visualization
1. **Enable**: Check "Enable Navigation Visualization" in Navigation tab
2. **Configure**: Set VTank profiles path in Settings (auto-detected)
3. **Select Route**: Choose from dropdown and click "Load Route"
4. **View**: Red route lines appear in 3D game world

### Configuration
Settings are stored per-character in YAML format at `<PluginDir>/<CharacterName>.yaml`:

```yaml
rare_meta_enabled: true
remote_commands_enabled: false
http_server_enabled: false
websocket_enabled: true
telemetry_enabled: false
char_tag: "default"
vtank_profiles_path: "C:\\Games\\VirindiPlugins\\VirindiTank\\"
main_window_x: 100
main_window_y: 100
```

## 🏗️ Architecture

### Core Components
- **PluginCore.cs**: Main entry point and event coordination
- **PluginSettings.cs**: YAML-based per-character configuration
- **Views/VVSTabbedMainView.cs**: Main tabbed UI with direct VVS integration  
- **Views/VVSBaseView.cs**: Base class for VVS-based views

### Navigation System
- **NavRoute.cs**: VTank .nav file parser and 3D renderer
- **NavVisualization.cs**: Route management and file discovery
- **Registry Integration**: Automatic VTank directory detection

### Communication Systems
- **WebSocket.cs**: Real-time data streaming to external services
- **HttpCommandServer.cs**: Local HTTP API for remote control
- **Telemetry.cs**: Periodic statistics reporting

### Game Integration
- **VtankControl.cs**: vTank automation interface
- **MossyInventory.cs**: Inventory monitoring and rare detection
- **Utils.cs**: Game coordinate systems and utility functions

## 🔧 Technical Details

### Dependencies
- **DECAL Framework**: Core plugin system (Decal.Adapter, Decal.Interop.Core, Decal.Interop.D3DService)
- **VirindiViewService**: UI framework for game overlays
- **Newtonsoft.Json**: JSON serialization for APIs
- **YamlDotNet**: Configuration file management

### Build Configuration
- **Target**: .NET Framework 4.8, x86 platform
- **Architecture**: Direct VVS integration (no wrapper abstraction)
- **Features**: Unsafe blocks enabled for P/Invoke operations

### Navigation File Format Support
**Complete VTank .nav format compatibility:**
- **Nav Types**: Circular (1), Linear (0/2), Target (3), Once (4)
- **Waypoint Types**: Point, Portal, Recall, Pause, ChatCommand, OpenVendor, Portal2, UseNPC, Checkpoint, Jump
- **Performance**: Optimized for routes up to 10,000 waypoints with 500-segment rendering limit

## 🔌 API Integration

### HTTP Command Server
```bash
# Enable server
curl -X POST http://localhost:8085/ -d "target=PlayerName&command=report"

# Available endpoints
POST /    - Execute command for target player
```

### WebSocket Streaming
Real-time data streaming to `wss://overlord.snakedesert.se/websocket/` including:
- Monster spawn/despawn events
- Chat messages and rare discoveries  
- Player position and statistics
- Session-based authentication with SharedSecret

### Telemetry Data
Periodic JSON snapshots posted to configurable endpoints:
```json
{
  "timestamp": "2024-12-19T10:30:00Z",
  "character": "PlayerName",
  "position": {"x": 59.2, "y": -28.7, "z": 0.05},
  "stats": {"kills": 150, "rares": 3, "session_time": "02:15:30"}
}
```

## 🛠️ Development

### Project Structure
```
MosswartMassacre/
├── Views/                    # VVS-based UI components
│   ├── VVSBaseView.cs       # Base view foundation  
│   └── VVSTabbedMainView.cs # Main tabbed interface
├── ViewXML/                 # UI layout definitions
│   └── mainViewTabbed.xml   # Current layout
├── NavRoute.cs              # Navigation file parser
├── NavVisualization.cs      # Route visualization manager
├── PluginCore.cs           # Main plugin logic
├── PluginSettings.cs       # Configuration management
└── lib/                    # External dependencies
```

### Development Environment
- **IDE**: Visual Studio 2017+ or VS Code with C# extension
- **Tools**: MSBuild, NuGet Package Manager
- **Testing**: In-game with Asheron's Call client and DECAL

### Contributing
1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📚 Related Documentation

- **CLAUDE.md**: Claude AI development guidance and build commands
- **Development History**: Successful VVS migration completed, wrapper system removed
- **Architecture Evolution**: Migrated from wrapper-based to direct VVS integration

## 📄 License

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

## 🎯 Roadmap

### Completed ✅
- [x] VVS Direct Integration Migration
- [x] Navigation Visualization System
- [x] Tabbed UI Interface
- [x] WebSocket Streaming
- [x] HTTP Command API
- [x] Telemetry System
- [x] Architecture Cleanup (Phase 3)

### Future Enhancements
- [ ] Multiple route visualization
- [ ] Route analysis and optimization tools
- [ ] Enhanced UI controls and themes
- [ ] Plugin integration marketplace
- [ ] Advanced statistics and reporting

---

*Built with ❤️ for the Asheron's Call community*