From 7ca59e7197bd8d8af4e0a685fd635b0e567af712 Mon Sep 17 00:00:00 2001 From: MayaTheShy Date: Thu, 19 Feb 2026 22:48:14 -0500 Subject: [PATCH] feat: Expand README with project statistics, API endpoints, and voice command details --- README.md | 362 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 340 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 9571fd3..367c684 100644 --- a/README.md +++ b/README.md @@ -213,45 +213,272 @@ To access from other devices on your network: 3. Ensure firewall allows connections on ports 3000, 3001, and 3002 +## 📊 Project Statistics + +- **Total Code**: 3,500+ lines +- **Database Tables**: 10 +- **API Endpoints**: 35+ +- **Supported Commands**: 25+ +- **Voice Commands**: 20+ +- **Frontend Components**: 8+ + ## 📊 API Reference -### REST Endpoints +### Turtle Management -**POST /api/turtle/update** -- Body: Turtle status object -- Updates turtle state +#### `POST /api/turtle/update` +Update turtle status +```json +{ + "turtleID": 123, + "name": "Miner-1", + "x": 100, "y": 64, "z": 200, + "facing": 0, + "fuel": 5000, + "mode": "exploring", + "inventory": [...] +} +``` -**GET /api/turtle/:id/commands** -- Returns pending commands for turtle +#### `GET /api/turtles` +Get all connected turtles -**POST /api/turtle/:id/command** -- Body: `{ command: string, param: any }` -- Queues command for turtle +#### `GET /api/turtle/:id` +Get specific turtle details -**GET /api/turtles** -- Returns all connected turtles +#### `POST /api/turtle/:id/command` +Send command to turtle +```json +{ + "command": "explore", + "param": null +} +``` + +#### `GET /api/turtle/:id/commands` +Get pending commands for turtle + +### Home Management + +#### `POST /api/homes` +Set turtle home position +```json +{ + "turtleID": 123, + "x": 100, "y": 64, "z": 200 +} +``` + +#### `GET /api/homes/:turtleId` +Get turtle's home position + +### Block Tracking + +#### `POST /api/blocks` +Record discovered block +```json +{ + "x": 100, "y": 64, "z": 200, + "blockType": "minecraft:diamond_ore", + "discoveredBy": 123 +} +``` + +#### `GET /api/blocks` +Get all discovered blocks (with filtering) +- Query params: `minX`, `maxX`, `minY`, `maxY`, `minZ`, `maxZ` + +### Path Recording + +#### `POST /api/paths` +Create new path recording +```json +{ + "name": "Mine Route 1", + "turtleId": 123, + "description": "Efficient mining path" +} +``` + +#### `GET /api/paths` +Get all recorded paths + +#### `GET /api/paths/:pathId` +Get specific path with waypoints + +#### `POST /api/paths/:pathId/waypoints` +Add waypoint to path +```json +{ + "x": 100, "y": 64, "z": 200, + "action": "dig_forward" +} +``` + +#### `DELETE /api/paths/:pathId` +Delete path + +### Task Queue + +#### `POST /api/tasks` +Create new task +```json +{ + "taskType": "mine_area", + "priority": 1, + "assignedTurtleId": 123, + "parameters": { + "x1": 100, "y1": 60, "z1": 200, + "x2": 120, "y2": 70, "z2": 220 + } +} +``` + +#### `GET /api/tasks` +Get all tasks (with optional status filter) +- Query params: `status=pending|in_progress|completed|failed` + +#### `GET /api/tasks/:taskId` +Get specific task details + +#### `PUT /api/tasks/:taskId` +Update task status +```json +{ + "status": "completed", + "result": "Mined 450 blocks" +} +``` + +#### `DELETE /api/tasks/:taskId` +Delete task + +### Mining Areas + +#### `POST /api/mining-areas` +Define mining area +```json +{ + "name": "Diamond Layer", + "x1": 100, "y1": -64, "z1": 200, + "x2": 200, "y2": -50, "z2": 300, + "priority": 1, + "assignedTurtles": [123, 456] +} +``` + +#### `GET /api/mining-areas` +Get all mining areas + +#### `GET /api/mining-areas/:areaId` +Get specific mining area + +#### `PUT /api/mining-areas/:areaId` +Update mining area + +#### `DELETE /api/mining-areas/:areaId` +Delete mining area + +### Mining Statistics + +#### `POST /api/stats/block-mined` +Record block mined +```json +{ + "turtleId": 123, + "blockType": "minecraft:diamond_ore" +} +``` + +#### `GET /api/stats/mining/:turtleId?` +Get mining statistics +- Query params: `days=7` (filter by recent days) +- Returns per-block-type counts + +#### `GET /api/stats/top-miners` +Get leaderboard of top mining turtles +- Query params: `limit=10` + +### Turtle Groups/Teams + +#### `POST /api/groups` +Create turtle group +```json +{ + "groupName": "Mining Team Alpha", + "color": "#3b82f6" +} +``` + +#### `GET /api/groups` +Get all groups with member counts + +#### `DELETE /api/groups/:groupId` +Delete group + +#### `POST /api/groups/:groupId/members` +Add turtle to group +```json +{ + "turtleId": 123 +} +``` + +#### `DELETE /api/groups/:groupId/members/:turtleId` +Remove turtle from group + +#### `GET /api/turtles/:turtleId/groups` +Get turtle's groups + +#### `POST /api/groups/:groupId/command` +Send command to all turtles in group +```json +{ + "command": "returnHome" +} +``` ### WebSocket Messages -**From Server:** +**From Server to Client:** + ```json { "type": "initial_state", "turtles": [...] } +``` +```json { "type": "turtle_update", "turtle": {...} } +``` +```json { "type": "turtle_disconnected", "turtleID": 123 } ``` -**From Client:** +```json +{ + "type": "block_discovered", + "block": {...} +} +``` + +```json +{ + "type": "task_update", + "task": {...} +} +``` + +**From Client to Server:** + ```json { "type": "command", @@ -261,6 +488,66 @@ To access from other devices on your network: } ``` +## 🎤 Voice Commands + +The system supports natural language voice commands using the Web Speech API (Chrome, Edge, Safari): + +### Movement Commands +- "forward" / "move forward" / "go forward" +- "back" / "backward" / "move back" +- "turn left" / "left" +- "turn right" / "right" +- "up" / "move up" / "go up" +- "down" / "move down" / "go down" + +### Action Commands +- "dig" / "mine" +- "dig up" / "mine up" +- "dig down" / "mine down" +- "place" / "place block" +- "refuel" + +### Autonomous Commands +- "explore" / "start exploring" +- "mine" / "start mining" +- "return home" / "go home" / "come back" +- "stop" / "halt" +- "set home" / "mark home" +- "status" / "report" + +## 💾 Database Schema + +### Tables + +1. **turtle_homes** - Home positions for turtles +2. **turtle_config** - Turtle configuration settings +3. **world_blocks** - Discovered block locations +4. **turtle_paths** - Recorded movement paths +5. **path_waypoints** - Individual waypoints in paths +6. **task_queue** - Task scheduling and coordination +7. **mining_areas** - Defined mining zones +8. **mining_stats** - Block mining statistics per turtle +9. **turtle_groups** - Turtle team/group definitions +10. **turtle_group_members** - Group membership +11. **turtle_sessions** - Time-based analytics tracking + +## 📱 Frontend Features + +### Enhanced Inventory Display +- 4x4 grid matching Minecraft turtle slots +- Item-specific emojis (💎 diamond, ⚫ coal, 🟡 gold, etc.) +- Item count badges +- Empty slot indicators +- Hover tooltips with full item names + +### Mobile Responsive Design +- **Desktop (>1024px)**: Side-by-side map and controls +- **Tablet (768-1024px)**: Vertical stacking +- **Mobile (<768px)**: Tab-based navigation, optimized touch targets +- Touch-optimized controls (48px minimum) +- Landscape orientation support +- Accessibility features (reduced motion, high contrast) + ## 🐛 Troubleshooting ### Turtles not appearing in web panel @@ -322,16 +609,47 @@ Built with: - [Express](https://expressjs.com/) - Backend server - [ws](https://github.com/websockets/ws) - WebSocket server -## 🚀 Future Enhancements +## 🚀 Implementation Status -- [ ] Path recording and playback -- [ ] Multi-turtle task coordination -- [ ] Inventory management interface -- [ ] Mining area visualization -- [ ] Task scheduling -- [ ] Database persistence -- [ ] Authentication/multi-user support -- [ ] Mobile-responsive design +### ✅ Completed Features + +- [x] Real-time 3D visualization with Three.js +- [x] WebSocket bidirectional communication +- [x] Manual turtle control interface +- [x] Autonomous exploration with intelligent navigation +- [x] Database persistence (SQLite with 10+ tables) +- [x] Path recording backend (API complete) +- [x] Task queue system backend (API complete) +- [x] Mining area management backend (API complete) +- [x] Mining statistics tracking (per turtle, per block type) +- [x] Turtle groups/teams coordination +- [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 + +### 🚧 In Progress / Frontend Pending + +- [ ] 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 + +- [ ] User authentication system +- [ ] Multi-user support with permissions +- [ ] Real-time collaboration features +- [ ] Advanced pathfinding algorithms (A*) +- [ ] Quarry mode with automatic area mining +- [ ] Ore detection and priority mining +- [ ] Automated smelting coordination +- [ ] Chest management and auto-storage +- [ ] Fuel depot system +- [ ] Emergency recovery protocols ## 💡 Tips