forked from Rockachopa/the-matrix
81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
# Timmy Tower World
|
|
|
|
A Three.js 3D visualization of the Timmy agent network. Agents appear as
|
|
glowing icosahedra connected by lines, pulsing as they process jobs. A
|
|
matrix-rain particle effect fills the background.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev # Vite dev server with hot reload → http://localhost:5173
|
|
npm run build # Production bundle → dist/
|
|
npm run preview # Serve dist/ locally
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set these in a `.env.local` file (not committed):
|
|
|
|
```
|
|
VITE_WS_URL=ws://localhost:8080/ws/agents
|
|
```
|
|
|
|
Leave `VITE_WS_URL` unset to run in offline/demo mode (agents animate but
|
|
receive no live updates).
|
|
|
|
## Adding custom agents
|
|
|
|
**Edit one file only: `js/agent-defs.js`**
|
|
|
|
```js
|
|
export const AGENT_DEFS = [
|
|
// existing agents …
|
|
{
|
|
id: 'zeta', // unique string — matches WebSocket message agentId
|
|
label: 'ZETA', // displayed in the 3D HUD
|
|
color: 0xff00aa, // hex integer (0xRRGGBB)
|
|
role: 'observer', // shown under the label sprite
|
|
direction: 'east', // cardinal facing direction (north/east/south/west)
|
|
x: 12, // world-space position (horizontal)
|
|
z: 0, // world-space position (depth)
|
|
},
|
|
];
|
|
```
|
|
|
|
Nothing else needs to change. `agents.js` reads positions from `x`/`z`,
|
|
and `websocket.js` reads colors and labels — both derive everything from
|
|
`AGENT_DEFS`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
js/
|
|
├── agent-defs.js ← single source of truth: id, label, color, role, position
|
|
├── agents.js ← Three.js scene objects, animation loop
|
|
├── effects.js ← matrix rain particles, starfield
|
|
├── interaction.js ← OrbitControls (pan, zoom, rotate)
|
|
├── main.js ← entry point, rAF loop
|
|
├── ui.js ← DOM HUD overlay (FPS, agent states, chat)
|
|
└── websocket.js ← WebSocket reconnect, message dispatch
|
|
```
|
|
|
|
## WebSocket protocol
|
|
|
|
The backend sends JSON messages on the agents channel:
|
|
|
|
| `type` | Fields | Effect |
|
|
|-----------------|-------------------------------------|-------------------------------|
|
|
| `agent_state` | `agentId`, `state` | Update agent visual state |
|
|
| `job_started` | `agentId`, `jobId` | Increment job counter, pulse |
|
|
| `job_completed` | `agentId`, `jobId` | Decrement job counter |
|
|
| `chat` | `agentId`, `text` | Append to chat panel |
|
|
|
|
Agent states: `idle` (dim pulse) · `active` (bright pulse + fast ring spin)
|
|
|
|
## Stack
|
|
|
|
- [Three.js](https://threejs.org) 0.171.0 — 3D rendering
|
|
- [Vite](https://vitejs.dev) 5 — build + dev server
|
|
- `crypto.randomUUID()` — secure client session IDs (no external library)
|