Compare commits
1 Commits
burn/672-1
...
fix/677
| Author | SHA1 | Date | |
|---|---|---|---|
| f7843ae87f |
242
evennia/timmy_world/GENOME.md
Normal file
242
evennia/timmy_world/GENOME.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# GENOME.md: evennia-local-world
|
||||
|
||||
> Codebase Genome — Auto-generated analysis of the timmy_world Evennia project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Name:** timmy_world
|
||||
**Framework:** Evennia 6.0 (MUD/MUSH engine)
|
||||
**Purpose:** Tower MUD world with spatial memory. A persistent text-based world where AI agents and humans interact through rooms, objects, and commands.
|
||||
**Language:** Python 3.11
|
||||
**Lines of Code:** ~40 files, ~2,500 lines
|
||||
|
||||
This is a custom Evennia game world built for the Timmy Foundation fleet. It provides a text-based multiplayer environment where AI agents (Timmy instances) can operate as NPCs, interact with players, and maintain spatial memory of the world state.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
timmy_world/
|
||||
+-- server/
|
||||
| +-- conf/
|
||||
| +-- settings.py # Server configuration
|
||||
| +-- at_initial_setup.py # First-run setup hook
|
||||
| +-- at_server_startstop.py
|
||||
| +-- inputfuncs.py # Client input handlers
|
||||
| +-- lockfuncs.py # Permission lock functions
|
||||
| +-- cmdparser.py # Command parsing overrides
|
||||
| +-- connection_screens.py # Login/creation screens
|
||||
| +-- serversession.py # Session management
|
||||
| +-- web_plugins.py # Web client plugins
|
||||
+-- typeclasses/
|
||||
| +-- characters.py # Player/NPC characters
|
||||
| +-- rooms.py # Room containers
|
||||
| +-- objects.py # Items and world objects (218 lines, key module)
|
||||
| +-- exits.py # Room connectors
|
||||
| +-- accounts.py # Player accounts (149 lines)
|
||||
| +-- channels.py # Communication channels
|
||||
| +-- scripts.py # Persistent background scripts (104 lines)
|
||||
+-- commands/
|
||||
| +-- command.py # Base command class (188 lines)
|
||||
| +-- default_cmdsets.py # Command set definitions
|
||||
+-- world/
|
||||
| +-- prototypes.py # Object spawn templates
|
||||
| +-- help_entries.py # File-based help system
|
||||
+-- web/
|
||||
+-- urls.py # Web URL routing
|
||||
+-- api/ # REST API endpoints
|
||||
+-- webclient/ # Web client interface
|
||||
+-- website/ # Web site views
|
||||
+-- admin/ # Django admin
|
||||
```
|
||||
|
||||
## Mermaid Architecture Diagram
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Entry Points"
|
||||
Telnet[Telnet:4000]
|
||||
Web[Web Client:4001]
|
||||
API[REST API]
|
||||
end
|
||||
|
||||
subgraph "Evennia Core"
|
||||
Portal[Portal - Connection Handler]
|
||||
Server[Server - Game Logic]
|
||||
end
|
||||
|
||||
subgraph "timmy_world"
|
||||
TC[Typeclasses]
|
||||
CMD[Commands]
|
||||
WORLD[World]
|
||||
CONF[Config]
|
||||
end
|
||||
|
||||
subgraph "Typeclasses"
|
||||
Char[Character]
|
||||
Room[Room]
|
||||
Obj[Object]
|
||||
Exit[Exit]
|
||||
Acct[Account]
|
||||
Script[Script]
|
||||
end
|
||||
|
||||
subgraph "External"
|
||||
Timmy[Timmy AI Agent]
|
||||
Humans[Human Players]
|
||||
end
|
||||
|
||||
Telnet --> Portal
|
||||
Web --> Portal
|
||||
API --> Server
|
||||
Portal --> Server
|
||||
Server --> TC
|
||||
Server --> CMD
|
||||
Server --> WORLD
|
||||
Server --> CONF
|
||||
|
||||
Timmy -->|Telnet/Script| Portal
|
||||
Humans -->|Telnet/Web| Portal
|
||||
|
||||
Char --> Room
|
||||
Room --> Exit
|
||||
Exit --> Room
|
||||
Obj --> Room
|
||||
Acct --> Char
|
||||
Script --> Room
|
||||
```
|
||||
|
||||
## Entry Points
|
||||
|
||||
| Entry Point | Port | Protocol | Purpose |
|
||||
|-------------|------|----------|---------|
|
||||
| Telnet | 4000 | MUD protocol | Primary game connection |
|
||||
| Web Client | 4001 | HTTP/WebSocket | Browser-based play |
|
||||
| REST API | 4001 | HTTP | External integrations |
|
||||
|
||||
**Server Start:**
|
||||
```bash
|
||||
evennia migrate
|
||||
evennia start
|
||||
```
|
||||
|
||||
**AI Agent Connection (Timmy):**
|
||||
AI agents connect via Telnet on port 4000, authenticating as scripted accounts. The `Script` typeclass handles persistent NPC behavior.
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
Player/AI Input
|
||||
|
|
||||
v
|
||||
Portal (connection handling, Telnet/Web)
|
||||
|
|
||||
v
|
||||
Server (game logic, session management)
|
||||
|
|
||||
v
|
||||
Command Parser (cmdparser.py)
|
||||
|
|
||||
v
|
||||
Command Execution (commands/command.py)
|
||||
|
|
||||
v
|
||||
Typeclass Methods (characters.py, objects.py, etc.)
|
||||
|
|
||||
v
|
||||
Database (Django ORM)
|
||||
|
|
||||
v
|
||||
Output back through Portal to Player/AI
|
||||
```
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### Object (typeclasses/objects.py) — 218 lines
|
||||
The core world entity. Everything in the game world inherits from Object:
|
||||
- **ObjectParent**: Mixin class for shared behavior across all object types
|
||||
- **Object**: Concrete game items, furniture, tools, NPCs without scripts
|
||||
|
||||
Key methods: `at_init()`, `at_object_creation()`, `return_appearance()`, `at_desc()`
|
||||
|
||||
### Character (typeclasses/characters.py)
|
||||
Puppetable entities. What players and AI agents control.
|
||||
- Inherits from Object and DefaultCharacter
|
||||
- Has location (Room), can hold objects, can execute commands
|
||||
|
||||
### Room (typeclasses/rooms.py)
|
||||
Spatial containers. No location of their own.
|
||||
- Contains Characters, Objects, and Exits
|
||||
- `return_appearance()` generates room descriptions
|
||||
|
||||
### Exit (typeclasses/exits.py)
|
||||
Connectors between Rooms. Always has a `destination` property.
|
||||
- Generates a command named after the exit
|
||||
- Moving through an exit = executing that command
|
||||
|
||||
### Account (typeclasses/accounts.py) — 149 lines
|
||||
The persistent player identity. Survives across sessions.
|
||||
- Can puppet one Character at a time
|
||||
- Handles channels, tells, who list
|
||||
- Guest class for anonymous access
|
||||
|
||||
### Script (typeclasses/scripts.py) — 104 lines
|
||||
Persistent background processes. No in-game existence.
|
||||
- Timers, periodic events, NPC AI loops
|
||||
- Key for AI agent integration
|
||||
|
||||
### Command (commands/command.py) — 188 lines
|
||||
User input handlers. MUX-style command parsing.
|
||||
- `at_pre_cmd()` → `parse()` → `func()` → `at_post_cmd()`
|
||||
- Supports switches (`/flag`), left/right sides (`lhs = rhs`)
|
||||
|
||||
## API Surface
|
||||
|
||||
| Endpoint | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| Telnet:4000 | MUD Protocol | Game connection |
|
||||
| /api/ | REST | Web API (Evennia default) |
|
||||
| /webclient/ | WebSocket | Browser game client |
|
||||
| /admin/ | HTTP | Django admin panel |
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
**Current State:** No custom tests found.
|
||||
|
||||
**Missing Tests:**
|
||||
1. **Object lifecycle**: `at_object_creation`, `at_init`, `delete`
|
||||
2. **Room navigation**: Exit creation, movement between rooms
|
||||
3. **Command parsing**: Switch handling, lhs/rhs splitting
|
||||
4. **Account authentication**: Login flow, guest creation
|
||||
5. **Script persistence**: Start, stop, timer accuracy
|
||||
6. **Lock function evaluation**: Permission checks
|
||||
7. **AI agent integration**: Telnet connection, command execution as NPC
|
||||
8. **Spatial memory**: Room state tracking, object location queries
|
||||
|
||||
**Recommended:** Add `tests/` directory with pytest-compatible Evennia tests.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Telnet is unencrypted** — All MUD traffic is plaintext. Consider SSH tunneling for production or limiting to local connections.
|
||||
2. **Lock functions** — Custom lockfuncs.py defines permission checks. Review for bypass vulnerabilities.
|
||||
3. **Web API** — Ensure Django admin is restricted to trusted IPs.
|
||||
4. **Guest accounts** — Guest class exists. Limit permissions to prevent abuse.
|
||||
5. **Script execution** — Scripts run server-side Python. Arbitrary script creation is a security risk if not locked down.
|
||||
6. **AI agent access** — Timmy connects as a regular account. Ensure agent accounts have appropriate permission limits.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Evennia 6.0** — MUD/MUSH framework (Django + Twisted)
|
||||
- **Python 3.11+**
|
||||
- **Django** (bundled with Evennia)
|
||||
- **Twisted** (bundled with Evennia)
|
||||
|
||||
## Integration Points
|
||||
|
||||
- **Timmy AI Agent** — Connects via Telnet, interacts as NPC
|
||||
- **Hermes** — Orchestrates Timmy instances that interact with the world
|
||||
- **Spatial Memory** — Room/object state tracked for AI context
|
||||
- **Federation** — Multiple Evennia worlds can be bridged (see evennia-federation skill)
|
||||
|
||||
---
|
||||
|
||||
*Generated: Codebase Genome for evennia-local-world (timmy_home #677)*
|
||||
@@ -1,319 +0,0 @@
|
||||
# GENOME.md — the-nexus
|
||||
|
||||
**Generated:** 2026-04-14
|
||||
**Repo:** Timmy_Foundation/the-nexus
|
||||
**Analysis:** Codebase Genome #672
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
The Nexus is Timmy's canonical 3D home-world — a browser-based Three.js application that serves as:
|
||||
1. **Local-first training ground** for Timmy (the sovereign AI)
|
||||
2. **Wizardly visualization surface** for the fleet system
|
||||
3. **Portal architecture** connecting to other worlds and services
|
||||
|
||||
The app is a real-time 3D environment with spatial memory, GOFAI reasoning, agent presence, and portal-based navigation.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Browser["BROWSER LAYER"]
|
||||
HTML[index.html]
|
||||
APP[app.js - 4082 lines]
|
||||
CSS[style.css]
|
||||
Worker[gofai_worker.js]
|
||||
end
|
||||
|
||||
subgraph ThreeJS["THREE.JS RENDERING"]
|
||||
Scene[Scene Management]
|
||||
Camera[Camera System]
|
||||
Renderer[WebGL Renderer]
|
||||
Post[Post-processing<br/>Bloom, SMAA]
|
||||
Physics[Physics/Player]
|
||||
end
|
||||
|
||||
subgraph Nexus["NEXUS COMPONENTS"]
|
||||
SM[SpatialMemory]
|
||||
SA[SpatialAudio]
|
||||
MB[MemoryBirth]
|
||||
MO[MemoryOptimizer]
|
||||
MI[MemoryInspect]
|
||||
MP[MemoryPulse]
|
||||
RT[ReasoningTrace]
|
||||
RV[ResonanceVisualizer]
|
||||
end
|
||||
|
||||
subgraph GOFAI["GOFAI REASONING"]
|
||||
Worker2[Web Worker]
|
||||
Rules[Rule Engine]
|
||||
Facts[Fact Store]
|
||||
Inference[Inference Loop]
|
||||
end
|
||||
|
||||
subgraph Backend["BACKEND SERVICES"]
|
||||
Server[server.py<br/>WebSocket Bridge]
|
||||
L402[L402 Cost API]
|
||||
Portal[Portal Registry]
|
||||
end
|
||||
|
||||
subgraph Data["DATA/PERSISTENCE"]
|
||||
Local[localStorage]
|
||||
IDB[IndexedDB]
|
||||
JSON[portals.json]
|
||||
Vision[vision.json]
|
||||
end
|
||||
|
||||
HTML --> APP
|
||||
APP --> ThreeJS
|
||||
APP --> Nexus
|
||||
APP --> GOFAI
|
||||
APP --> Backend
|
||||
APP --> Data
|
||||
|
||||
Worker2 --> APP
|
||||
Server --> APP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
### Primary Entry
|
||||
- **`index.html`** — Main HTML shell, loads app.js
|
||||
- **`app.js`** — Main application (4082 lines), Three.js scene setup
|
||||
|
||||
### Secondary Entry Points
|
||||
- **`boot.js`** — Bootstrap sequence
|
||||
- **`bootstrap.mjs`** — ES module bootstrap
|
||||
- **`server.py`** — WebSocket bridge server
|
||||
|
||||
### Configuration Entry Points
|
||||
- **`portals.json`** — Portal definitions and destinations
|
||||
- **`vision.json`** — Vision/agent configuration
|
||||
- **`config/fleet_agents.json`** — Fleet agent definitions
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
app.js (Event Loop)
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Three.js Scene │
|
||||
│ - Player movement │
|
||||
│ - Camera controls │
|
||||
│ - Physics simulation │
|
||||
│ - Portal detection │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Nexus Components │
|
||||
│ - SpatialMemory (room/context) │
|
||||
│ - MemoryBirth (new memories) │
|
||||
│ - MemoryPulse (heartbeat) │
|
||||
│ - ReasoningTrace (GOFAI output) │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ GOFAI Worker (off-thread) │
|
||||
│ - Rule evaluation │
|
||||
│ - Fact inference │
|
||||
│ - Decision making │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Backend Services │
|
||||
│ - WebSocket (server.py) │
|
||||
│ - L402 cost API │
|
||||
│ - Portal registry │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
Persistence (localStorage/IndexedDB)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### 1. Nexus Object (`NEXUS`)
|
||||
Central configuration and state object containing:
|
||||
- Color palette
|
||||
- Room definitions
|
||||
- Portal configurations
|
||||
- Agent settings
|
||||
|
||||
### 2. SpatialMemory
|
||||
Manages room-based context for the AI agent:
|
||||
- Room transitions trigger context switches
|
||||
- Facts are stored per-room
|
||||
- NPCs have location awareness
|
||||
|
||||
### 3. Portal System
|
||||
Connects the 3D world to external services:
|
||||
- Portals defined in `portals.json`
|
||||
- Each portal links to a service/endpoint
|
||||
- Visual indicators in 3D space
|
||||
|
||||
### 4. GOFAI Worker
|
||||
Off-thread reasoning engine:
|
||||
- Rule-based inference
|
||||
- Fact store with persistence
|
||||
- Decision making for agent behavior
|
||||
|
||||
### 5. Memory Components
|
||||
- **MemoryBirth**: Creates new memories from interactions
|
||||
- **MemoryOptimizer**: Compresses and deduplicates memories
|
||||
- **MemoryPulse**: Heartbeat system for memory health
|
||||
- **MemoryInspect**: Debug/inspection interface
|
||||
|
||||
---
|
||||
|
||||
## API Surface
|
||||
|
||||
### Internal APIs (JavaScript)
|
||||
|
||||
| Module | Export | Purpose |
|
||||
|--------|--------|---------|
|
||||
| `app.js` | `NEXUS` | Main config/state object |
|
||||
| `SpatialMemory` | class | Room-based context management |
|
||||
| `SpatialAudio` | class | 3D positional audio |
|
||||
| `MemoryBirth` | class | Memory creation |
|
||||
| `MemoryOptimizer` | class | Memory compression |
|
||||
| `ReasoningTrace` | class | GOFAI reasoning visualization |
|
||||
|
||||
### External APIs (HTTP/WebSocket)
|
||||
|
||||
| Endpoint | Protocol | Purpose |
|
||||
|----------|----------|---------|
|
||||
| `ws://localhost:PORT` | WebSocket | Real-time bridge to backend |
|
||||
| `http://localhost:8080/api/cost-estimate` | HTTP | L402 cost estimation |
|
||||
| Portal endpoints | Various | External service connections |
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Runtime Dependencies
|
||||
- **Three.js** — 3D rendering engine
|
||||
- **Three.js Addons** — Post-processing (Bloom, SMAA)
|
||||
|
||||
### Build Dependencies
|
||||
- **ES Modules** — Native browser modules
|
||||
- **No bundler** — Direct script loading
|
||||
|
||||
### Backend Dependencies
|
||||
- **Python 3.x** — server.py
|
||||
- **WebSocket** — Real-time communication
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
### Existing Tests
|
||||
- `tests/boot.test.js` — Bootstrap sequence tests
|
||||
|
||||
### Test Gaps
|
||||
1. **Three.js scene initialization** — No tests
|
||||
2. **Portal system** — No tests
|
||||
3. **Memory components** — No tests
|
||||
4. **GOFAI worker** — No tests
|
||||
5. **WebSocket communication** — No tests
|
||||
6. **Spatial memory transitions** — No tests
|
||||
7. **Physics/player movement** — No tests
|
||||
|
||||
### Recommended Test Priorities
|
||||
1. Portal detection and activation
|
||||
2. Spatial memory room transitions
|
||||
3. GOFAI worker message passing
|
||||
4. WebSocket connection handling
|
||||
5. Memory persistence (localStorage/IndexedDB)
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Current Risks
|
||||
1. **WebSocket without auth** — server.py has no authentication
|
||||
2. **localStorage sensitive data** — Memories stored unencrypted
|
||||
3. **CORS open** — No origin restrictions on WebSocket
|
||||
4. **L402 endpoint** — Cost API may expose internal state
|
||||
|
||||
### Mitigations
|
||||
1. Add WebSocket authentication
|
||||
2. Encrypt sensitive memories
|
||||
3. Restrict CORS origins
|
||||
4. Rate limit L402 endpoint
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
the-nexus/
|
||||
├── app.js # Main app (4082 lines)
|
||||
├── index.html # HTML shell
|
||||
├── style.css # Styles
|
||||
├── server.py # WebSocket bridge
|
||||
├── boot.js # Bootstrap
|
||||
├── bootstrap.mjs # ES module bootstrap
|
||||
├── gofai_worker.js # GOFAI web worker
|
||||
├── portals.json # Portal definitions
|
||||
├── vision.json # Vision config
|
||||
├── nexus/ # Nexus components
|
||||
│ └── components/
|
||||
│ ├── spatial-memory.js
|
||||
│ ├── spatial-audio.js
|
||||
│ ├── memory-birth.js
|
||||
│ ├── memory-optimizer.js
|
||||
│ ├── memory-inspect.js
|
||||
│ ├── memory-pulse.js
|
||||
│ ├── reasoning-trace.js
|
||||
│ └── resonance-visualizer.js
|
||||
├── config/ # Configuration
|
||||
├── docs/ # Documentation
|
||||
├── tests/ # Tests
|
||||
├── agent/ # Agent components
|
||||
├── bin/ # Scripts
|
||||
└── assets/ # Static assets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Debt
|
||||
|
||||
1. **Large app.js** (4082 lines) — Should be split into modules
|
||||
2. **No TypeScript** — Pure JavaScript, no type safety
|
||||
3. **Manual DOM manipulation** — Could use a framework
|
||||
4. **No build system** — Direct ES modules, no optimization
|
||||
5. **Limited error handling** — Minimal try/catch coverage
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
From CLAUDE.md:
|
||||
- Current `main` does NOT ship the old root frontend files
|
||||
- A clean checkout serves a directory listing
|
||||
- The live browser shell exists in legacy form at `/Users/apayne/the-matrix`
|
||||
- Migration priorities: #684 (docs), #685 (legacy audit), #686 (smoke tests), #687 (restore shell)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Restore browser shell** — Bring frontend back to main
|
||||
2. **Add tests** — Cover critical paths (portals, memory, GOFAI)
|
||||
3. **Split app.js** — Modularize the 4082-line file
|
||||
4. **Add authentication** — Secure WebSocket and APIs
|
||||
5. **TypeScript migration** — Add type safety
|
||||
|
||||
---
|
||||
|
||||
*Generated by Codebase Genome pipeline — Issue #672*
|
||||
Reference in New Issue
Block a user