feat: Add comprehensive feature documentation and overview of key files in README.md
This commit is contained in:
MayaTheShy
495
FEATURES.md
Normal file
495
FEATURES.md
Normal file
@@ -0,0 +1,495 @@
|
||||
# 🎮 Feature Documentation
|
||||
|
||||
## ✅ Implemented Features
|
||||
|
||||
### 1. 🗄️ Database Persistence (SQLite)
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Persistent storage for all turtle data across server restarts.
|
||||
|
||||
**Features:**
|
||||
- Turtle home positions saved to database
|
||||
- World block discoveries persisted
|
||||
- Turtle configurations stored
|
||||
- Path recordings saved
|
||||
- Task queue persistence
|
||||
- Mining area claims tracked
|
||||
|
||||
**Database Tables:**
|
||||
- `turtle_homes` - Home position for each turtle
|
||||
- `turtle_config` - Configuration per turtle
|
||||
- `world_blocks` - All discovered blocks with timestamps
|
||||
- `turtle_paths` - Recorded movement paths
|
||||
- `task_queue` - Shared task system
|
||||
- `mining_areas` - Area claims and zones
|
||||
|
||||
**API Endpoints:**
|
||||
```
|
||||
GET /api/turtle/:id/home - Get turtle home
|
||||
POST /api/turtle/:id/home - Set turtle home
|
||||
GET /api/stats - Server statistics
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ No data loss on server restart
|
||||
- ✅ Historical block discovery tracking
|
||||
- ✅ Persistent configurations
|
||||
- ✅ Scalable to many turtles
|
||||
|
||||
---
|
||||
|
||||
### 2. 📦 Inventory Management UI
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Beautiful 4x4 grid inventory display with real-time updates.
|
||||
|
||||
**Features:**
|
||||
- 16-slot grid layout (matches Minecraft turtle inventory)
|
||||
- Item-specific emoji icons (💎 for diamonds, ⚫ for coal, etc.)
|
||||
- Item counts displayed in corner
|
||||
- Item names shown on hover
|
||||
- Empty slots clearly marked
|
||||
- Smooth hover animations
|
||||
- Touch-friendly on mobile
|
||||
|
||||
**Visual Design:**
|
||||
- Dark theme matching overall UI
|
||||
- Glowing borders for filled slots
|
||||
- Dashed borders for empty slots
|
||||
- Item count badges
|
||||
- Responsive grid layout
|
||||
|
||||
**Item Icons:**
|
||||
- 💎 Diamond ore
|
||||
- 🟡 Gold ore
|
||||
- ⚪ Iron ore
|
||||
- ⚫ Coal
|
||||
- 🟢 Emerald
|
||||
- 🔴 Redstone
|
||||
- 🔵 Lapis
|
||||
- 🗿 Stone
|
||||
- 🟤 Dirt
|
||||
- 🪵 Wood/logs
|
||||
- 🪨 Cobblestone
|
||||
- 📦 Generic items
|
||||
|
||||
---
|
||||
|
||||
### 3. 📱 Mobile-Responsive Design
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Fully responsive interface that works on all devices.
|
||||
|
||||
**Breakpoints:**
|
||||
- **Desktop (1024px+):** Split 50/50 view
|
||||
- **Tablet (768-1024px):** Stacked vertical layout
|
||||
- **Mobile (480-768px):** Tab-based single view
|
||||
- **Small Mobile (<480px):** Optimized compact layout
|
||||
|
||||
**Touch Optimizations:**
|
||||
- Minimum 44px touch targets (iOS standard)
|
||||
- Larger buttons on touch devices
|
||||
- Active states instead of hover
|
||||
- Optimized spacing for fingers
|
||||
- Scroll-friendly layouts
|
||||
|
||||
**Orientation Support:**
|
||||
- **Portrait:** Vertical stacking
|
||||
- **Landscape:** Side-by-side split
|
||||
|
||||
**Accessibility:**
|
||||
- Reduced motion support
|
||||
- High contrast mode
|
||||
- Screen reader friendly
|
||||
- Keyboard navigation
|
||||
|
||||
---
|
||||
|
||||
### 4. 🧠 Intelligent Navigation
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Smart exploration algorithm that learns and adapts.
|
||||
|
||||
**Features:**
|
||||
- Position memory (tracks visited locations)
|
||||
- Stuck detection and auto-recovery
|
||||
- Hole escape algorithm
|
||||
- Depth management (avoids going too deep)
|
||||
- Horizontal-focused exploration (75%)
|
||||
- Prefers unvisited areas
|
||||
- Valuable ore priority mining
|
||||
|
||||
**Navigation Priorities:**
|
||||
1. Mine valuable ores (always)
|
||||
2. Move horizontally (75%)
|
||||
3. Go down if safe (15%, only above y=15)
|
||||
4. Go up if needed (10%, only if stuck or deep)
|
||||
|
||||
**Anti-Stuck Features:**
|
||||
- Detects stationary position
|
||||
- Climbs out after 8 stuck steps
|
||||
- Tries all 4 directions
|
||||
- Digs through obstacles
|
||||
- Never gets permanently stuck
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Backend API Ready (Frontend Pending)
|
||||
|
||||
### 5. 🛤️ Path Recording System
|
||||
**Status:** 🔶 Backend Complete, Frontend Pending
|
||||
|
||||
Record and replay turtle movement paths.
|
||||
|
||||
**API Endpoints:**
|
||||
```
|
||||
POST /api/paths - Save a path
|
||||
GET /api/paths/:turtleId - Get all paths for turtle
|
||||
DELETE /api/paths/:pathId - Delete a path
|
||||
```
|
||||
|
||||
**Database:**
|
||||
- Stores path name, turtle ID, and movement data
|
||||
- Timestamps for creation and updates
|
||||
|
||||
**To Implement (Frontend):**
|
||||
- Record button to start/stop path recording
|
||||
- Path list viewer
|
||||
- Playback controls
|
||||
- Path sharing between turtles
|
||||
|
||||
---
|
||||
|
||||
### 6. 🤝 Multi-Turtle Task Coordination
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Shared task queue for coordinating multiple turtles.
|
||||
|
||||
**API Endpoints:**
|
||||
```
|
||||
POST /api/tasks - Create task
|
||||
GET /api/tasks - Get all tasks
|
||||
GET /api/tasks/next - Get next available task
|
||||
POST /api/tasks/:id/assign - Assign task to turtle
|
||||
POST /api/tasks/:id/complete - Mark task complete
|
||||
```
|
||||
|
||||
**Task System:**
|
||||
- Priority-based queue
|
||||
- Task types: mine, explore, build, gather, transport, clear_area
|
||||
- Status tracking: pending, in_progress, completed, failed
|
||||
- Automatic assignment to available turtles
|
||||
|
||||
**Frontend Features:**
|
||||
- ✅ Task creation UI with 6 task types
|
||||
- ✅ Task queue display with filtering
|
||||
- ✅ Priority management (1-10 with labels)
|
||||
- ✅ Assignment controls
|
||||
- ✅ Coordinate input for area-based tasks
|
||||
- ✅ Status tracking and updates
|
||||
- ✅ Mobile responsive design
|
||||
|
||||
---
|
||||
|
||||
### 7. 🗺️ Mining Area Visualization
|
||||
**Status:** 🔶 Backend Complete, Frontend Pending
|
||||
|
||||
Claim and visualize mining zones on 3D map.
|
||||
|
||||
**API Endpoints:**
|
||||
```
|
||||
POST /api/mining-areas - Claim mining area
|
||||
GET /api/mining-areas - Get all areas
|
||||
POST /api/mining-areas/:id/close - Close area
|
||||
```
|
||||
|
||||
**Database:**
|
||||
- Stores 3D bounding boxes (min/max X, Y, Z)
|
||||
- Tracks which turtle owns the area
|
||||
- Status: active or closed
|
||||
|
||||
**To Implement (Frontend):**
|
||||
- 3D wireframe boxes on map
|
||||
- Color coding per turtle
|
||||
- Area claim UI
|
||||
- Conflict detection
|
||||
|
||||
---
|
||||
|
||||
### 8. ⏰ Task Scheduling
|
||||
**Status:** 🔶 Backend Complete
|
||||
|
||||
Schedule tasks with priorities and time-based execution.
|
||||
|
||||
**Features:**
|
||||
- Priority system (0-10)
|
||||
- Task types and metadata
|
||||
- Queue management
|
||||
- Status tracking
|
||||
|
||||
**To Implement (Frontend):**
|
||||
- Scheduling calendar view
|
||||
- Priority slider
|
||||
- Task templates
|
||||
- Recurring tasks
|
||||
|
||||
---
|
||||
|
||||
## 📋 Not Yet Implemented
|
||||
|
||||
### 9. 🔐 Authentication System
|
||||
**Status:** ❌ Not Started
|
||||
|
||||
Multi-user support with login and permissions.
|
||||
|
||||
**Planned Features:**
|
||||
- User registration and login
|
||||
- JWT token authentication
|
||||
- Role-based permissions (admin, user, viewer)
|
||||
- Per-user turtle assignments
|
||||
- Action logging and audit trail
|
||||
|
||||
**Tech Stack (Proposed):**
|
||||
- bcrypt for password hashing
|
||||
- jsonwebtoken for JWT
|
||||
- Express middleware for auth
|
||||
- Cookie-based sessions
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## ✅ Newly Implemented Frontend Features
|
||||
|
||||
### 10. 🎤 Voice Commands
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Natural language control using Web Speech API.
|
||||
|
||||
**Features:**
|
||||
- 20+ voice commands for turtle control
|
||||
- Speech recognition with natural language processing
|
||||
- Speech synthesis for confirmation feedback
|
||||
- Browser compatibility detection (Chrome, Edge, Safari)
|
||||
- Command help with categorized lists
|
||||
- Pulse animation when listening
|
||||
|
||||
**Command Categories:**
|
||||
- Movement: forward, back, turn left/right, up, down
|
||||
- Actions: dig, dig up/down, place, refuel
|
||||
- Autonomous: explore, mine, return home, stop, set home, status
|
||||
|
||||
**UI Features:**
|
||||
- ✅ Voice button with listening state
|
||||
- ✅ Transcript display
|
||||
- ✅ Last command confirmation
|
||||
- ✅ Collapsible command help
|
||||
- ✅ Mobile responsive design
|
||||
|
||||
---
|
||||
|
||||
### 11. 📊 Mining Statistics Dashboard
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Comprehensive mining analytics and leaderboards.
|
||||
|
||||
**Features:**
|
||||
- Per-turtle mining statistics with block type breakdown
|
||||
- Top miners leaderboard with rankings (🥇🥈🥉)
|
||||
- Time filters (24h, 7 days, 30 days, All time)
|
||||
- Item-specific emoji icons for blocks
|
||||
- All turtles overview grid
|
||||
- Empty state handling
|
||||
|
||||
**UI Features:**
|
||||
- ✅ Total blocks mined display
|
||||
- ✅ Block type breakdown with counts
|
||||
- ✅ Leaderboard with medal rankings
|
||||
- ✅ Time-based filtering
|
||||
- ✅ Summary cards for all turtles
|
||||
- ✅ Responsive grid layouts
|
||||
- ✅ Animated transitions
|
||||
|
||||
---
|
||||
|
||||
### 12. 👥 Turtle Groups Management
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Organize turtles into teams with coordinated commands.
|
||||
|
||||
**Features:**
|
||||
- Create and delete turtle groups
|
||||
- 8 color presets for team identification
|
||||
- Add/remove turtles from groups
|
||||
- Send commands to entire group at once
|
||||
- Member list with status indicators
|
||||
- Group member count tracking
|
||||
|
||||
**UI Features:**
|
||||
- ✅ Group creation form with color picker
|
||||
- ✅ Group cards with member lists
|
||||
- ✅ Add/remove member controls
|
||||
- ✅ Group command buttons (explore, mine, return home, stop)
|
||||
- ✅ Status indicators per turtle
|
||||
- ✅ Success/error message feedback
|
||||
- ✅ Mobile responsive design
|
||||
|
||||
---
|
||||
|
||||
### 13. 📋 Task Queue Management
|
||||
**Status:** ✅ Complete
|
||||
|
||||
Schedule and coordinate multi-turtle tasks.
|
||||
|
||||
**Features:**
|
||||
- Create tasks with 6 types (mine_area, explore, gather, build, transport, clear_area)
|
||||
- Priority system (1-10) with visual labels (Critical, High, Medium, Low)
|
||||
- Coordinate input for area-based tasks
|
||||
- Assign tasks to specific turtles or leave unassigned
|
||||
- Filter by status (all, pending, in_progress, completed, failed)
|
||||
- Task lifecycle management (start, complete, fail, delete)
|
||||
- Result tracking and timestamps
|
||||
|
||||
**UI Features:**
|
||||
- ✅ Task creation form with validation
|
||||
- ✅ Priority slider with color coding
|
||||
- ✅ Coordinate input grid
|
||||
- ✅ Turtle assignment dropdown
|
||||
- ✅ Status filter tabs
|
||||
- ✅ Task cards with actions
|
||||
- ✅ Empty state handling
|
||||
- ✅ Mobile responsive design
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current System Statistics
|
||||
|
||||
**Lines of Code:**
|
||||
- Server: ~650 lines (with database integration)
|
||||
- Client: ~3,500 lines (including new components)
|
||||
- Turtle Lua: ~1,000 lines
|
||||
- Database: ~450 lines
|
||||
- **Total: ~5,600 lines**
|
||||
|
||||
**Features Implemented:**
|
||||
- ✅ Real-time WebSocket communication
|
||||
- ✅ 3D block visualization
|
||||
- ✅ GPS tracking
|
||||
- ✅ Autonomous exploration
|
||||
- ✅ Home position management
|
||||
- ✅ Distance limiting
|
||||
- ✅ Intelligent navigation
|
||||
- ✅ Database persistence
|
||||
- ✅ Inventory management UI
|
||||
- ✅ Mobile-responsive design
|
||||
- ✅ Task queue (backend + frontend)
|
||||
- ✅ Path recording backend
|
||||
- ✅ Mining area backend
|
||||
- ✅ Voice commands
|
||||
- ✅ Mining statistics dashboard
|
||||
- ✅ Turtle groups/teams
|
||||
- ✅ Multi-panel tabbed interface
|
||||
|
||||
**Database Tables:** 11
|
||||
**API Endpoints:** 35+
|
||||
**Supported Devices:** Desktop, Tablet, Mobile
|
||||
**Frontend Components:** 12+
|
||||
**Voice Commands:** 20+
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
1. **Install Dependencies:**
|
||||
```bash
|
||||
cd server && npm install
|
||||
cd ../client && npm install
|
||||
```
|
||||
|
||||
2. **Start Server:**
|
||||
```bash
|
||||
cd server && npm start
|
||||
```
|
||||
|
||||
3. **Start Client:**
|
||||
```bash
|
||||
cd client && npm run dev
|
||||
```
|
||||
|
||||
4. **Deploy Lua Files:**
|
||||
- Copy `turtle.lua` to your Minecraft turtle
|
||||
- Copy `webbridge.lua` to a computer with wireless modem
|
||||
- Configure SERVER_URL in webbridge.lua
|
||||
|
||||
5. **Run Turtle:**
|
||||
```lua
|
||||
turtle.lua
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### High Priority
|
||||
1. ✅ Database persistence - **DONE**
|
||||
2. ✅ Inventory UI - **DONE**
|
||||
3. ✅ Mobile responsive - **DONE**
|
||||
4. 🔄 Path recording UI - Backend ready
|
||||
5. 🔄 Task coordination UI - Backend ready
|
||||
|
||||
### Medium Priority
|
||||
6. Mining area visualization
|
||||
7. Task scheduling interface
|
||||
8. Multi-turtle work distribution
|
||||
|
||||
### Low Priority
|
||||
9. Authentication system
|
||||
10. User permissions
|
||||
11. Advanced analytics
|
||||
12. Performance monitoring
|
||||
|
||||
---
|
||||
|
||||
## 💡 Tips for Use
|
||||
|
||||
**For Best Performance:**
|
||||
- Use GPS hosts for accurate positioning
|
||||
- Keep turtles within 200 blocks of home
|
||||
- Use webbridge computer as dedicated proxy
|
||||
- Run server on local network for best latency
|
||||
|
||||
**For Mobile Use:**
|
||||
- Use landscape mode for split view
|
||||
- Swipe to scroll turtle list
|
||||
- Long-press inventory slots for info
|
||||
- Use tab buttons to switch views
|
||||
|
||||
**For Multiple Turtles:**
|
||||
- Give each turtle a unique ID
|
||||
- Set different home positions
|
||||
- Use task queue for coordination
|
||||
- Monitor from task dashboard
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
MIT License - Feel free to modify and distribute!
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions welcome! Areas needing work:
|
||||
- Frontend for path recording
|
||||
- Task queue UI
|
||||
- Mining area visualization
|
||||
- Authentication system
|
||||
- Performance optimizations
|
||||
- Additional turtle commands
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** February 19, 2026
|
||||
**Version:** 2.0.0
|
||||
**Status:** Production Ready ✨
|
||||
278
README.md
278
README.md
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user