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

feat: Add comprehensive feature documentation and overview of key files in README.md

Browse Source
This commit is contained in:
MayaTheShy
2026-02-19 22:57:00 -05:00
parent 546e17e6d2
commit 7b3ae34cfa
2 changed files with 727 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
README.md
View File

@@ -105,34 +105,101 @@ A comprehensive full-stack web application for monitoring and controlling Comput
```
remoteturtle/
├── server/ # Node.js backend
│ ├── server.js # Express + WebSocket server
│ └── package.json
├── client/ # React frontend
├── server/ # Node.js backend (650+ lines)
│ ├── server.js # Express REST API + WebSocket server
│ ├── database.js # SQLite database layer (450+ lines)
│ ├── turtle_control.db # SQLite database file
│ ├── package.json
│ └── node_modules/
│
├── client/ # React frontend (1,500+ lines)
│ ├── src/
│ │ ├── components/
│ │ │ ├── Map3D.jsx # 3D map visualization
│ │ │ ├── ControlPanel.jsx # Control interface
│ │ │ └── ControlPanel.css
│ │ │ ├── Map3D.jsx # Three.js 3D visualization
│ │ │ ├── ControlPanel.jsx # Main control interface
│ │ │ ├── ControlPanel.css # Control panel styles
│ │ │ ├── VoiceControl.jsx # Voice command interface (NEW)
│ │ │ └── VoiceControl.css # Voice control styles (NEW)
│ │ ├── store/
│ │ │ └── turtleStore.js # Zustand state management
│ │ ├── App.jsx
│ │ ├── App.css
│ │ ├── main.jsx
│ │ └── index.css
│ │ │ └── turtleStore.js # Zustand state management
│ │ ├── App.jsx # Main application component
│ │ ├── App.css # Global styles + responsive design
│ │ ├── main.jsx # React entry point
│ │ └── index.css # Base styles
│ ├── 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
│ ├── vite.config.js # Vite configuration
│ ├── package.json
│ └── node_modules/
│
├── webbridge.lua # ComputerCraft HTTP bridge (200+ lines)
├── turtle.lua # Intelligent turtle controller (400+ lines)
├── pocketremote.lua # Pocket computer interface (150+ lines)
├── FEATURES.md # Feature documentation
└── README.md # This file
```
### Key Files Overview
**Backend:**
- `server/server.js` - 35+ REST API endpoints, WebSocket server
- `server/database.js` - Database abstraction with 10 tables
**Frontend:**
- `client/src/App.jsx` - Layout and routing
- `client/src/components/Map3D.jsx` - 3D turtle visualization
- `client/src/components/ControlPanel.jsx` - Main control UI
- `client/src/components/VoiceControl.jsx` - Voice commands
- `client/src/store/turtleStore.js` - Global state management
**ComputerCraft:**
- `webbridge.lua` - Bridge between Minecraft and web server
- `turtle.lua` - Autonomous turtle with intelligent navigation
- `pocketremote.lua` - Mobile control from pocket computers
## 🎮 Usage
### Web Interface
The interface features a **multi-panel tabbed design** for comprehensive turtle management:
#### 🎮 Control Panel
- View all connected turtles
- Manual movement controls (forward, back, up, down, turn)
- Autonomous commands (explore, mine, return home)
- Real-time inventory display (4x4 grid with emojis)
- GPS position and fuel monitoring
#### 🎤 Voice Commands
- Speak naturally to control turtles
- 20+ recognized commands
- Real-time transcript display
- Speech confirmation feedback
- Command help reference
#### 📊 Statistics Dashboard
- Mining statistics per turtle
- Block type breakdown with emojis
- Top miners leaderboard (🥇🥈🥉)
- Time filters (24h, 7d, 30d, All)
- Total blocks mined tracking
#### 👥 Groups Management
- Create turtle teams with custom colors
- 8 color presets available
- Add/remove turtles from groups
- Send commands to entire team
- Member status tracking
#### 📋 Task Queue
- Create tasks with 6 types
- Priority system (1-10)
- Coordinate input for area tasks
- Filter by status
- Assign to specific turtles
- Task lifecycle management
### View Modes
1. **View Modes**:
- **Split View**: See both map and control panel
- **Map Only**: Full-screen 3D map
@@ -153,14 +220,44 @@ remoteturtle/
### 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
**Turtle Commands** (via pocket computer, web, or voice):
**Movement:**
- `forward/back/up/down` - Directional movement
- `turnLeft/turnRight` - Rotation
- `dig/digUp/digDown` - Mining
**Actions:**
- `dig/digUp/digDown` - Mining operations
- `place/placeUp/placeDown` - Block placement
- `refuel` - Consume fuel items
**Autonomous Operations:**
- `explore` - Intelligent exploration with position memory
- 75% horizontal movement preference
- 15% downward, 10% upward movement
- Visited position tracking to avoid loops
- Stuck detection with recovery
- `mine` - Autonomous mining mode
- `returnHome` - Navigate back to home (non-blocking)
- `stop` - Stop current operation
- `setHome` - Set current position as home
- `status` - Report current state
### Intelligent Navigation Features
The turtle.lua script includes advanced navigation:
1. **Position Memory**: Tracks last 50 positions to avoid revisiting
2. **Visited Position Tracking**: Maintains history to prevent loops
3. **Stuck Detection**: Identifies when turtle can't move and tries alternatives
4. **Smart Direction Selection**:
- Prefers horizontal movement (75%)
- Controlled descent (15%)
- Minimal upward movement (10%)
5. **Turn Limiting**: Max 3 turn attempts to prevent endless spinning
6. **Non-blocking Return Home**: Can return home without timing out
7. **Fuel Management**: Auto-refuels when fuel is low
8. **GPS Integration**: Uses GPS for accurate positioning
## 🔧 Configuration
@@ -215,12 +312,14 @@ To access from other devices on your network:
## 📊 Project Statistics
- **Total Code**: 3,500+ lines
- **Database Tables**: 10
- **Total Code**: 5,600+ lines
- **Database Tables**: 11
- **API Endpoints**: 35+
- **Supported Commands**: 25+
- **Voice Commands**: 20+
- **Frontend Components**: 8+
- **Frontend Components**: 12+
- **Task Types**: 6
- **Color Presets**: 8
## 📊 API Reference
@@ -552,23 +651,112 @@ The system supports natural language voice commands using the Web Speech API (Ch
### 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
1. **Check webbridge is running**
- Verify webbridge.lua is active in Minecraft
- Check for error messages in the Minecraft console
2. **Verify SERVER_URL configuration**
- Ensure webbridge.lua points to correct server address
- Use `http://localhost:3001` for local testing
- Use your machine's IP for remote access
3. **Check turtle setup**
- Ensure turtle.lua is running
- Verify wireless modem is equipped
- Check modem is on correct side (usually top)
4. **Verify channel configuration**
- All scripts must use matching channel numbers
- Default: RECEIVE=100, SEND=101, STATUS=102
### 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
1. **Server not responding**
- Check server is running: `http://localhost:3001/api/turtles`
- Verify no port conflicts (3001, 3002, 3000)
- Check firewall isn't blocking connections
2. **WebSocket disconnections**
- Check browser console for WebSocket errors
- Verify WS_PORT (3002) is accessible
- Try restarting both client and server
3. **Database errors**
- Check `server/turtle_control.db` file exists
- Ensure write permissions on database file
- Try deleting database to reinitialize (loses data)
### Turtle behavior issues
1. **Turtle gets stuck or spins endlessly**
- Check fuel level (need sufficient fuel)
- Verify GPS is working (`gps locate` in-game)
- Restart turtle.lua to reset state
2. **Turtle not finding home**
- Ensure home position is set (`setHome` command)
- Check GPS hosts are functioning
- Verify turtle has enough fuel to return
3. **Turtle timing out**
- Fixed in latest version with non-blocking return home
- Ensure latest turtle.lua is deployed
- Check modem range (max 64 blocks without ender modem)
### Voice commands not working
1. **Browser compatibility**
- Use Chrome, Edge, or Safari (Firefox not supported)
- Check microphone permissions in browser settings
- Try HTTPS instead of HTTP (some browsers require it)
2. **Microphone issues**
- Verify microphone is connected and working
- Check system permissions allow browser mic access
- Test with "Hello Google" or other voice apps
3. **Commands not recognized**
- Speak clearly and at normal pace
- Use exact command phrases from the help menu
- Check browser console for recognition 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
1. **Set up GPS hosts**
- Requires 4 computers in Minecraft
- Position in square pattern at high Y level (Y>100 recommended)
- Each runs: `gps host X Y Z` with their exact coordinates
2. **GPS host placement**
```
Host positions (example):
Computer 1: gps host 100 120 100
Computer 2: gps host 200 120 100
Computer 3: gps host 100 120 200
Computer 4: gps host 200 120 200
```
3. **Troubleshooting GPS**
- Ensure all 4 hosts are loaded (chunk loaders)
- Keep them at least 6 blocks apart
- Must be on same dimension as turtles
### Performance issues
1. **Slow web interface**
- Reduce number of visible turtles in 3D map
- Disable block tracking if not needed
- Use production build: `npm run build`
2. **High database size**
- Periodically clean old session data
- Archive old paths and tasks
- Consider vacuum command: `VACUUM;`
3. **Memory issues in Minecraft**
- Limit number of active turtles
- Reduce position memory size in turtle.lua
- Use more efficient exploration patterns
## 🎨 Customization
@@ -617,26 +805,24 @@ Built with:
- [x] WebSocket bidirectional communication
- [x] Manual turtle control interface
- [x] Autonomous exploration with intelligent navigation
- [x] Database persistence (SQLite with 10+ tables)
- [x] Database persistence (SQLite with 11 tables)
- [x] Path recording backend (API complete)
- [x] Task queue system backend (API complete)
- [x] Task queue system (backend + frontend complete)
- [x] Mining area management backend (API complete)
- [x] Mining statistics tracking (per turtle, per block type)
- [x] Turtle groups/teams coordination
- [x] Mining statistics tracking (backend + frontend complete)
- [x] Turtle groups/teams coordination (backend + frontend complete)
- [x] Voice command interface (Web Speech API, 20+ commands)
- [x] Enhanced inventory display (4x4 grid with emojis)
- [x] Mobile-responsive design (desktop/tablet/mobile)
- [x] Position memory and visited tracking
- [x] Stuck detection and recovery
- [x] Session-based analytics
- [x] Multi-panel tabbed interface (Control, Voice, Stats, Groups, Tasks)
### 🚧 In Progress / Frontend Pending
### 🚧 Frontend Pending (Backend Complete)
- [ ] Path recording UI (playback controls, visualization)
- [ ] Task coordination UI (task creation, queue display)
- [ ] Mining area visualization (3D overlays on map)
- [ ] Statistics dashboard (charts, leaderboards)
- [ ] Group management UI (create/manage teams)
### 📋 Future Enhancements