Add README.md for Turtle Control Center project documentation
This commit is contained in:
MayaTheShy
334
README.md
Normal file
334
README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 🐢 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!
|
||||
Reference in New Issue
Block a user