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

Node.js 18+ 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

Clone or download this project
Install Server Dependencies
```
cd server
npm install
```
Install Client Dependencies
```
cd client
npm install
```
Start the Backend Server
```
cd server
npm start
```
Server will run on:
- HTTP: http://localhost:3001
- WebSocket: ws://localhost:3002
Start the React Frontend
```
cd client
npm run dev
```
Frontend will open at: http://localhost:3000
Set up Minecraft Bridge
- In Minecraft, place a computer with a wireless modem
- Copy webbridge.lua to the computer
- Edit the SERVER_URL in webbridge.lua to point to your server (If running locally, use http://localhost:3001)
- Run: webbridge
Deploy Turtles
- Copy turtle.lua to your turtles
- Equip wireless modems on turtles
- Run: turtle

📁 Project Structure

remoteturtle/
├── server/                 # Node.js backend
│   ├── server.js          # Express + WebSocket server
│   └── package.json
├── client/                # React frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── Map3D.jsx        # 3D map visualization
│   │   │   ├── ControlPanel.jsx # Control interface
│   │   │   └── ControlPanel.css
│   │   ├── store/
│   │   │   └── turtleStore.js   # Zustand state management
│   │   ├── App.jsx
│   │   ├── App.css
│   │   ├── main.jsx
│   │   └── index.css
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
├── webbridge.lua          # ComputerCraft bridge script
├── turtle.lua             # Advanced turtle control script
├── pocketremote.lua       # Pocket computer interface
└── README.md

🎮 Usage

Web Interface

View Modes:
- Split View: See both map and control panel
- Map Only: Full-screen 3D map
- Control Only: Full-screen control panel
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
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 or web):

explore - Start exploration mode
returnHome - Return to home position
stop - Stop current operation
forward/back/up/down - Movement
turnLeft/turnRight - Rotation
dig/digUp/digDown - Mining
setHome - Set current position as home

🔧 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:

Find your computer's local IP address:

# Linux/Mac
ifconfig | grep "inet "

# Windows
ipconfig

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
Ensure firewall allows connections on ports 3000, 3001, and 3002

📊 Project Statistics

Total Code: 3,500+ lines
Database Tables: 10
API Endpoints: 35+
Supported Commands: 25+
Voice Commands: 20+
Frontend Components: 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

turtle_homes - Home positions for turtles
turtle_config - Turtle configuration settings
world_blocks - Discovered block locations
turtle_paths - Recorded movement paths
path_waypoints - Individual waypoints in paths
task_queue - Task scheduling and coordination
mining_areas - Defined mining zones
mining_stats - Block mining statistics per turtle
turtle_groups - Turtle team/group definitions
turtle_group_members - Group membership
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

Check that webbridge.lua is running
Verify SERVER_URL is correct
Check turtle.lua is running with wireless modem equipped
Verify all scripts are using same channel numbers

Connection issues

Check server is running: http://localhost:3001/api/turtles
Check firewall settings
Verify ports 3001 and 3002 are not in use
Check browser console for WebSocket errors

GPS not working

Set up GPS hosts in Minecraft (requires 4 computers)
Position them in a square pattern at high Y level
Each must run gps host X Y Z with their coordinates

🎨 Customization

Adding New Commands

Add to turtle.lua:

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

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 10+ tables)
Path recording backend (API complete)
Task queue system backend (API complete)
Mining area management backend (API complete)
Mining statistics tracking (per turtle, per block type)
Turtle groups/teams coordination
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

🚧 In Progress / Frontend Pending

Path recording UI (playback controls, visualization)
Task coordination UI (task creation, queue display)
Mining area visualization (3D overlays on map)
Statistics dashboard (charts, leaderboards)
Group management UI (create/manage teams)

📋 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!

Languages

JavaScript 72.1%

Lua 15.4%

CSS 11.6%

Batchfile 0.3%

Dockerfile 0.3%

Other 0.3%