15 KiB
15 KiB
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
{
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
{
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