remoteturtle/README.md

🐢 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.

✨ 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

   git clone <repository-url>
   cd remoteturtle
   

2. Start with Docker Compose

   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:

   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://<your-ip>:3001
   • Run: webbridge

5. Deploy Auto-Updating Turtles

   On each turtle with a wireless modem, run:

   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:

   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

# 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

   cd server && npm install
   cd ../client && npm install
   

2. Start Backend

   cd server && npm start
   

3. Start Frontend

   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)

const PORT = 3001;        // HTTP server port
const WS_PORT = 3002;     // WebSocket port

Client Configuration (client/src/store/turtleStore.js)

const WS_URL = 'ws://localhost:3002';
const API_URL = 'http://localhost:3001';

Minecraft Bridge (webbridge.lua)

local SERVER_URL = "http://localhost:3001"
local CHANNEL_RECEIVE = 101
local STATUS_CHANNEL = 102

Turtle Configuration (turtle.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:

   # 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

{
  "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

{
  "command": "explore",
  "param": null
}

GET /api/turtle/:id/commands

Get pending commands for turtle

Home Management

POST /api/homes

Set turtle home position

{
  "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

{
  "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

{
  "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

{
  "x": 100, "y": 64, "z": 200,
  "action": "dig_forward"
}

DELETE /api/paths/:pathId

Delete path

Task Queue

POST /api/tasks

Create new task

{
  "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

{
  "status": "completed",
  "result": "Mined 450 blocks"
}

DELETE /api/tasks/:taskId

Delete task

Mining Areas

POST /api/mining-areas

Define mining area

{
  "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

{
  "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

{
  "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

{
  "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

{
  "command": "returnHome"
}

WebSocket Messages

From Server to Client:

{
  "type": "initial_state",
  "turtles": [...]
}

{
  "type": "turtle_update",
  "turtle": {...}
}

{
  "type": "turtle_disconnected",
  "turtleID": 123
}

{
  "type": "block_discovered",
  "block": {...}
}

{
  "type": "task_update",
  "task": {...}
}

From Client to Server:

{
  "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:

   commands.myCommand = function(param)
       -- Your code here
       return true, "Success message"
   end
   

2. Add button in ControlPanel.jsx:

   <button onClick={() => sendCommand(turtle.turtleID, 'myCommand')}>
       My Command
   </button>
   

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 - UI framework
• Three.js - 3D graphics
• React Three Fiber - React renderer for Three.js
• Zustand - State management
• Express - Backend server
• ws - WebSocket server

🚀 Implementation Status

✅ Completed Features

• Real-time 3D visualization with Three.js
• WebSocket bidirectional communication
• Manual turtle control interface
• Autonomous exploration with intelligent navigation
• Database persistence (SQLite with 11 tables)
• Path recording backend (API complete)
• Task queue system (backend + frontend complete)
• Mining area management backend (API complete)
• Mining statistics tracking (backend + frontend complete)
• Turtle groups/teams coordination (backend + frontend complete)
• Voice command interface (Web Speech API, 20+ commands)
• Enhanced inventory display (4x4 grid with emojis)
• Mobile-responsive design (desktop/tablet/mobile)
• Position memory and visited tracking
• Stuck detection and recovery
• Session-based analytics
• 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!