335 lines
9.3 KiB
Markdown
335 lines
9.3 KiB
Markdown
# 🐢 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 📋 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!
|