917 lines
25 KiB
Markdown
917 lines
25 KiB
Markdown
# 🐢 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**
|
|
```bash
|
|
git clone <repository-url>
|
|
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://<your-ip>: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
|
|
<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](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!
|