# 🐢 Turtle Control Center - Web Panel

A full-stack web application for monitoring and controlling ComputerCraft turtles in Minecraft. Features a real-time 3D map, WebSocket communication, and an intuitive control panel.

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

## 📋 Features

- **🗺️ Real-time 3D Map**: Visualize turtle positions and movements in a beautiful 3D environment
- **🎮 Control Panel**: Monitor and control multiple turtles simultaneously
- **⚡ WebSocket Communication**: Instant updates and commands
- **🔄 Auto-reconnect**: Handles connection drops gracefully
- **📊 Live Statistics**: Track fuel, inventory, position, and more
- **🎯 Manual Control**: Direct control with arrow keys
- **🤖 Autonomous Modes**: Explore, mine, and return home automatically

## 🏗️ 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

## 📊 API Reference

### REST Endpoints

**POST /api/turtle/update**
- Body: Turtle status object
- Updates turtle state

**GET /api/turtle/:id/commands**
- Returns pending commands for turtle

**POST /api/turtle/:id/command**
- Body: `{ command: string, param: any }`
- Queues command for turtle

**GET /api/turtles**
- Returns all connected turtles

### WebSocket Messages

**From Server:**
```json
{
  "type": "initial_state",
  "turtles": [...]
}

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

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

**From Client:**
```json
{
  "type": "command",
  "turtleID": 123,
  "command": "explore",
  "param": null
}
```

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

## 🚀 Future Enhancements

- [ ] Path recording and playback
- [ ] Multi-turtle task coordination
- [ ] Inventory management interface
- [ ] Mining area visualization
- [ ] Task scheduling
- [ ] Database persistence
- [ ] Authentication/multi-user support
- [ ] Mobile-responsive design

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