MayaTheShy/remoteturtle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add comprehensive documentation for project architecture, troubleshooting, and setup

Browse Source
This commit is contained in:
MayaTheShy
2026-02-16 00:01:04 -05:00
parent db3e07689a
commit a6edc0934c
3 changed files with 1046 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

291
ARCHITECTURE.md Normal file
View File

@@ -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

347
START_HERE.md Normal file
View File

@@ -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!** ⛏️

408
TROUBLESHOOTING.md Normal file
View File

@@ -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 <PID_NUMBER> /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: <command>`
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://<Computer_B_IP>:3001"
```
2. On Computer B, server.js needs no changes
3. Access web interface from anywhere: `http://<Computer_B_IP>: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