remoteturtle/README.md

🐢 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

   cd server
   npm install
   

3. Install Client Dependencies

   cd client
   npm install
   

4. Start the Backend Server

   cd server
   npm start
   

   Server will run on:

   • HTTP: http://localhost:3001
   • WebSocket: ws://localhost:3002

5. Start the React Frontend

   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)

const PORT = 3001;        // HTTP server port
const WS_PORT = 3002;     // WebSocket port

Client Configuration (client/src/store/turtleStore.js)

const WS_URL = 'ws://localhost:3002';
const API_URL = 'http://localhost:3001';

Minecraft Bridge (webbridge.lua)

local SERVER_URL = "http://localhost:3001"
local CHANNEL_RECEIVE = 101
local STATUS_CHANNEL = 102

Turtle Configuration (turtle.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:

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

{
  "type": "initial_state",
  "turtles": [...]
}

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

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

From Client:

{
  "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:

   commands.myCommand = function(param)
       -- Your code here
       return true, "Success message"
   end
   

2. Add button in ControlPanel.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 - UI framework
• Three.js - 3D graphics
• React Three Fiber - React renderer for Three.js
• Zustand - State management
• Express - Backend server
• 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!