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

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