667 lines
17 KiB
Markdown
667 lines
17 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
|
|
|
|
- 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
|
|
|
|
1. **Clone or download this project**
|
|
|
|
2. **Install Server Dependencies**
|
|
```bash
|
|
cd server
|
|
npm install
|
|
```
|
|
|
|
3. **Install Client Dependencies**
|
|
```bash
|
|
cd client
|
|
npm install
|
|
```
|
|
|
|
4. **Start the Backend Server**
|
|
```bash
|
|
cd server
|
|
npm start
|
|
```
|
|
Server will run on:
|
|
- HTTP: http://localhost:3001
|
|
- WebSocket: ws://localhost:3002
|
|
|
|
5. **Start the React Frontend**
|
|
```bash
|
|
cd client
|
|
npm run dev
|
|
```
|
|
Frontend will open at: http://localhost:3000
|
|
|
|
6. **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`
|
|
|
|
7. **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
|
|
|
|
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 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)
|
|
|
|
```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**: 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
|
|
```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 that webbridge.lua is running
|
|
2. Verify SERVER_URL is correct
|
|
3. Check turtle.lua is running with wireless modem equipped
|
|
4. Verify all scripts are using same channel numbers
|
|
|
|
### Connection issues
|
|
|
|
1. Check server is running: `http://localhost:3001/api/turtles`
|
|
2. Check firewall settings
|
|
3. Verify ports 3001 and 3002 are not in use
|
|
4. Check browser console for WebSocket errors
|
|
|
|
### GPS not working
|
|
|
|
1. Set up GPS hosts in Minecraft (requires 4 computers)
|
|
2. Position them in a square pattern at high Y level
|
|
3. Each must run `gps host X Y Z` with their coordinates
|
|
|
|
## 🎨 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 10+ tables)
|
|
- [x] Path recording backend (API complete)
|
|
- [x] Task queue system backend (API complete)
|
|
- [x] Mining area management backend (API complete)
|
|
- [x] Mining statistics tracking (per turtle, per block type)
|
|
- [x] Turtle groups/teams coordination
|
|
- [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
|
|
|
|
### 🚧 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!
|