feat: Add comprehensive documentation for project architecture, troubleshooting, and setup
This commit is contained in:
MayaTheShy
408
TROUBLESHOOTING.md
Normal file
408
TROUBLESHOOTING.md
Normal 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
|
||||
Reference in New Issue
Block a user