diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..48fe469 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,291 @@ +# System Architecture Diagram + +## High-Level Overview + +``` + ╔═══════════════════════════╗ + ║ YOUR COMPUTER ║ + ║ ║ + ┌────────────────────║──────────────────────────║────────────────┐ + │ ║ ║ │ + │ ┏━━━━━━━━━━━━━━┓ ║ ┏━━━━━━━━━━━━━━━━━━━┓ ║ ┏━━━━━━━━━━┓ │ + │ ┃ Browser ┃ ║ ┃ Node.js Server ┃ ║ ┃ Minecraft┃ │ + │ ┃ ┃ ║ ┃ ┃ ║ ┃ ┃ │ + │ ┃ React App ┃◄─╫─►┃ Express + WS ┃◄─╫─►┃ Bridge ┃ │ + │ ┃ ┃ ║ ┃ ┃ ║ ┃ Computer ┃ │ + │ ┃ :3000 ┃ ║ ┃ :3001 / :3002 ┃ ║ ┃ ┃ │ + │ ┗━━━━━━━━━━━━━━┛ ║ ┗━━━━━━━━━━━━━━━━━━━┛ ║ ┗━━━━━━━━━━┛ │ + │ ║ ║ │ │ + └────────────────────║──────────────────────────║───────┼────────┘ + ╚═══════════════════════════╝ │ + │ Modem + │ Wireless + ↓ + ┏━━━━━━━━━━━━━━┓ + ┃ Turtle 1 ┃ + ┃ Turtle 2 ┃ + ┃ Turtle N ┃ + ┗━━━━━━━━━━━━━━┛ +``` + +## Communication Flow + +### Status Updates (Turtle → Web) + +``` +Turtle Bridge Server Web Client + │ │ │ │ + │ Status Broadcast │ │ │ + ├──────modem───────>│ │ │ + │ (channel 102) │ │ │ + │ │ HTTP POST │ │ + │ ├───────────────────>│ │ + │ │ /api/turtle/update│ │ + │ │ │ WebSocket Broadcast │ + │ │ ├─────────────────────>│ + │ │ │ turtle_update │ + │ │ │ │ + │ │ │ ┌───┴───┐ + │ │ │ │Update │ + │ │ │ │3D Map │ + │ │ │ └───────┘ +``` + +### Commands (Web → Turtle) + +``` +Web Client Server Bridge Turtle + │ │ │ │ + │ Click "Explore" │ │ │ + ├─────WebSocket────>│ │ │ + │ command msg │ │ │ + │ │ Queue Command │ │ + │ ├──(in memory) │ │ + │ │ │ │ + │ │ │ Poll for Commands │ + │ │ HTTP GET │ │ + │ │<──────────────────┤ │ + │ │/api/turtle/:id/.. │ │ + │ │ │ │ + │ │ Return Commands │ │ + │ ├──────────────────>│ │ + │ │ JSON │ │ + │ │ │ Forward via Modem │ + │ │ ├──────────────────>│ + │ │ │ (channel 100) │ + │ │ │ │ + │ │ │ ┌───┴────┐ + │ │ │ │Execute │ + │ │ │ │Command │ + │ │ │ └────────┘ +``` + +## Component Details + +### React Frontend (Port 3000) + +``` +┌─────────────────────────────────────┐ +│ App.jsx │ +│ ┌───────────────────────────────┐ │ +│ │ View Controls (Split/Map/..) │ │ +│ └───────────────────────────────┘ │ +│ │ +│ ┌────────────┬──────────────────┐ │ +│ │ │ │ │ +│ │ Control │ Map3D.jsx │ │ +│ │ Panel │ │ │ +│ │ .jsx │ ┌────────────┐ │ │ +│ │ │ │ Three.js │ │ │ +│ │ - Turtle │ │ Canvas │ │ │ +│ │ Cards │ │ │ │ │ +│ │ - Details │ │ - Turtles │ │ │ +│ │ - Commands│ │ - Grid │ │ │ +│ │ - Manual │ │ - Camera │ │ │ +│ │ Control │ │ │ │ │ +│ │ │ └────────────┘ │ │ +│ └────────────┴──────────────────┘ │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ turtleStore.js │ │ +│ │ - WebSocket connection │ │ +│ │ - State management │ │ +│ │ - Command sending │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### Node.js Server (Ports 3001, 3002) + +``` +┌─────────────────────────────────────┐ +│ server.js │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ Express HTTP Server │ │ +│ │ Port: 3001 │ │ +│ │ │ │ +│ │ POST /api/turtle/update │ │ +│ │ GET /api/turtle/:id/commands│ │ +│ │ POST /api/turtle/:id/command │ │ +│ │ GET /api/turtles │ │ +│ └───────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ WebSocket Server │ │ +│ │ Port: 3002 │ │ +│ │ │ │ +│ │ - Broadcast turtle updates │ │ +│ │ - Receive commands │ │ +│ │ - Track connected clients │ │ +│ └───────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ In-Memory Data Store │ │ +│ │ │ │ +│ │ turtleData Map: │ │ +│ │ turtleID → state │ │ +│ │ - position │ │ +│ │ - fuel │ │ +│ │ - inventory │ │ +│ │ - pendingCommands[] │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### Minecraft Components + +``` +┌─────────────────────────────────────┐ +│ webbridge.lua │ +│ (Bridge Computer) │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ Modem Listener │ │ +│ │ Channels: 101, 102 │ │ +│ └───────────────────────────────┘ │ +│ ↕ │ +│ ┌───────────────────────────────┐ │ +│ │ HTTP Client │ │ +│ │ - POST status to server │ │ +│ │ - GET commands from server │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ + ↕ (modem) +┌─────────────────────────────────────┐ +│ turtle.lua │ +│ (Each Turtle) │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ Command Processor │ │ +│ │ Listen: channel 100 │ │ +│ └───────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ Status Broadcaster │ │ +│ │ Send: channel 102 (every 5s) │ │ +│ └───────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ Autonomous AI │ │ +│ │ - Exploration │ │ +│ │ - Mining │ │ +│ │ - Pathfinding │ │ +│ │ - Fuel management │ │ +│ └───────────────────────────────┘ │ +└─────────────────────────────────────┘ +``` + +## Network Ports + +``` +Port 3000 → React Dev Server (Vite) +Port 3001 → Express HTTP API +Port 3002 → WebSocket Server + +Modem Channels: + 100 → Commands to Turtles + 101 → Responses from Turtles + 102 → Status Updates +``` + +## Data Models + +### Turtle State Object + +```javascript +{ + turtleID: 123, + mode: "mining", // idle, exploring, mining, returning, manual + position: { + x: 100, + y: 64, + z: 200 + }, + homePosition: { + x: 95, + y: 64, + z: 195 + }, + fuel: 5000, + inventory: [ + { slot: 1, name: "minecraft:coal_ore", count: 32 }, + { slot: 2, name: "minecraft:iron_ore", count: 16 } + ], + lastUpdate: 1234567890, + pendingCommands: [ + { command: "explore", param: null, timestamp: 1234567890 } + ] +} +``` + +### Command Message + +```javascript +{ + command: "explore", // explore, mine, returnHome, stop, forward, etc. + param: null, // optional parameter + target: 123 // turtle ID (for Lua) or turtleID (for web) +} +``` + +## Technology Stack Summary + +``` +┌─────────────────────────────────────┐ +│ Presentation Layer │ +│ - React 18 │ +│ - Three.js / React Three Fiber │ +│ - CSS3 │ +└─────────────────────────────────────┘ + ↕ +┌─────────────────────────────────────┐ +│ State Management │ +│ - Zustand │ +│ - WebSocket API │ +└─────────────────────────────────────┘ + ↕ +┌─────────────────────────────────────┐ +│ Backend Services │ +│ - Node.js │ +│ - Express.js │ +│ - ws (WebSocket library) │ +└─────────────────────────────────────┘ + ↕ +┌─────────────────────────────────────┐ +│ Game Integration │ +│ - ComputerCraft Lua │ +│ - HTTP API │ +│ - Modem Wireless │ +└─────────────────────────────────────┘ +``` + +--- + +This architecture provides: +- ✅ Real-time bidirectional communication +- ✅ Scalable to multiple turtles +- ✅ Web-based interface accessible from any device +- ✅ Backward compatible with existing Lua scripts +- ✅ Clean separation of concerns +- ✅ Easy to extend and modify diff --git a/START_HERE.md b/START_HERE.md new file mode 100644 index 0000000..a436bd2 --- /dev/null +++ b/START_HERE.md @@ -0,0 +1,347 @@ +# 🎉 Project Complete! + +## What You Now Have + +A **complete full-stack web application** for controlling ComputerCraft mining turtles in Minecraft! + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 🐢 TURTLE CONTROL CENTER │ +│ │ +│ ┌──────────────────┐ ┌─────────────────────────┐ │ +│ │ Turtle List │ │ Live 3D Map │ │ +│ │ ───────────── │ │ │ │ +│ │ │ │ 🏠 │ │ +│ │ 🐢 Turtle 1 │ │ \ │ │ +│ │ [Mining] │ │ \----🐢 Selected │ │ +│ │ Fuel: 5000 │ │ │ │ +│ │ Inventory: 8 │ │ │ │ +│ │ │ │ 🐢 │ │ +│ │ 🐢 Turtle 2 │ │ │ │ +│ │ [Exploring] │ │ Rotate • Zoom • Pan │ │ +│ │ Fuel: 3200 │ │ │ │ +│ │ Inventory: 3 │ └─────────────────────────┘ │ +│ │ │ │ +│ │ + Add More... │ ┌─────────────────────────┐ │ +│ └──────────────────┘ │ Turtle 1 Control │ │ +│ │ ───────────────────── │ │ +│ ✅ Real-time Updates │ [🔍Explore] [⛏️Mine] │ │ +│ ✅ WebSocket Connected │ [🏠Return] [⏹️Stop] │ │ +│ ✅ Auto-reconnect │ │ │ +│ │ Manual: ↑ ← → ↓ │ │ +│ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 📁 Complete File Structure + +``` +remoteturtle/ +│ +├── 📚 Documentation (7 files) +│ ├── README.md ⭐ Main documentation +│ ├── QUICKSTART.md 🚀 Fast setup guide +│ ├── PROJECT_SUMMARY.md 📊 What was built +│ ├── ARCHITECTURE.md 🏗️ System design +│ ├── INTERFACE.md 🎨 UI overview +│ ├── TROUBLESHOOTING.md 🔧 Problem solving +│ └── THIS_FILE.md ✅ You are here! +│ +├── 🎮 Setup Scripts (3 files) +│ ├── start.sh Linux/Mac launcher +│ ├── start.bat Windows launcher +│ └── package.json Root config +│ +├── 🖥️ Backend (server/) +│ ├── server.js Express + WebSocket server +│ └── package.json Node.js dependencies +│ +├── 🌐 Frontend (client/) +│ ├── index.html +│ ├── vite.config.js +│ ├── package.json +│ └── src/ +│ ├── main.jsx +│ ├── App.jsx Main React component +│ ├── App.css +│ ├── index.css +│ ├── components/ +│ │ ├── Map3D.jsx 3D visualization +│ │ ├── ControlPanel.jsx UI controls +│ │ └── ControlPanel.css +│ └── store/ +│ └── turtleStore.js State management +│ +└── 🎮 Minecraft/Lua (3 files) + ├── webbridge.lua HTTP bridge to server + ├── turtle.lua Advanced turtle AI + └── pocketremote.lua Original pocket UI + +Total: 23+ files created/enhanced! +``` + +## 🎯 Key Features + +### Web Interface +- ✅ **3D Interactive Map** - Orbital camera, click to select +- ✅ **Real-time Updates** - See turtle movements live +- ✅ **Multiple Views** - Split, map-only, control-only +- ✅ **Turtle Cards** - Quick overview of all turtles +- ✅ **Detailed Control** - Per-turtle commands and stats +- ✅ **Manual Controls** - Arrow keys for direct movement +- ✅ **Inventory Display** - See what turtles collected +- ✅ **Connection Status** - Visual indicator +- ✅ **Dark Theme** - Easy on the eyes + +### Technical +- ✅ **WebSocket** - Real-time bidirectional communication +- ✅ **REST API** - HTTP endpoints for turtle updates +- ✅ **State Management** - Zustand for React state +- ✅ **3D Graphics** - Three.js rendering +- ✅ **Auto-reconnect** - Handles disconnections +- ✅ **Command Queue** - Reliable command delivery +- ✅ **Stale Cleanup** - Removes offline turtles + +### Minecraft Integration +- ✅ **HTTP Bridge** - Connects game to web +- ✅ **Wireless Modem** - In-game communication +- ✅ **GPS Support** - Position tracking +- ✅ **Autonomous Modes** - Explore, mine, return +- ✅ **Fuel Management** - Auto-refuel logic +- ✅ **Pathfinding** - Navigate to targets +- ✅ **Status Broadcasting** - Regular updates + +## 🚀 How to Use + +### 1. Install Dependencies + +**Option A: One Command** +```bash +./start.sh # Linux/Mac +start.bat # Windows +``` + +**Option B: Manual** +```bash +cd server && npm install +cd ../client && npm install +``` + +### 2. Start Servers + +The startup script automatically starts both: +- Backend server (http://localhost:3001) +- Frontend app (http://localhost:3000) + +### 3. Configure Minecraft + +**Bridge Computer:** +1. Place computer with wireless modem +2. Copy `webbridge.lua` +3. Edit SERVER_URL if needed +4. Run: `webbridge` + +**Turtles:** +1. Place turtles with wireless modems +2. Copy `turtle.lua` +3. Run: `turtle` + +### 4. Open Web Interface + +Navigate to: **http://localhost:3000** + +You should see: +- Connection status: 🟢 Connected +- Waiting for turtles message +- Empty 3D map with grid + +### 5. Control Turtles! + +- Click turtle cards or 3D markers to select +- Use command buttons: Explore, Mine, Return, Stop +- Try manual controls: ↑ ↓ ← → ⬆ ⬇ +- Watch the 3D map update in real-time! + +## 📚 Documentation Guide + +**New to the project?** Start here: +1. **QUICKSTART.md** - Get running in 5 minutes +2. **README.md** - Full documentation + +**Want to understand the system?** +- **ARCHITECTURE.md** - How everything connects +- **INTERFACE.md** - UI/UX design + +**Having problems?** +- **TROUBLESHOOTING.md** - Common issues & solutions + +**Curious what was built?** +- **PROJECT_SUMMARY.md** - Complete overview +- **THIS_FILE.md** - Quick reference + +## 🎨 Color Guide + +Turtle Status Colors: +- 🟢 Green: Mining/Active +- 🔵 Blue: Exploring +- 🟠 Orange: Returning Home +- ⚪ Gray: Idle +- 🟣 Purple: Manual Control + +UI Theme: +- Background: Dark blue (#0a0e1a) +- Panels: Slate (#1e293b) +- Text: Light gray (#e2e8f0) +- Accents: Cyan (#60a5fa) + +## 🔧 Quick Commands + +```bash +# Start everything +./start.sh + +# Install all dependencies +npm run install:all + +# Start only backend +npm run server + +# Start only frontend +npm run client + +# Build for production +npm run build +``` + +## 🌐 Network Ports + +``` +3000 - React Frontend (Vite dev server) +3001 - Express HTTP API +3002 - WebSocket Server + +Minecraft Modem Channels: +100 - Commands TO turtles +101 - Responses FROM turtles +102 - Status updates +``` + +## 💡 Pro Tips + +1. **GPS Setup**: Place 4 computers at Y=200+ in square pattern +2. **Fuel Management**: Keep coal in turtle slot 16 +3. **Chunk Loading**: Use chunk loader for bridge computer +4. **Multiple Turtles**: Each needs unique ID (automatic) +5. **View Modes**: Split for monitoring, Map for presentations +6. **Browser**: Chrome or Firefox work best +7. **Network**: Use IP address for remote access +8. **Backup**: Save turtle programs to disk + +## 🔍 Testing Checklist + +- [ ] Node.js installed (v18+) +- [ ] Dependencies installed (npm install) +- [ ] Server starts without errors +- [ ] Browser opens to http://localhost:3000 +- [ ] Connection status shows "Connected" +- [ ] Bridge computer running in Minecraft +- [ ] Turtles have wireless modems +- [ ] GPS hosts configured (optional but recommended) +- [ ] Turtle appears in web interface +- [ ] Commands work (try "Explore") +- [ ] 3D map updates when turtle moves + +## 📊 What Happens When You Run It + +``` +1. Start scripts → Install dependencies → Launch servers + ↓ +2. Node.js Server starts → Opens HTTP (3001) & WebSocket (3002) + ↓ +3. React App starts → Vite dev server (3000) → Opens browser + ↓ +4. Browser connects → WebSocket established → Shows "Connected" + ↓ +5. In Minecraft → Run webbridge.lua → Listens for turtles + ↓ +6. Run turtle.lua → Broadcasts status → Bridge forwards to server + ↓ +7. Server → WebSocket → React → Updates UI → Turtle appears! + ↓ +8. Click "Explore" → Command queued → Bridge polls → Turtle moves + ↓ +9. Real-time updates → 3D map animates → You see turtle exploring! +``` + +## 🎉 Success Looks Like + +When everything works: +- ✅ Terminal shows "Server ready!" and "Vite dev server running" +- ✅ Browser shows turtle control interface +- ✅ Green "Connected" indicator in top-right +- ✅ Minecraft bridge shows "Sent to server" messages +- ✅ Turtles appear in left panel +- ✅ 3D map shows turtle markers +- ✅ Commands execute when clicked +- ✅ Map updates as turtles move + +## 🚨 If Something's Wrong + +1. Check server terminal for errors +2. Check browser console (F12) +3. Check Minecraft computer console +4. Read TROUBLESHOOTING.md +5. Verify all files exist +6. Try restarting everything + +## 🎓 Learning Resources + +**React**: https://react.dev/ +**Three.js**: https://threejs.org/ +**Node.js**: https://nodejs.org/ +**ComputerCraft**: https://tweaked.cc/ +**WebSocket**: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket + +## 🌟 Next Steps + +Once you have it running: +1. Try controlling multiple turtles +2. Set up GPS for accurate tracking +3. Watch autonomous mining in action +4. Customize the UI colors/layout +5. Add new commands +6. Share with friends on your network! + +## 📈 Possible Enhancements + +Future ideas: +- [ ] Path recording and playback +- [ ] Task scheduling +- [ ] Multi-turtle coordination +- [ ] Database persistence +- [ ] User authentication +- [ ] Mobile app +- [ ] Voice commands +- [ ] Mining statistics +- [ ] Area visualization +- [ ] Turtle groups/teams + +## 🎊 Congratulations! + +You've successfully set up a complete full-stack web application for Minecraft turtle control! + +**You now have:** +- Modern React web interface +- Real-time 3D visualization +- WebSocket communication +- Node.js backend server +- Minecraft integration +- Complete documentation + +**Enjoy your new turtle command center!** 🐢✨ + +--- + +Need help? Check the documentation files or troubleshooting guide! + +**Happy mining!** ⛏️ diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..d24af7b --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,408 @@ +# 🔧 Troubleshooting Guide + +## Installation Issues + +### Node.js Not Found + +**Problem:** `command not found: node` or `'node' is not recognized` + +**Solution:** +1. Install Node.js from https://nodejs.org/ (LTS version recommended) +2. Restart your terminal after installation +3. Verify: `node --version` should show v18.0.0 or higher + +### npm Install Fails + +**Problem:** Errors during `npm install` + +**Solutions:** +- Clear npm cache: `npm cache clean --force` +- Delete `node_modules` folders and try again +- Update npm: `npm install -g npm@latest` +- Check your internet connection +- Try: `npm install --legacy-peer-deps` + +## Server Issues + +### Port Already in Use + +**Problem:** `Error: listen EADDRINUSE: address already in use :::3001` + +**Solution 1 - Change Ports:** +1. Edit `server/server.js`: + ```javascript + const PORT = 3005; // Change from 3001 + const WS_PORT = 3006; // Change from 3002 + ``` + +2. Edit `client/src/store/turtleStore.js`: + ```javascript + const WS_URL = 'ws://localhost:3006'; + const API_URL = 'http://localhost:3005'; + ``` + +**Solution 2 - Kill Existing Process:** + +Linux/Mac: +```bash +lsof -ti:3001 | xargs kill -9 +lsof -ti:3002 | xargs kill -9 +``` + +Windows: +```cmd +netstat -ano | findstr :3001 +taskkill /PID /F +``` + +### Server Won't Start + +**Problem:** Server crashes on start + +**Checklist:** +- [ ] Dependencies installed? Run `cd server && npm install` +- [ ] Node.js version 18+? Check with `node --version` +- [ ] Firewall blocking ports? Add exception for ports 3001-3002 +- [ ] Check server logs for specific error messages + +## Client Issues + +### White Screen / Nothing Renders + +**Problem:** Browser shows blank page + +**Solutions:** +1. Open browser console (F12) and check for errors +2. Verify server is running: http://localhost:3001/api/turtles +3. Clear browser cache (Ctrl+Shift+Delete) +4. Try incognito/private mode +5. Try different browser (Chrome/Firefox recommended) + +### WebSocket Connection Failed + +**Problem:** Red "Disconnected" status in top-right + +**Solutions:** +1. Check server console for errors +2. Verify WebSocket port (3002) is open +3. Check browser console for WebSocket errors +4. Ensure server URL is correct in `turtleStore.js` +5. Firewall may be blocking WebSocket - add exception + +### 3D Map Not Showing + +**Problem:** Map area is black or shows errors + +**Solutions:** +- WebGL not supported: Update graphics drivers +- Browser compatibility: Use Chrome 90+ or Firefox 88+ +- Hardware acceleration disabled: Enable in browser settings + - Chrome: Settings → System → Use hardware acceleration + - Firefox: Settings → Performance → Use hardware acceleration +- GPU issues: Try different browser + +## Minecraft/ComputerCraft Issues + +### Bridge Computer Not Connecting + +**Problem:** `webbridge.lua` runs but no connection to server + +**Checklist:** +1. Verify SERVER_URL is correct: + ```lua + local SERVER_URL = "http://localhost:3001" + ``` + - Use computer's IP if server is remote + - Don't use `https://` (use `http://`) + +2. Check HTTP API is enabled: + - Edit `config/computercraft-server.toml` or `.minecraft/config/computercraft.cfg` + - Find: `enable_http = true` + - Ensure your server URL is not in `blocked_domains` + +3. Test HTTP manually: + ```lua + local response = http.get("http://localhost:3001/api/turtles") + print(response ~= nil) -- Should print true + ``` + +### Turtles Not Appearing in Web + +**Problem:** Bridge runs, but no turtles show up + +**Diagnosis:** +1. Check bridge computer console for "Status from Turtle X" messages +2. Check server console for "Status update from Turtle X" messages +3. Check web browser console for WebSocket messages + +**Common Causes:** +- Channel mismatch - Verify all scripts use same channels: + - `turtle.lua`: STATUS_CHANNEL = 102 + - `webbridge.lua`: STATUS_CHANNEL = 102 + +- Modem not equipped on turtle +- Turtles out of wireless range +- Turtles not running `turtle.lua` script + +### GPS Not Working + +**Problem:** Turtles show "No GPS" + +**Solution - Set Up GPS Hosts:** + +1. Place 4 computers at high altitude (Y=200+) +2. Arrange in square pattern (20+ blocks apart) +3. Give each a wireless modem +4. Run on each: + ```lua + gps host X Y Z + ``` + Replace X Y Z with that computer's actual coordinates + +5. Test from turtle: + ```lua + x, y, z = gps.locate(5) + print(x, y, z) -- Should print coordinates + ``` + +### Modem Not Found + +**Problem:** `No wireless modem found!` + +**Solutions:** +- Craft wireless modem (Stone + Ender Pearl) +- Equip to turtle: Right-click turtle with modem +- For computer: Place modem adjacent and right-click +- Verify: `peripheral.find("modem")` should not be nil + +### Commands Not Reaching Turtles + +**Problem:** Click commands in web but turtle doesn't respond + +**Debug Steps:** + +1. Check server receives command: + - Server console should show: `Command queued for turtle X` + +2. Check bridge polls for commands: + - Bridge console should show: `Command for Turtle X: ` + +3. Check turtle receives command: + - Add debug to `turtle.lua`: + ```lua + print("Received message:", textutils.serialize(message)) + ``` + +4. Verify channels match: + - Web → Server → Bridge → Modem Channel 100 → Turtle + +## Performance Issues + +### Laggy 3D Map + +**Solutions:** +- Reduce number of visible turtles +- Lower browser zoom level +- Close other browser tabs +- Update graphics drivers +- Try lower graphics settings in browser + +### Server Using Too Much Memory + +**Solutions:** +- Restart server periodically +- Reduce `statusUpdateInterval` in turtle.lua (less frequent updates) +- Clear old turtle data: restart server + +### High Network Usage + +**Solutions:** +- Increase `statusUpdateInterval` in turtle.lua (default: 5 seconds) +- Reduce number of active turtles +- Use local server instead of remote + +## Browser-Specific Issues + +### Chrome + +**WebSocket closes immediately:** +- Disable browser extensions (especially ad blockers) +- Clear site data: F12 → Application → Clear storage + +### Firefox + +**3D map performance poor:** +- Enable WebRender: about:config → gfx.webrender.all → true + +### Safari + +**Not recommended** - Limited WebGL support. Use Chrome or Firefox. + +## Network Issues + +### Can't Access from Other Devices + +**Problem:** Works on localhost but not from other computers + +**Solution:** + +1. Get your computer's IP address: + ```bash + # Linux/Mac + ifconfig | grep "inet " + + # Windows + ipconfig + ``` + Example: 192.168.1.100 + +2. Update configs to use IP instead of localhost: + + **webbridge.lua:** + ```lua + local SERVER_URL = "http://192.168.1.100:3001" + ``` + + **client/src/store/turtleStore.js:** + ```javascript + const WS_URL = 'ws://192.168.1.100:3002'; + const API_URL = 'http://192.168.1.100:3001'; + ``` + +3. Configure firewall: + + **Linux:** + ```bash + sudo ufw allow 3000:3002/tcp + ``` + + **Windows:** + - Windows Defender Firewall → Advanced Settings + - Inbound Rules → New Rule + - Port: 3000-3002 + - Allow the connection + +4. Access from other device: `http://192.168.1.100:3000` + +### Minecraft Server and Web Server on Different Machines + +**Setup:** +- Computer A: Minecraft + Bridge +- Computer B: Node.js Server + Web Client + +**Configuration:** + +1. On Computer A (Minecraft), edit `webbridge.lua`: + ```lua + local SERVER_URL = "http://:3001" + ``` + +2. On Computer B, server.js needs no changes + +3. Access web interface from anywhere: `http://:3000` + +## Common Error Messages + +### "Failed to send to server" + +**In webbridge.lua console** + +**Cause:** Bridge can't reach Node.js server + +**Fix:** +- Verify server is running +- Check SERVER_URL is correct +- Test: `http.get(SERVER_URL .. "/api/turtles")` + +### "Turtle not found" + +**In server logs** + +**Cause:** Turtle ID not in server's turtle map + +**Fix:** +- Turtle hasn't sent status update yet - wait 5 seconds +- Restart turtle script +- Check turtle is broadcasting on correct channel + +### "WebSocket connection failed" + +**In browser console** + +**Cause:** Can't connect to WebSocket server + +**Fix:** +- Verify server is running +- Check port 3002 is open +- Update WS_URL in turtleStore.js +- Disable VPN/proxy + +## Still Having Issues? + +### Collect Debug Information + +1. **Server logs**: Copy output from server terminal +2. **Browser console**: F12 → Console tab → Copy errors +3. **Minecraft logs**: Check bridge computer output +4. **Network test**: Can you access http://localhost:3001/api/turtles? + +### Reset Everything + +Sometimes easiest to start fresh: + +```bash +# Stop all servers (Ctrl+C) + +# Clean and reinstall +rm -rf server/node_modules client/node_modules +cd server && npm install +cd ../client && npm install + +# Restart +./start.sh # or start.bat on Windows +``` + +### Check Versions + +```bash +node --version # Should be v18.0.0+ +npm --version # Should be v9.0.0+ +``` + +### Test Connectivity + +**Test 1 - Server Health:** +```bash +curl http://localhost:3001/api/turtles +``` +Should return: `{"turtles":[]}` + +**Test 2 - WebSocket:** +Open browser console and run: +```javascript +const ws = new WebSocket('ws://localhost:3002'); +ws.onopen = () => console.log('Connected!'); +ws.onerror = (e) => console.log('Error:', e); +``` + +**Test 3 - Minecraft HTTP:** +In ComputerCraft: +```lua +local r = http.get("http://localhost:3001/api/turtles") +print(r ~= nil) +``` + +--- + +**If all else fails:** +- Check the full README.md +- Review ARCHITECTURE.md for system design +- Ensure all dependencies are installed +- Try example commands manually +- Double-check all configuration files match + +**Still stuck?** Create an issue with: +- Error messages +- Server/client logs +- Steps to reproduce +- Your configuration