292 lines
15 KiB
Markdown
292 lines
15 KiB
Markdown
# System Architecture Diagram
|
|
|
|
## High-Level Overview
|
|
|
|
```
|
|
╔═══════════════════════════╗
|
|
║ YOUR COMPUTER ║
|
|
║ ║
|
|
┌────────────────────║──────────────────────────║────────────────┐
|
|
│ ║ ║ │
|
|
│ ┏━━━━━━━━━━━━━━┓ ║ ┏━━━━━━━━━━━━━━━━━━━┓ ║ ┏━━━━━━━━━━┓ │
|
|
│ ┃ Browser ┃ ║ ┃ Node.js Server ┃ ║ ┃ Minecraft┃ │
|
|
│ ┃ ┃ ║ ┃ ┃ ║ ┃ ┃ │
|
|
│ ┃ React App ┃◄─╫─►┃ Express + WS ┃◄─╫─►┃ Bridge ┃ │
|
|
│ ┃ ┃ ║ ┃ ┃ ║ ┃ Computer ┃ │
|
|
│ ┃ :3000 ┃ ║ ┃ :3001 / :3002 ┃ ║ ┃ ┃ │
|
|
│ ┗━━━━━━━━━━━━━━┛ ║ ┗━━━━━━━━━━━━━━━━━━━┛ ║ ┗━━━━━━━━━━┛ │
|
|
│ ║ ║ │ │
|
|
└────────────────────║──────────────────────────║───────┼────────┘
|
|
╚═══════════════════════════╝ │
|
|
│ Modem
|
|
│ Wireless
|
|
↓
|
|
┏━━━━━━━━━━━━━━┓
|
|
┃ Turtle 1 ┃
|
|
┃ Turtle 2 ┃
|
|
┃ Turtle N ┃
|
|
┗━━━━━━━━━━━━━━┛
|
|
```
|
|
|
|
## Communication Flow
|
|
|
|
### Status Updates (Turtle → Web)
|
|
|
|
```
|
|
Turtle Bridge Server Web Client
|
|
│ │ │ │
|
|
│ Status Broadcast │ │ │
|
|
├──────modem───────>│ │ │
|
|
│ (channel 102) │ │ │
|
|
│ │ HTTP POST │ │
|
|
│ ├───────────────────>│ │
|
|
│ │ /api/turtle/update│ │
|
|
│ │ │ WebSocket Broadcast │
|
|
│ │ ├─────────────────────>│
|
|
│ │ │ turtle_update │
|
|
│ │ │ │
|
|
│ │ │ ┌───┴───┐
|
|
│ │ │ │Update │
|
|
│ │ │ │3D Map │
|
|
│ │ │ └───────┘
|
|
```
|
|
|
|
### Commands (Web → Turtle)
|
|
|
|
```
|
|
Web Client Server Bridge Turtle
|
|
│ │ │ │
|
|
│ Click "Explore" │ │ │
|
|
├─────WebSocket────>│ │ │
|
|
│ command msg │ │ │
|
|
│ │ Queue Command │ │
|
|
│ ├──(in memory) │ │
|
|
│ │ │ │
|
|
│ │ │ Poll for Commands │
|
|
│ │ HTTP GET │ │
|
|
│ │<──────────────────┤ │
|
|
│ │/api/turtle/:id/.. │ │
|
|
│ │ │ │
|
|
│ │ Return Commands │ │
|
|
│ ├──────────────────>│ │
|
|
│ │ JSON │ │
|
|
│ │ │ Forward via Modem │
|
|
│ │ ├──────────────────>│
|
|
│ │ │ (channel 100) │
|
|
│ │ │ │
|
|
│ │ │ ┌───┴────┐
|
|
│ │ │ │Execute │
|
|
│ │ │ │Command │
|
|
│ │ │ └────────┘
|
|
```
|
|
|
|
## Component Details
|
|
|
|
### React Frontend (Port 3000)
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ App.jsx │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ View Controls (Split/Map/..) │ │
|
|
│ └───────────────────────────────┘ │
|
|
│ │
|
|
│ ┌────────────┬──────────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ Control │ Map3D.jsx │ │
|
|
│ │ Panel │ │ │
|
|
│ │ .jsx │ ┌────────────┐ │ │
|
|
│ │ │ │ Three.js │ │ │
|
|
│ │ - Turtle │ │ Canvas │ │ │
|
|
│ │ Cards │ │ │ │ │
|
|
│ │ - Details │ │ - Turtles │ │ │
|
|
│ │ - Commands│ │ - Grid │ │ │
|
|
│ │ - Manual │ │ - Camera │ │ │
|
|
│ │ Control │ │ │ │ │
|
|
│ │ │ └────────────┘ │ │
|
|
│ └────────────┴──────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ turtleStore.js │ │
|
|
│ │ - WebSocket connection │ │
|
|
│ │ - State management │ │
|
|
│ │ - Command sending │ │
|
|
│ └───────────────────────────────┘ │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### Node.js Server (Ports 3001, 3002)
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ server.js │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ Express HTTP Server │ │
|
|
│ │ Port: 3001 │ │
|
|
│ │ │ │
|
|
│ │ POST /api/turtle/update │ │
|
|
│ │ GET /api/turtle/:id/commands│ │
|
|
│ │ POST /api/turtle/:id/command │ │
|
|
│ │ GET /api/turtles │ │
|
|
│ └───────────────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ WebSocket Server │ │
|
|
│ │ Port: 3002 │ │
|
|
│ │ │ │
|
|
│ │ - Broadcast turtle updates │ │
|
|
│ │ - Receive commands │ │
|
|
│ │ - Track connected clients │ │
|
|
│ └───────────────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ In-Memory Data Store │ │
|
|
│ │ │ │
|
|
│ │ turtleData Map: │ │
|
|
│ │ turtleID → state │ │
|
|
│ │ - position │ │
|
|
│ │ - fuel │ │
|
|
│ │ - inventory │ │
|
|
│ │ - pendingCommands[] │ │
|
|
│ └───────────────────────────────┘ │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### Minecraft Components
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ webbridge.lua │
|
|
│ (Bridge Computer) │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ Modem Listener │ │
|
|
│ │ Channels: 101, 102 │ │
|
|
│ └───────────────────────────────┘ │
|
|
│ ↕ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ HTTP Client │ │
|
|
│ │ - POST status to server │ │
|
|
│ │ - GET commands from server │ │
|
|
│ └───────────────────────────────┘ │
|
|
└─────────────────────────────────────┘
|
|
↕ (modem)
|
|
┌─────────────────────────────────────┐
|
|
│ turtle.lua │
|
|
│ (Each Turtle) │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ Command Processor │ │
|
|
│ │ Listen: channel 100 │ │
|
|
│ └───────────────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ Status Broadcaster │ │
|
|
│ │ Send: channel 102 (every 5s) │ │
|
|
│ └───────────────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────┐ │
|
|
│ │ Autonomous AI │ │
|
|
│ │ - Exploration │ │
|
|
│ │ - Mining │ │
|
|
│ │ - Pathfinding │ │
|
|
│ │ - Fuel management │ │
|
|
│ └───────────────────────────────┘ │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
## Network Ports
|
|
|
|
```
|
|
Port 3000 → React Dev Server (Vite)
|
|
Port 3001 → Express HTTP API
|
|
Port 3002 → WebSocket Server
|
|
|
|
Modem Channels:
|
|
100 → Commands to Turtles
|
|
101 → Responses from Turtles
|
|
102 → Status Updates
|
|
```
|
|
|
|
## Data Models
|
|
|
|
### Turtle State Object
|
|
|
|
```javascript
|
|
{
|
|
turtleID: 123,
|
|
mode: "mining", // idle, exploring, mining, returning, manual
|
|
position: {
|
|
x: 100,
|
|
y: 64,
|
|
z: 200
|
|
},
|
|
homePosition: {
|
|
x: 95,
|
|
y: 64,
|
|
z: 195
|
|
},
|
|
fuel: 5000,
|
|
inventory: [
|
|
{ slot: 1, name: "minecraft:coal_ore", count: 32 },
|
|
{ slot: 2, name: "minecraft:iron_ore", count: 16 }
|
|
],
|
|
lastUpdate: 1234567890,
|
|
pendingCommands: [
|
|
{ command: "explore", param: null, timestamp: 1234567890 }
|
|
]
|
|
}
|
|
```
|
|
|
|
### Command Message
|
|
|
|
```javascript
|
|
{
|
|
command: "explore", // explore, mine, returnHome, stop, forward, etc.
|
|
param: null, // optional parameter
|
|
target: 123 // turtle ID (for Lua) or turtleID (for web)
|
|
}
|
|
```
|
|
|
|
## Technology Stack Summary
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Presentation Layer │
|
|
│ - React 18 │
|
|
│ - Three.js / React Three Fiber │
|
|
│ - CSS3 │
|
|
└─────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────┐
|
|
│ State Management │
|
|
│ - Zustand │
|
|
│ - WebSocket API │
|
|
└─────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────┐
|
|
│ Backend Services │
|
|
│ - Node.js │
|
|
│ - Express.js │
|
|
│ - ws (WebSocket library) │
|
|
└─────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────┐
|
|
│ Game Integration │
|
|
│ - ComputerCraft Lua │
|
|
│ - HTTP API │
|
|
│ - Modem Wireless │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
This architecture provides:
|
|
- ✅ Real-time bidirectional communication
|
|
- ✅ Scalable to multiple turtles
|
|
- ✅ Web-based interface accessible from any device
|
|
- ✅ Backward compatible with existing Lua scripts
|
|
- ✅ Clean separation of concerns
|
|
- ✅ Easy to extend and modify
|