From dc6a9a94b7d8e2cbbfeb009360f6b024e0a1afbb Mon Sep 17 00:00:00 2001 From: MayaTheShy Date: Sun, 15 Feb 2026 23:49:36 -0500 Subject: [PATCH] Add README.md for Turtle Control Center project documentation --- README.md | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c480d99 --- /dev/null +++ b/README.md @@ -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. + +![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 + + ``` + +### 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!