feat: Add comprehensive feature documentation and overview of key files in README.md
This commit is contained in:
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/
|
remoteturtle/
|
||||||
├── server/ # Node.js backend
|
├── server/ # Node.js backend (650+ lines)
|
||||||
│ ├── server.js # Express + WebSocket server
|
│ ├── server.js # Express REST API + WebSocket server
|
||||||
│ └── package.json
|
│ ├── database.js # SQLite database layer (450+ lines)
|
||||||
├── client/ # React frontend
|
│ ├── turtle_control.db # SQLite database file
|
||||||
|
│ ├── package.json
|
||||||
|
│ └── node_modules/
|
||||||
|
│
|
||||||
|
├── client/ # React frontend (1,500+ lines)
|
||||||
│ ├── src/
|
│ ├── src/
|
||||||
│ │ ├── components/
|
│ │ ├── components/
|
||||||
│ │ │ ├── Map3D.jsx # 3D map visualization
|
│ │ │ ├── Map3D.jsx # Three.js 3D visualization
|
||||||
│ │ │ ├── ControlPanel.jsx # Control interface
|
│ │ │ ├── ControlPanel.jsx # Main control interface
|
||||||
│ │ │ └── ControlPanel.css
|
│ │ │ ├── ControlPanel.css # Control panel styles
|
||||||
|
│ │ │ ├── VoiceControl.jsx # Voice command interface (NEW)
|
||||||
|
│ │ │ └── VoiceControl.css # Voice control styles (NEW)
|
||||||
│ │ ├── store/
|
│ │ ├── store/
|
||||||
│ │ │ └── turtleStore.js # Zustand state management
|
│ │ │ └── turtleStore.js # Zustand state management
|
||||||
│ │ ├── App.jsx
|
│ │ ├── App.jsx # Main application component
|
||||||
│ │ ├── App.css
|
│ │ ├── App.css # Global styles + responsive design
|
||||||
│ │ ├── main.jsx
|
│ │ ├── main.jsx # React entry point
|
||||||
│ │ └── index.css
|
│ │ └── index.css # Base styles
|
||||||
│ ├── index.html
|
│ ├── index.html
|
||||||
│ ├── vite.config.js
|
│ ├── vite.config.js # Vite configuration
|
||||||
│ └── package.json
|
│ ├── package.json
|
||||||
├── webbridge.lua # ComputerCraft bridge script
|
│ └── node_modules/
|
||||||
├── turtle.lua # Advanced turtle control script
|
│
|
||||||
├── pocketremote.lua # Pocket computer interface
|
├── webbridge.lua # ComputerCraft HTTP bridge (200+ lines)
|
||||||
└── README.md
|
├── 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
|
## 🎮 Usage
|
||||||
|
|
||||||
### Web Interface
|
### 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**:
|
1. **View Modes**:
|
||||||
- **Split View**: See both map and control panel
|
- **Split View**: See both map and control panel
|
||||||
- **Map Only**: Full-screen 3D map
|
- **Map Only**: Full-screen 3D map
|
||||||
@@ -153,14 +220,44 @@ remoteturtle/
|
|||||||
|
|
||||||
### In-Game Commands
|
### In-Game Commands
|
||||||
|
|
||||||
**Turtle Commands** (via pocket computer or web):
|
**Turtle Commands** (via pocket computer, web, or voice):
|
||||||
- `explore` - Start exploration mode
|
|
||||||
- `returnHome` - Return to home position
|
**Movement:**
|
||||||
- `stop` - Stop current operation
|
- `forward/back/up/down` - Directional movement
|
||||||
- `forward/back/up/down` - Movement
|
|
||||||
- `turnLeft/turnRight` - Rotation
|
- `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
|
- `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
|
## 🔧 Configuration
|
||||||
|
|
||||||
@@ -215,12 +312,14 @@ To access from other devices on your network:
|
|||||||
|
|
||||||
## 📊 Project Statistics
|
## 📊 Project Statistics
|
||||||
|
|
||||||
- **Total Code**: 3,500+ lines
|
- **Total Code**: 5,600+ lines
|
||||||
- **Database Tables**: 10
|
- **Database Tables**: 11
|
||||||
- **API Endpoints**: 35+
|
- **API Endpoints**: 35+
|
||||||
- **Supported Commands**: 25+
|
- **Supported Commands**: 25+
|
||||||
- **Voice Commands**: 20+
|
- **Voice Commands**: 20+
|
||||||
- **Frontend Components**: 8+
|
- **Frontend Components**: 12+
|
||||||
|
- **Task Types**: 6
|
||||||
|
- **Color Presets**: 8
|
||||||
|
|
||||||
## 📊 API Reference
|
## 📊 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
|
### Turtles not appearing in web panel
|
||||||
|
|
||||||
1. Check that webbridge.lua is running
|
1. **Check webbridge is running**
|
||||||
2. Verify SERVER_URL is correct
|
- Verify webbridge.lua is active in Minecraft
|
||||||
3. Check turtle.lua is running with wireless modem equipped
|
- Check for error messages in the Minecraft console
|
||||||
4. Verify all scripts are using same channel numbers
|
|
||||||
|
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
|
### Connection issues
|
||||||
|
|
||||||
1. Check server is running: `http://localhost:3001/api/turtles`
|
1. **Server not responding**
|
||||||
2. Check firewall settings
|
- Check server is running: `http://localhost:3001/api/turtles`
|
||||||
3. Verify ports 3001 and 3002 are not in use
|
- Verify no port conflicts (3001, 3002, 3000)
|
||||||
4. Check browser console for WebSocket errors
|
- 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
|
### GPS not working
|
||||||
|
|
||||||
1. Set up GPS hosts in Minecraft (requires 4 computers)
|
1. **Set up GPS hosts**
|
||||||
2. Position them in a square pattern at high Y level
|
- Requires 4 computers in Minecraft
|
||||||
3. Each must run `gps host X Y Z` with their coordinates
|
- 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
|
## 🎨 Customization
|
||||||
|
|
||||||
@@ -617,26 +805,24 @@ Built with:
|
|||||||
- [x] WebSocket bidirectional communication
|
- [x] WebSocket bidirectional communication
|
||||||
- [x] Manual turtle control interface
|
- [x] Manual turtle control interface
|
||||||
- [x] Autonomous exploration with intelligent navigation
|
- [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] 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 area management backend (API complete)
|
||||||
- [x] Mining statistics tracking (per turtle, per block type)
|
- [x] Mining statistics tracking (backend + frontend complete)
|
||||||
- [x] Turtle groups/teams coordination
|
- [x] Turtle groups/teams coordination (backend + frontend complete)
|
||||||
- [x] Voice command interface (Web Speech API, 20+ commands)
|
- [x] Voice command interface (Web Speech API, 20+ commands)
|
||||||
- [x] Enhanced inventory display (4x4 grid with emojis)
|
- [x] Enhanced inventory display (4x4 grid with emojis)
|
||||||
- [x] Mobile-responsive design (desktop/tablet/mobile)
|
- [x] Mobile-responsive design (desktop/tablet/mobile)
|
||||||
- [x] Position memory and visited tracking
|
- [x] Position memory and visited tracking
|
||||||
- [x] Stuck detection and recovery
|
- [x] Stuck detection and recovery
|
||||||
- [x] Session-based analytics
|
- [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)
|
- [ ] Path recording UI (playback controls, visualization)
|
||||||
- [ ] Task coordination UI (task creation, queue display)
|
|
||||||
- [ ] Mining area visualization (3D overlays on map)
|
- [ ] Mining area visualization (3D overlays on map)
|
||||||
- [ ] Statistics dashboard (charts, leaderboards)
|
|
||||||
- [ ] Group management UI (create/manage teams)
|
|
||||||
|
|
||||||
### 📋 Future Enhancements
|
### 📋 Future Enhancements
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user