# 🐢 Turtle Control Center - Advanced Web Panel A comprehensive full-stack web application for monitoring and controlling ComputerCraft turtles in Minecraft. Features real-time 3D visualization, voice commands, intelligent navigation, mining statistics, team coordination, and persistent database storage. ![Turtle Control Center](https://img.shields.io/badge/Minecraft-ComputerCraft-green) ![Node.js](https://img.shields.io/badge/Node.js-18+-blue) ![React](https://img.shields.io/badge/React-18-61DAFB) ![Three.js](https://img.shields.io/badge/Three.js-3D-black) ![SQLite](https://img.shields.io/badge/SQLite-Database-003B57) ## ✨ Features ### Core Features - **🗺️ Real-time 3D Map**: Visualize turtle positions and movements with Three.js - **🎮 Control Panel**: Monitor and control multiple turtles simultaneously - **⚡ WebSocket Communication**: Instant bidirectional updates - **🔄 Auto-reconnect**: Robust connection handling with automatic recovery - **📊 Live Statistics**: Fuel, inventory, position, mining stats, and more - **🎯 Manual Control**: Direct movement and action controls - **🤖 Autonomous Intelligence**: Smart exploration with position memory and stuck detection ### Advanced Features - **🎤 Voice Commands**: Natural language control with Web Speech API (20+ commands) - **📦 Enhanced Inventory**: 4x4 grid display with item-specific emojis and counts - **📱 Mobile Responsive**: Optimized for desktop, tablet, and mobile devices - **💾 Database Persistence**: SQLite storage for homes, blocks, paths, tasks, and statistics - **📈 Mining Statistics**: Track blocks mined per turtle with leaderboards - **👥 Turtle Teams**: Organize turtles into groups with coordinated commands - **🗺️ Path Recording**: Record and replay turtle movement paths - **📋 Task Queue**: Schedule and coordinate multi-turtle tasks - **🏗️ Mining Areas**: Define and manage mining zones - **⏱️ Session Tracking**: Time-based analytics and performance metrics ## 🏗️ Architecture ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ React Web │◄────────┤ Node.js │◄────────│ ComputerCraft │ │ Interface │ WebSocket│ Bridge Server │ HTTP │ Bridge Script │ │ (Browser) │ │ (Express + WS) │ │ (webbridge.lua)│ └─────────────────┘ └──────────────────┘ └─────────────────┘ ▲ │ Modem ▼ ┌─────────────────┐ │ Mining Turtles │ │ (turtle.lua) │ └─────────────────┘ ``` ## 🚀 Quick Start ### Prerequisites - **Docker and Docker Compose** installed on your computer - **Minecraft** with ComputerCraft mod installed - At least one **turtle with a wireless modem** - A **computer in Minecraft** to run the bridge script ### Installation (Docker - Recommended) 1. **Clone or download this project** ```bash git clone cd remoteturtle ``` 2. **Start with Docker Compose** ```bash docker-compose up -d ``` This will automatically: - Build and start the backend server on port 3001 - Build and start the frontend on port 3000 - Create a persistent SQLite database volume - Set up networking between containers 3. **Access the Web Interface** - Frontend: http://localhost:3000 - Backend API: http://localhost:3001 - WebSocket: ws://localhost:3002 4. **Set up Minecraft Bridge Computer** In Minecraft, place a computer with a wireless modem and run: ```lua wget https://git.spatulaa.com/MayaTheShy/remoteturtle/raw/branch/master/startup_webbridge.lua startup reboot ``` This installs an auto-update system that: - Downloads the latest `webbridge.lua` on boot - Falls back to cached version if download fails - Automatically connects to your server Or manually: - Copy `webbridge.lua` to the computer - Edit the `SERVER_URL` to point to your Docker host - If Minecraft is on the same machine: `http://host.docker.internal:3001` - If on different machine: `http://:3001` - Run: `webbridge` 5. **Deploy Auto-Updating Turtles** On each turtle with a wireless modem, run: ```lua wget https://git.spatulaa.com/MayaTheShy/remoteturtle/raw/branch/master/startup_turtle.lua startup reboot ``` This installs an auto-update system that: - Downloads the latest `turtle.lua` on boot - Falls back to cached version if download fails - Keeps turtles updated automatically 6. **Optional: Deploy Pocket Computer Control** For wireless pocket computer control: ```lua wget https://git.spatulaa.com/MayaTheShy/remoteturtle/raw/branch/master/startup_pocket.lua startup reboot ``` This provides a wireless control interface for managing turtles from anywhere in-game ### Docker Commands ```bash # Start services docker-compose up -d # View logs docker-compose logs -f # Stop services docker-compose down # Rebuild after code changes docker-compose up -d --build # Stop and remove volumes (resets database) docker-compose down -v ``` ### Alternative: Manual Installation (Without Docker) If you prefer not to use Docker: 1. **Install Dependencies** ```bash cd server && npm install cd ../client && npm install ``` 2. **Start Backend** ```bash cd server && npm start ``` 3. **Start Frontend** ```bash cd client && npm run dev ``` 4. Follow steps 4-6 from the Docker installation above ## 📁 Project Structure ``` remoteturtle/ ├── server/ # Node.js backend (650+ lines) │ ├── server.js # Express REST API + WebSocket server │ ├── database.js # SQLite database layer (450+ lines) │ ├── turtle_control.db # SQLite database file │ ├── package.json │ └── node_modules/ │ ├── client/ # React frontend (1,500+ lines) │ ├── src/ │ │ ├── components/ │ │ │ ├── Map3D.jsx # Three.js 3D visualization │ │ │ ├── ControlPanel.jsx # Main control interface │ │ │ ├── ControlPanel.css # Control panel styles │ │ │ ├── VoiceControl.jsx # Voice command interface (NEW) │ │ │ └── VoiceControl.css # Voice control styles (NEW) │ │ ├── store/ │ │ │ └── turtleStore.js # Zustand state management │ │ ├── App.jsx # Main application component │ │ ├── App.css # Global styles + responsive design │ │ ├── main.jsx # React entry point │ │ └── index.css # Base styles │ ├── index.html │ ├── vite.config.js # Vite configuration │ ├── package.json │ └── node_modules/ │ ├── webbridge.lua # ComputerCraft HTTP bridge (200+ lines) ├── turtle.lua # Intelligent turtle controller (400+ lines) ├── pocketremote.lua # Pocket computer interface (150+ lines) ├── FEATURES.md # Feature documentation └── README.md # This file ``` ### Key Files Overview **Backend:** - `server/server.js` - 35+ REST API endpoints, WebSocket server - `server/database.js` - Database abstraction with 10 tables **Frontend:** - `client/src/App.jsx` - Layout and routing - `client/src/components/Map3D.jsx` - 3D turtle visualization - `client/src/components/ControlPanel.jsx` - Main control UI - `client/src/components/VoiceControl.jsx` - Voice commands - `client/src/store/turtleStore.js` - Global state management **ComputerCraft:** - `webbridge.lua` - Bridge between Minecraft and web server - `turtle.lua` - Autonomous turtle with intelligent navigation - `pocketremote.lua` - Mobile control from pocket computers ## 🎮 Usage ### Web Interface The interface features a **multi-panel tabbed design** for comprehensive turtle management: #### 🎮 Control Panel - View all connected turtles - Manual movement controls (forward, back, up, down, turn) - Autonomous commands (explore, mine, return home) - Real-time inventory display (4x4 grid with emojis) - GPS position and fuel monitoring #### 🎤 Voice Commands - Speak naturally to control turtles - 20+ recognized commands - Real-time transcript display - Speech confirmation feedback - Command help reference #### 📊 Statistics Dashboard - Mining statistics per turtle - Block type breakdown with emojis - Top miners leaderboard (🥇🥈🥉) - Time filters (24h, 7d, 30d, All) - Total blocks mined tracking #### 👥 Groups Management - Create turtle teams with custom colors - 8 color presets available - Add/remove turtles from groups - Send commands to entire team - Member status tracking #### 📋 Task Queue - Create tasks with 6 types - Priority system (1-10) - Coordinate input for area tasks - Filter by status - Assign to specific turtles - Task lifecycle management ### View Modes 1. **View Modes**: - **Split View**: See both map and control panel - **Map Only**: Full-screen 3D map - **Control Only**: Full-screen control panel 2. **Controlling Turtles**: - Click on a turtle card or 3D marker to select it - Use command buttons for autonomous actions: - 🔍 **Explore**: Start autonomous mining/exploration - ⛏️ **Mine**: Begin mining operation - 🏠 **Return Home**: Navigate back to home position - ⏹️ **Stop**: Stop current operation 3. **Manual Control**: - Use arrow buttons for directional movement - ⬆ Up / ⬇ Down for vertical movement - ← Left / → Right for turning ### In-Game Commands **Turtle Commands** (via pocket computer, web, or voice): **Movement:** - `forward/back/up/down` - Directional movement - `turnLeft/turnRight` - Rotation **Actions:** - `dig/digUp/digDown` - Mining operations - `place/placeUp/placeDown` - Block placement - `refuel` - Consume fuel items **Autonomous Operations:** - `explore` - Intelligent exploration with position memory - 75% horizontal movement preference - 15% downward, 10% upward movement - Visited position tracking to avoid loops - Stuck detection with recovery - `mine` - Autonomous mining mode - `returnHome` - Navigate back to home (non-blocking) - `stop` - Stop current operation - `setHome` - Set current position as home - `status` - Report current state ### Intelligent Navigation Features The turtle.lua script includes advanced navigation: 1. **Position Memory**: Tracks last 50 positions to avoid revisiting 2. **Visited Position Tracking**: Maintains history to prevent loops 3. **Stuck Detection**: Identifies when turtle can't move and tries alternatives 4. **Smart Direction Selection**: - Prefers horizontal movement (75%) - Controlled descent (15%) - Minimal upward movement (10%) 5. **Turn Limiting**: Max 3 turn attempts to prevent endless spinning 6. **Non-blocking Return Home**: Can return home without timing out 7. **Fuel Management**: Auto-refuels when fuel is low 8. **GPS Integration**: Uses GPS for accurate positioning ## 🔧 Configuration ### Server Configuration (server/server.js) ```javascript const PORT = 3001; // HTTP server port const WS_PORT = 3002; // WebSocket port ``` ### Client Configuration (client/src/store/turtleStore.js) ```javascript const WS_URL = 'ws://localhost:3002'; const API_URL = 'http://localhost:3001'; ``` ### Minecraft Bridge (webbridge.lua) ```lua local SERVER_URL = "http://localhost:3001" local CHANNEL_RECEIVE = 101 local STATUS_CHANNEL = 102 ``` ### Turtle Configuration (turtle.lua) ```lua local CHANNEL_RECEIVE = 100 local CHANNEL_SEND = 101 local STATUS_CHANNEL = 102 ``` ## 🌐 Remote Access To access from other devices on your network: 1. Find your computer's local IP address: ```bash # Linux/Mac ifconfig | grep "inet " # Windows ipconfig ``` 2. Update configurations to use your IP instead of `localhost`: - In `webbridge.lua`: `local SERVER_URL = "http://192.168.1.100:3001"` - In `turtleStore.js`: Update WS_URL and API_URL 3. Ensure firewall allows connections on ports 3000, 3001, and 3002 ## 📊 Project Statistics - **Total Code**: 5,600+ lines - **Database Tables**: 11 - **API Endpoints**: 35+ - **Supported Commands**: 25+ - **Voice Commands**: 20+ - **Frontend Components**: 12+ - **Task Types**: 6 - **Color Presets**: 8 ## 📊 API Reference ### Turtle Management #### `POST /api/turtle/update` Update turtle status ```json { "turtleID": 123, "name": "Miner-1", "x": 100, "y": 64, "z": 200, "facing": 0, "fuel": 5000, "mode": "exploring", "inventory": [...] } ``` #### `GET /api/turtles` Get all connected turtles #### `GET /api/turtle/:id` Get specific turtle details #### `POST /api/turtle/:id/command` Send command to turtle ```json { "command": "explore", "param": null } ``` #### `GET /api/turtle/:id/commands` Get pending commands for turtle ### Home Management #### `POST /api/homes` Set turtle home position ```json { "turtleID": 123, "x": 100, "y": 64, "z": 200 } ``` #### `GET /api/homes/:turtleId` Get turtle's home position ### Block Tracking #### `POST /api/blocks` Record discovered block ```json { "x": 100, "y": 64, "z": 200, "blockType": "minecraft:diamond_ore", "discoveredBy": 123 } ``` #### `GET /api/blocks` Get all discovered blocks (with filtering) - Query params: `minX`, `maxX`, `minY`, `maxY`, `minZ`, `maxZ` ### Path Recording #### `POST /api/paths` Create new path recording ```json { "name": "Mine Route 1", "turtleId": 123, "description": "Efficient mining path" } ``` #### `GET /api/paths` Get all recorded paths #### `GET /api/paths/:pathId` Get specific path with waypoints #### `POST /api/paths/:pathId/waypoints` Add waypoint to path ```json { "x": 100, "y": 64, "z": 200, "action": "dig_forward" } ``` #### `DELETE /api/paths/:pathId` Delete path ### Task Queue #### `POST /api/tasks` Create new task ```json { "taskType": "mine_area", "priority": 1, "assignedTurtleId": 123, "parameters": { "x1": 100, "y1": 60, "z1": 200, "x2": 120, "y2": 70, "z2": 220 } } ``` #### `GET /api/tasks` Get all tasks (with optional status filter) - Query params: `status=pending|in_progress|completed|failed` #### `GET /api/tasks/:taskId` Get specific task details #### `PUT /api/tasks/:taskId` Update task status ```json { "status": "completed", "result": "Mined 450 blocks" } ``` #### `DELETE /api/tasks/:taskId` Delete task ### Mining Areas #### `POST /api/mining-areas` Define mining area ```json { "name": "Diamond Layer", "x1": 100, "y1": -64, "z1": 200, "x2": 200, "y2": -50, "z2": 300, "priority": 1, "assignedTurtles": [123, 456] } ``` #### `GET /api/mining-areas` Get all mining areas #### `GET /api/mining-areas/:areaId` Get specific mining area #### `PUT /api/mining-areas/:areaId` Update mining area #### `DELETE /api/mining-areas/:areaId` Delete mining area ### Mining Statistics #### `POST /api/stats/block-mined` Record block mined ```json { "turtleId": 123, "blockType": "minecraft:diamond_ore" } ``` #### `GET /api/stats/mining/:turtleId?` Get mining statistics - Query params: `days=7` (filter by recent days) - Returns per-block-type counts #### `GET /api/stats/top-miners` Get leaderboard of top mining turtles - Query params: `limit=10` ### Turtle Groups/Teams #### `POST /api/groups` Create turtle group ```json { "groupName": "Mining Team Alpha", "color": "#3b82f6" } ``` #### `GET /api/groups` Get all groups with member counts #### `DELETE /api/groups/:groupId` Delete group #### `POST /api/groups/:groupId/members` Add turtle to group ```json { "turtleId": 123 } ``` #### `DELETE /api/groups/:groupId/members/:turtleId` Remove turtle from group #### `GET /api/turtles/:turtleId/groups` Get turtle's groups #### `POST /api/groups/:groupId/command` Send command to all turtles in group ```json { "command": "returnHome" } ``` ### WebSocket Messages **From Server to Client:** ```json { "type": "initial_state", "turtles": [...] } ``` ```json { "type": "turtle_update", "turtle": {...} } ``` ```json { "type": "turtle_disconnected", "turtleID": 123 } ``` ```json { "type": "block_discovered", "block": {...} } ``` ```json { "type": "task_update", "task": {...} } ``` **From Client to Server:** ```json { "type": "command", "turtleID": 123, "command": "explore", "param": null } ``` ## 🎤 Voice Commands The system supports natural language voice commands using the Web Speech API (Chrome, Edge, Safari): ### Movement Commands - "forward" / "move forward" / "go forward" - "back" / "backward" / "move back" - "turn left" / "left" - "turn right" / "right" - "up" / "move up" / "go up" - "down" / "move down" / "go down" ### Action Commands - "dig" / "mine" - "dig up" / "mine up" - "dig down" / "mine down" - "place" / "place block" - "refuel" ### Autonomous Commands - "explore" / "start exploring" - "mine" / "start mining" - "return home" / "go home" / "come back" - "stop" / "halt" - "set home" / "mark home" - "status" / "report" ## 💾 Database Schema ### Tables 1. **turtle_homes** - Home positions for turtles 2. **turtle_config** - Turtle configuration settings 3. **world_blocks** - Discovered block locations 4. **turtle_paths** - Recorded movement paths 5. **path_waypoints** - Individual waypoints in paths 6. **task_queue** - Task scheduling and coordination 7. **mining_areas** - Defined mining zones 8. **mining_stats** - Block mining statistics per turtle 9. **turtle_groups** - Turtle team/group definitions 10. **turtle_group_members** - Group membership 11. **turtle_sessions** - Time-based analytics tracking ## 📱 Frontend Features ### Enhanced Inventory Display - 4x4 grid matching Minecraft turtle slots - Item-specific emojis (💎 diamond, ⚫ coal, 🟡 gold, etc.) - Item count badges - Empty slot indicators - Hover tooltips with full item names ### Mobile Responsive Design - **Desktop (>1024px)**: Side-by-side map and controls - **Tablet (768-1024px)**: Vertical stacking - **Mobile (<768px)**: Tab-based navigation, optimized touch targets - Touch-optimized controls (48px minimum) - Landscape orientation support - Accessibility features (reduced motion, high contrast) ## 🐛 Troubleshooting ### Turtles not appearing in web panel 1. **Check webbridge is running** - Verify webbridge.lua is active in Minecraft - Check for error messages in the Minecraft console 2. **Verify SERVER_URL configuration** - Ensure webbridge.lua points to correct server address - Use `http://localhost:3001` for local testing - Use your machine's IP for remote access 3. **Check turtle setup** - Ensure turtle.lua is running - Verify wireless modem is equipped - Check modem is on correct side (usually top) 4. **Verify channel configuration** - All scripts must use matching channel numbers - Default: RECEIVE=100, SEND=101, STATUS=102 ### Connection issues 1. **Server not responding** - Check server is running: `http://localhost:3001/api/turtles` - Verify no port conflicts (3001, 3002, 3000) - Check firewall isn't blocking connections 2. **WebSocket disconnections** - Check browser console for WebSocket errors - Verify WS_PORT (3002) is accessible - Try restarting both client and server 3. **Database errors** - Check `server/turtle_control.db` file exists - Ensure write permissions on database file - Try deleting database to reinitialize (loses data) ### Turtle behavior issues 1. **Turtle gets stuck or spins endlessly** - Check fuel level (need sufficient fuel) - Verify GPS is working (`gps locate` in-game) - Restart turtle.lua to reset state 2. **Turtle not finding home** - Ensure home position is set (`setHome` command) - Check GPS hosts are functioning - Verify turtle has enough fuel to return 3. **Turtle timing out** - Fixed in latest version with non-blocking return home - Ensure latest turtle.lua is deployed - Check modem range (max 64 blocks without ender modem) ### Voice commands not working 1. **Browser compatibility** - Use Chrome, Edge, or Safari (Firefox not supported) - Check microphone permissions in browser settings - Try HTTPS instead of HTTP (some browsers require it) 2. **Microphone issues** - Verify microphone is connected and working - Check system permissions allow browser mic access - Test with "Hello Google" or other voice apps 3. **Commands not recognized** - Speak clearly and at normal pace - Use exact command phrases from the help menu - Check browser console for recognition errors ### GPS not working 1. **Set up GPS hosts** - Requires 4 computers in Minecraft - Position in square pattern at high Y level (Y>100 recommended) - Each runs: `gps host X Y Z` with their exact coordinates 2. **GPS host placement** ``` Host positions (example): Computer 1: gps host 100 120 100 Computer 2: gps host 200 120 100 Computer 3: gps host 100 120 200 Computer 4: gps host 200 120 200 ``` 3. **Troubleshooting GPS** - Ensure all 4 hosts are loaded (chunk loaders) - Keep them at least 6 blocks apart - Must be on same dimension as turtles ### Performance issues 1. **Slow web interface** - Reduce number of visible turtles in 3D map - Disable block tracking if not needed - Use production build: `npm run build` 2. **High database size** - Periodically clean old session data - Archive old paths and tasks - Consider vacuum command: `VACUUM;` 3. **Memory issues in Minecraft** - Limit number of active turtles - Reduce position memory size in turtle.lua - Use more efficient exploration patterns ## 🎨 Customization ### Adding New Commands 1. **Add to turtle.lua**: ```lua commands.myCommand = function(param) -- Your code here return true, "Success message" end ``` 2. **Add button in ControlPanel.jsx**: ```jsx ``` ### Styling - Modify `client/src/components/ControlPanel.css` for panel styling - Modify `client/src/App.css` for layout changes - Colors use Tailwind-inspired palette ## 📝 License MIT License - Feel free to use and modify! ## 🙏 Credits Built with: - [React](https://react.dev/) - UI framework - [Three.js](https://threejs.org/) - 3D graphics - [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) - React renderer for Three.js - [Zustand](https://zustand-demo.pmnd.rs/) - State management - [Express](https://expressjs.com/) - Backend server - [ws](https://github.com/websockets/ws) - WebSocket server ## 🚀 Implementation Status ### ✅ Completed Features - [x] Real-time 3D visualization with Three.js - [x] WebSocket bidirectional communication - [x] Manual turtle control interface - [x] Autonomous exploration with intelligent navigation - [x] Database persistence (SQLite with 11 tables) - [x] Path recording backend (API complete) - [x] Task queue system (backend + frontend complete) - [x] Mining area management backend (API complete) - [x] Mining statistics tracking (backend + frontend complete) - [x] Turtle groups/teams coordination (backend + frontend complete) - [x] Voice command interface (Web Speech API, 20+ commands) - [x] Enhanced inventory display (4x4 grid with emojis) - [x] Mobile-responsive design (desktop/tablet/mobile) - [x] Position memory and visited tracking - [x] Stuck detection and recovery - [x] Session-based analytics - [x] Multi-panel tabbed interface (Control, Voice, Stats, Groups, Tasks) ### 🚧 Frontend Pending (Backend Complete) - [ ] Path recording UI (playback controls, visualization) - [ ] Mining area visualization (3D overlays on map) ### 📋 Future Enhancements - [ ] User authentication system - [ ] Multi-user support with permissions - [ ] Real-time collaboration features - [ ] Advanced pathfinding algorithms (A*) - [ ] Quarry mode with automatic area mining - [ ] Ore detection and priority mining - [ ] Automated smelting coordination - [ ] Chest management and auto-storage - [ ] Fuel depot system - [ ] Emergency recovery protocols ## 💡 Tips - Keep the web bridge computer loaded (use a chunk loader) - Monitor turtle fuel levels regularly - Set home position before starting exploration - Use GPS for accurate positioning - Keep backup fuel in turtle inventories --- **Need help?** Check the troubleshooting section or review the code comments! **Have ideas?** Feel free to fork and extend this project!