MayaTheShy/Inventory-Manager-CC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md: enhance documentation with architecture and component details

Browse Source
This commit is contained in:
MayaTheShy
2026-03-22 00:53:21 -04:00
parent bee1019fd6
commit 582c92f090
1 changed files with 131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
README.md
View File

@@ -1,2 +1,133 @@
# Inventory-Manager-CC
A Minecraft inventory management system built on [CC:Tweaked](https://tweaked.cc/). Automates storage sorting, smelting, crafting, and item dispensing across networked computers, turtles, and peripherals — with an optional web dashboard for remote monitoring and control.
## Architecture
```
┌──────────────────────────────────────────────────────────────┐
│ Minecraft World │
│ │
│ ┌──────────────────────┐ modem channels 4200-4204 │
│ │ inventoryManager.lua │◄──────────────────────┐ │
│ │ (master computer) │───────────────────────┤ │
│ └──────┬───────────────┘ │ │
│ │ peripherals │ │
│ ┌─────┴──────┬───────────┐ ┌──────────┴────────┐ │
│ │ chests / │ furnaces │ │ inventoryClient │ │
│ │ barrels │ smokers │ │ (display client) │ │
│ │ │ blasters │ └───────────────────┘ │
│ └────────────┴───────────┘ │
│ ┌──────────────────┐ ┌────────────────────┐ │
│ │ craftingTurtle.lua│ │dropperController │ │
│ │ (auto-craft) │ │ (redstone pulses) │ │
│ └──────────────────┘ └────────────────────┘ │
│ ┌──────────────────────┐ HTTP │
│ │ inventoryWebBridge.lua│─────────────────┐ │
│ └──────────────────────┘ │ │
└────────────────────────────────────────────┼─────────────────┘
▼
┌──────────────────┐
│ Web Server :3001 │ ◄── SQLite
└────────┬─────────┘
│ WebSocket + REST
┌────────▼─────────┐
│ React Dashboard │ (port 80)
└──────────────────┘
```
## Components
### In-Game (Lua)
| File | Role | Description |
|------|------|-------------|
| `inventoryManager.lua` | **Master Controller** | The brain — scans all networked chests, auto-sorts/defrags items, auto-smelts ores and food, dispatches crafting jobs, manages composting, fires alerts on low stock, and broadcasts state on modem channel 4200. Requires an attached monitor and wired modem. |
| `inventoryClient.lua` | **Display Client** | A read-only dashboard that mirrors the master's state on a separate monitor. Supports search, pagination, and sending item orders back to the master. |
| `craftingTurtle.lua` | **Crafting Worker** | Runs on a Crafting Turtle. When the master places ingredients in its grid, it auto-crafts and reports results. Must be connected to the master via wired network. |
| `dropperController.lua` | **Dropper Driver** | Pulses redstone to fire items out of a dropper block until empty. Runs on a computer adjacent to the dropper. |
| `inventoryWebBridge.lua` | **Web Bridge** | Bridges the in-game modem network to the external web server over HTTP/WebSocket. Forwards state from the master and relays commands from the web dashboard back into the game. |
| `listDevicesByType.lua` | **Diagnostic Utility** | Lists all peripherals on the wired network grouped by type. Useful for discovering connected chests, furnaces, etc. |
### Web Stack (Docker)
| Component | Description |
|-----------|-------------|
| **Server** (`web/server/`) | Express + WebSocket API backed by SQLite. Receives state from the Lua bridge, persists item history, and pushes real-time updates to browser clients. |
| **Client** (`web/client/`) | React SPA (Vite + Zustand) served via Nginx. Tabbed panels for inventory grid, smelting, crafting, analytics, alerts, and settings. |
| **Docker Compose** | Orchestrates server and client containers on an internal bridge network. Only port 80 is exposed; the Nginx client proxies API/WS requests to the server. |
## Quick Start
### Prerequisites
- Minecraft with [CC:Tweaked](https://tweaked.cc/) installed
- A CC:Tweaked computer with a wired modem and monitor attached
- HTTP access enabled in the CC:Tweaked config (for the web bridge)
### 1. Install the Master Controller
On your main CC:Tweaked computer (with the monitor and wired modem), open the terminal and run:
```
wget https://git.spatulaa.com/MayaTheShy/Inventory-Manager-CC/raw/branch/main/inventoryManager.lua startup.lua
```
This downloads `inventoryManager.lua` and saves it as `startup.lua` so it runs automatically on boot. Reboot the computer or run `startup.lua` to start.
### 2. Install a Display Client (Optional)
On a separate CC:Tweaked computer with a monitor:
```
wget https://git.spatulaa.com/MayaTheShy/Inventory-Manager-CC/raw/branch/main/inventoryClient.lua startup.lua
```
### 3. Install the Crafting Turtle (Optional)
On a **Crafting Turtle** connected to the wired network:
```
wget https://git.spatulaa.com/MayaTheShy/Inventory-Manager-CC/raw/branch/main/craftingTurtle.lua startup.lua
```
### 4. Install the Dropper Controller (Optional)
On a computer adjacent to a dropper block:
```
wget https://git.spatulaa.com/MayaTheShy/Inventory-Manager-CC/raw/branch/main/dropperController.lua startup.lua
```
### 5. Install the Web Bridge (Optional)
On any CC:Tweaked computer with a wired modem and HTTP access:
```
wget https://git.spatulaa.com/MayaTheShy/Inventory-Manager-CC/raw/branch/main/inventoryWebBridge.lua startup.lua
```
Configure the web server URL by editing `.webbridge_config` on the computer, or it will default to `http://localhost`.
### 6. Start the Web Dashboard (Optional)
On the host machine, navigate to the `web/` directory and run:
```bash
docker compose up -d --build
```
The dashboard will be available at `http://localhost` on port 80.
## Modem Channels
| Channel | Purpose |
|---------|---------|
| 4200 | Master → Clients/Bridge (state broadcast) |
| 4201 | Clients/Bridge → Master (orders & commands) |
| 4203 | Master → Crafting Turtle (craft requests) |
| 4204 | Crafting Turtle → Master (craft results) |
## License
See [LICENSE](LICENSE) for details.