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

feat: Expand README with project statistics, API endpoints, and voice command details

Browse Source
This commit is contained in:
MayaTheShy
2026-02-19 22:48:14 -05:00
parent 42a626807b
commit 7ca59e7197
1 changed files with 340 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
README.md
View File

@@ -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