|
|
|
|
@@ -1,271 +1,417 @@
|
|
|
|
|
# GENOME.md — evennia-local-world
|
|
|
|
|
|
|
|
|
|
*Auto-generated by Codebase Genome Pipeline. 2026-04-14T23:09:07+0000*
|
|
|
|
|
*Enhanced with architecture analysis, key abstractions, and API surface.*
|
|
|
|
|
|
|
|
|
|
## Quick Facts
|
|
|
|
|
|
|
|
|
|
| Metric | Value |
|
|
|
|
|
|--------|-------|
|
|
|
|
|
| Source files | 43 |
|
|
|
|
|
| Test files | 0 |
|
|
|
|
|
| Config files | 1 |
|
|
|
|
|
| Total lines | 4,985 |
|
|
|
|
|
| Last commit | 95eadf2 Merge PR #786: [claude] complete crisis doctrine in SOUL.md + refresh horizon doc (#545) (2026-04-22 02:39:05 +0000) |
|
|
|
|
|
| Branch | main |
|
|
|
|
|
| Test coverage | 0% (35 untested modules) |
|
|
|
|
|
*Generated: 2026-04-21 07:07:29 UTC | Refreshed for timmy-home #677*
|
|
|
|
|
|
|
|
|
|
## Project Overview
|
|
|
|
|
|
|
|
|
|
The academy codebase comprises **43 Python files** totaling **4,985** lines of source code. Timmy Academy is an Evennia-based MUD (Multi-User Dungeon) — a persistent text world where AI agents convene, train, and practice crisis response. It runs on Bezalel VPS (167.99.126.228) with telnet on port 4000 and web client on port 4001.
|
|
|
|
|
`evennia/timmy_world` is a hybrid codebase with two layers living side by side:
|
|
|
|
|
|
|
|
|
|
The world has five wings: Central Hub, Dormitory, Commons, Workshop, and Gardens. Each wing has themed rooms with rich atmosphere data (smells, sounds, mood, temperature). Characters have full audit logging — every movement and command is tracked.
|
|
|
|
|
1. A mostly stock Evennia 6.0 game directory:
|
|
|
|
|
- `server/conf/*.py`
|
|
|
|
|
- `typeclasses/*.py`
|
|
|
|
|
- `commands/*.py`
|
|
|
|
|
- `web/**/*.py`
|
|
|
|
|
- `world/prototypes.py`
|
|
|
|
|
- `world/help_entries.py`
|
|
|
|
|
2. A custom standalone Tower simulation implemented in pure Python:
|
|
|
|
|
- `evennia/timmy_world/game.py`
|
|
|
|
|
- `evennia/timmy_world/world/game.py`
|
|
|
|
|
- `evennia/timmy_world/play_200.py`
|
|
|
|
|
|
|
|
|
|
Grounded metrics from live inspection:
|
|
|
|
|
- 68 tracked files under `evennia/timmy_world`
|
|
|
|
|
- 43 Python files
|
|
|
|
|
- 4,985 Python LOC
|
|
|
|
|
- largest modules:
|
|
|
|
|
- `evennia/timmy_world/game.py` — 1,541 lines
|
|
|
|
|
- `evennia/timmy_world/world/game.py` — 1,345 lines
|
|
|
|
|
- `evennia/timmy_world/play_200.py` — 275 lines
|
|
|
|
|
- `evennia/timmy_world/typeclasses/objects.py` — 217 lines
|
|
|
|
|
- `evennia/timmy_world/commands/command.py` — 187 lines
|
|
|
|
|
|
|
|
|
|
The repo is not just an Evennia shell. The distinctive product logic lives in the standalone Tower simulator. That simulator models five rooms, named agents, trust/energy systems, narrative phases, NPC decision-making, and JSON persistence. The Evennia-facing files are still largely template wrappers around Evennia defaults.
|
|
|
|
|
|
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
|
|
The architecture splits into an Evennia runtime lane and a local simulation lane.
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
graph TB
|
|
|
|
|
subgraph "Connections"
|
|
|
|
|
TELNET[Telnet :4000]
|
|
|
|
|
WEB[Web Client :4001]
|
|
|
|
|
graph TD
|
|
|
|
|
subgraph External Clients
|
|
|
|
|
Telnet[Telnet client :4000]
|
|
|
|
|
Browser[Browser / webclient :4001]
|
|
|
|
|
Operator[Local operator]
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
subgraph "Evennia Core"
|
|
|
|
|
SERVER[Evennia Server]
|
|
|
|
|
PORTAL[Evennia Portal]
|
|
|
|
|
subgraph Evennia Runtime
|
|
|
|
|
Settings[server/conf/settings.py]
|
|
|
|
|
URLs[web/urls.py]
|
|
|
|
|
Cmdsets[commands/default_cmdsets.py]
|
|
|
|
|
Typeclasses[typeclasses/*.py]
|
|
|
|
|
WorldDocs[world/prototypes.py + world/help_entries.py]
|
|
|
|
|
WebHooks[server/conf/web_plugins.py]
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
subgraph "Typeclasses"
|
|
|
|
|
CHAR[Character]
|
|
|
|
|
AUDIT[AuditedCharacter]
|
|
|
|
|
ROOM[Room]
|
|
|
|
|
EXIT[Exit]
|
|
|
|
|
OBJ[Object]
|
|
|
|
|
subgraph Standalone Tower Simulator
|
|
|
|
|
Play200[play_200.py]
|
|
|
|
|
RootGame[game.py]
|
|
|
|
|
AltGame[world/game.py]
|
|
|
|
|
Engine[GameEngine / PlayerInterface / NPCAI]
|
|
|
|
|
State[game_state.json + timmy_log.md]
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
subgraph "Commands"
|
|
|
|
|
CMD_EXAM[CmdExamine]
|
|
|
|
|
CMD_ROOMS[CmdRooms]
|
|
|
|
|
CMD_STATUS[CmdStatus]
|
|
|
|
|
CMD_MAP[CmdMap]
|
|
|
|
|
CMD_ACADEMY[CmdAcademy]
|
|
|
|
|
CMD_SMELL[CmdSmell]
|
|
|
|
|
CMD_LISTEN[CmdListen]
|
|
|
|
|
CMD_WHO[CmdWho]
|
|
|
|
|
end
|
|
|
|
|
Telnet --> Settings
|
|
|
|
|
Browser --> URLs
|
|
|
|
|
Settings --> Cmdsets
|
|
|
|
|
Cmdsets --> Typeclasses
|
|
|
|
|
URLs --> WebHooks
|
|
|
|
|
Typeclasses --> WorldDocs
|
|
|
|
|
|
|
|
|
|
subgraph "World - Wings"
|
|
|
|
|
HUB[Central Hub]
|
|
|
|
|
DORM[Dormitory Wing]
|
|
|
|
|
COMMONS[Commons Wing]
|
|
|
|
|
WORKSHOP[Workshop Wing]
|
|
|
|
|
GARDENS[Gardens Wing]
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
subgraph "Hermes Bridge"
|
|
|
|
|
HERMES_CFG[hermes-agent/config.yaml]
|
|
|
|
|
BRIDGE[Agent Bridge]
|
|
|
|
|
end
|
|
|
|
|
|
|
|
|
|
TELNET --> SERVER
|
|
|
|
|
WEB --> PORTAL
|
|
|
|
|
PORTAL --> SERVER
|
|
|
|
|
SERVER --> CHAR
|
|
|
|
|
SERVER --> AUDIT
|
|
|
|
|
SERVER --> ROOM
|
|
|
|
|
SERVER --> EXIT
|
|
|
|
|
CHAR --> CMD_EXAM
|
|
|
|
|
CHAR --> CMD_STATUS
|
|
|
|
|
CHAR --> CMD_WHO
|
|
|
|
|
ROOM --> HUB
|
|
|
|
|
ROOM --> DORM
|
|
|
|
|
ROOM --> COMMONS
|
|
|
|
|
ROOM --> WORKSHOP
|
|
|
|
|
ROOM --> GARDENS
|
|
|
|
|
HERMES_CFG --> BRIDGE
|
|
|
|
|
BRIDGE --> SERVER
|
|
|
|
|
Operator --> Play200
|
|
|
|
|
Play200 --> RootGame
|
|
|
|
|
RootGame --> Engine
|
|
|
|
|
AltGame --> Engine
|
|
|
|
|
Engine --> State
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Core engine modules:
|
|
|
|
|
- `evennia/timmy_world/game.py` — top-level GameEngine
|
|
|
|
|
- `evennia/timmy_world/world/game.py` — world model (World, Room, Item, NPC)
|
|
|
|
|
- `evennia/timmy_world/play_200.py` — demo training scenario
|
|
|
|
|
What is actually wired today:
|
|
|
|
|
- `server/conf/settings.py` only overrides `SERVERNAME = "timmy_world"` and optionally imports `server.conf.secret_settings`.
|
|
|
|
|
- `web/urls.py` mounts `web.website.urls`, `web.webclient.urls`, `web.admin.urls`, then appends `evennia.web.urls`.
|
|
|
|
|
- `commands/default_cmdsets.py` subclasses Evennia defaults but does not add custom commands yet.
|
|
|
|
|
- `typeclasses/*.py` are thin wrappers around Evennia defaults.
|
|
|
|
|
- `server/conf/web_plugins.py` returns the web roots unchanged.
|
|
|
|
|
- `server/conf/at_initial_setup.py` is a no-op.
|
|
|
|
|
- `world/batch_cmds.ev` is still template commentary rather than a real build script.
|
|
|
|
|
|
|
|
|
|
What is custom and stateful today:
|
|
|
|
|
- `evennia/timmy_world/game.py`
|
|
|
|
|
- `evennia/timmy_world/world/game.py`
|
|
|
|
|
- `evennia/timmy_world/play_200.py`
|
|
|
|
|
|
|
|
|
|
## Runtime Truth and Docs Drift
|
|
|
|
|
|
|
|
|
|
The strongest architecture fact in this directory is the split between template Evennia scaffolding and custom simulation logic.
|
|
|
|
|
|
|
|
|
|
Drift discovered during inspection:
|
|
|
|
|
- `evennia/timmy_world/README.md` is the stock Evennia welcome text.
|
|
|
|
|
- `server/conf/at_initial_setup.py` is empty, so the Evennia world is not auto-populating custom Tower content at first boot.
|
|
|
|
|
- `world/batch_cmds.ev` is also a template, not a concrete room/object bootstrap file.
|
|
|
|
|
- The deepest custom logic is not in the typeclasses or server hooks. It is in `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
|
|
|
|
- `evennia/timmy_world/play_200.py` imports `from game import GameEngine, NARRATIVE_PHASES`, which proves the root `game.py` is an active entry point.
|
|
|
|
|
- `evennia/timmy_world/world/game.py` is not dead weight either; it contains its own `World`, `ActionSystem`, `NPCAI`, `DialogueSystem`, `GameEngine`, and `PlayerInterface` stack.
|
|
|
|
|
|
|
|
|
|
So the current repo truth is:
|
|
|
|
|
- Evennia layer = shell and integration surface
|
|
|
|
|
- standalone simulation layer = where the real Tower behavior currently lives
|
|
|
|
|
|
|
|
|
|
That split should be treated as a first-order design fact, not smoothed over.
|
|
|
|
|
|
|
|
|
|
## Entry Points
|
|
|
|
|
|
|
|
|
|
| File | Purpose |
|
|
|
|
|
|------|---------|
|
|
|
|
|
| `server/conf/settings.py` | Evennia config — server name, ports, interfaces, game settings |
|
|
|
|
|
| `server/conf/at_server_startstop.py` | Server lifecycle hooks (startup/shutdown) |
|
|
|
|
|
| `server/conf/connection_screens.py` | Login/connection screen text |
|
|
|
|
|
| `commands/default_cmdsets.py` | Registers all custom commands with Evennia |
|
|
|
|
|
| `world/rebuild_world.py` | Rebuilds all rooms from source |
|
|
|
|
|
| `world/build_academy.ev` | Evennia batch script for initial world setup |
|
|
|
|
|
| `game.py` | Main game engine (GameEngine, PlayerInterface) |
|
|
|
|
|
| `world/game.py` | World model (World, Room, NPC, ActionSystem) |
|
|
|
|
|
| `play_200.py` | Training scenario and demo actions |
|
|
|
|
|
### 1. Evennia server startup
|
|
|
|
|
Primary operational entry point for the networked world:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd evennia/timmy_world
|
|
|
|
|
evennia migrate
|
|
|
|
|
evennia start
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Grounding:
|
|
|
|
|
- `evennia/timmy_world/README.md`
|
|
|
|
|
- `evennia/timmy_world/server/conf/settings.py`
|
|
|
|
|
|
|
|
|
|
### 2. Web routing
|
|
|
|
|
`evennia/timmy_world/web/urls.py` is the browser-facing entry point. It includes:
|
|
|
|
|
- `web.website.urls`
|
|
|
|
|
- `web.webclient.urls`
|
|
|
|
|
- `web.admin.urls`
|
|
|
|
|
- `evennia.web.urls` appended after the local patterns
|
|
|
|
|
|
|
|
|
|
This means the effective surface inherits Evennia defaults rather than defining a custom Tower web application.
|
|
|
|
|
|
|
|
|
|
### 3. Standalone simulation module
|
|
|
|
|
`evennia/timmy_world/game.py` is a pure-Python entry point with:
|
|
|
|
|
- `NARRATIVE_PHASES`
|
|
|
|
|
- `get_narrative_phase()`
|
|
|
|
|
- `get_phase_transition_event()`
|
|
|
|
|
- `World`
|
|
|
|
|
- `ActionSystem`
|
|
|
|
|
- `NPCAI`
|
|
|
|
|
- `GameEngine`
|
|
|
|
|
- `PlayerInterface`
|
|
|
|
|
|
|
|
|
|
This module can be imported and exercised without an Evennia runtime.
|
|
|
|
|
|
|
|
|
|
### 4. Alternate simulation module
|
|
|
|
|
`evennia/timmy_world/world/game.py` mirrors much of the same gameplay stack, but is not the one used by `play_200.py`.
|
|
|
|
|
|
|
|
|
|
Important distinction:
|
|
|
|
|
- root `game.py` is the active scripted demo target
|
|
|
|
|
- `world/game.py` is a second engine implementation with overlapping responsibilities
|
|
|
|
|
|
|
|
|
|
### 5. Scripted narrative demo
|
|
|
|
|
`evennia/timmy_world/play_200.py` runs 200 deterministic ticks and prints a story arc across four named phases:
|
|
|
|
|
- Quietus
|
|
|
|
|
- Fracture
|
|
|
|
|
- Breaking
|
|
|
|
|
- Mending
|
|
|
|
|
|
|
|
|
|
This file is the clearest executable artifact proving how the simulator is intended to be consumed outside Evennia.
|
|
|
|
|
|
|
|
|
|
## Data Flow
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
In a deployed environment, the unpacked code is typically found at `/Users/apayne/.timmy/evennia/timmy_world`.
|
|
|
|
|
Player connects (telnet/web)
|
|
|
|
|
-> Evennia Portal accepts connection
|
|
|
|
|
-> Server authenticates (Account typeclass)
|
|
|
|
|
-> Player puppets a Character
|
|
|
|
|
-> Character enters world (Room typeclass)
|
|
|
|
|
-> Commands processed through Command typeclass
|
|
|
|
|
-> AuditedCharacter logs every action
|
|
|
|
|
-> World responds with rich text + atmosphere data
|
|
|
|
|
```
|
|
|
|
|
### Networked Evennia path
|
|
|
|
|
1. Client connects via telnet or browser.
|
|
|
|
|
2. Evennia loads settings from `server/conf/settings.py`.
|
|
|
|
|
3. Command set resolution flows through `commands/default_cmdsets.py`.
|
|
|
|
|
4. Typeclass objects resolve through `typeclasses/accounts.py`, `typeclasses/characters.py`, `typeclasses/rooms.py`, `typeclasses/exits.py`, `typeclasses/objects.py`, and `typeclasses/scripts.py`.
|
|
|
|
|
5. URL dispatch flows through `web/urls.py` into website, webclient, admin, and Evennia default URL patterns.
|
|
|
|
|
6. Object/help/prototype metadata can be sourced from `world/prototypes.py` and `world/help_entries.py`.
|
|
|
|
|
|
|
|
|
|
### Standalone Tower simulation path
|
|
|
|
|
1. Operator imports `evennia/timmy_world/game.py` directly or runs `evennia/timmy_world/play_200.py`.
|
|
|
|
|
2. `GameEngine.start_new_game()` initializes the world state.
|
|
|
|
|
3. `PlayerInterface.get_available_actions()` exposes current verbs from room topology and nearby characters.
|
|
|
|
|
4. `GameEngine.run_tick()` / `play_turn()` advances time, movement, world events, NPC actions, and logs.
|
|
|
|
|
5. `World` tracks rooms, characters, trust, weather, forge/garden/bridge/tower state, and narrative phase.
|
|
|
|
|
6. Persistence writes to JSON/log files rooted at `/Users/apayne/.timmy/evennia/timmy_world`.
|
|
|
|
|
|
|
|
|
|
### Evidence of the persistence contract
|
|
|
|
|
Both simulation modules hardcode the same portability-sensitive base path:
|
|
|
|
|
- `evennia/timmy_world/game.py`
|
|
|
|
|
- `evennia/timmy_world/world/game.py`
|
|
|
|
|
|
|
|
|
|
Each defines:
|
|
|
|
|
- `WORLD_DIR = Path('/Users/apayne/.timmy/evennia/timmy_world')`
|
|
|
|
|
- `STATE_FILE = WORLD_DIR / 'game_state.json'`
|
|
|
|
|
- `TIMMY_LOG = WORLD_DIR / 'timmy_log.md'`
|
|
|
|
|
|
|
|
|
|
## Key Abstractions
|
|
|
|
|
|
|
|
|
|
### Typeclasses (the world model)
|
|
|
|
|
### `World` — state container for the Tower
|
|
|
|
|
Found in both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
|
|
|
|
|
|
|
|
|
| Class | File | Purpose |
|
|
|
|
|
|-------|------|---------|
|
|
|
|
|
| `Character` | `typeclasses/characters.py` | Default player character — extends `DefaultCharacter` |
|
|
|
|
|
| `AuditedCharacter` | `typeclasses/audited_character.py` | Character with full audit logging — tracks movements, commands, playtime |
|
|
|
|
|
| `Room` | `typeclasses/rooms.py` | Default room container |
|
|
|
|
|
| `Exit` | `typeclasses/exits.py` | Connections between rooms |
|
|
|
|
|
| `Object` | `typeclasses/objects.py` | Base object with `ObjectParent` mixin |
|
|
|
|
|
| `Account` | `typeclasses/accounts.py` | Player account (login identity) |
|
|
|
|
|
| `Channel` | `typeclasses/channels.py` | In-game communication channels |
|
|
|
|
|
| `Script` | `typeclasses/scripts.py` | Background/timed processes |
|
|
|
|
|
Responsibilities:
|
|
|
|
|
- defines the five-room map: Threshold, Tower, Forge, Garden, Bridge
|
|
|
|
|
- stores per-room connections and dynamic state
|
|
|
|
|
- stores per-character room, energy, trust, goals, memories, and inventory
|
|
|
|
|
- tracks global pressure variables like `forge_fire_dying`, `garden_drought`, `bridge_flooding`, and `tower_power_low`
|
|
|
|
|
- updates world time and environmental drift each tick
|
|
|
|
|
|
|
|
|
|
### AuditedCharacter — the flagship typeclass
|
|
|
|
|
### `ActionSystem`
|
|
|
|
|
Also present in both engine files.
|
|
|
|
|
|
|
|
|
|
The `AuditedCharacter` is the most important abstraction. It wraps every player action in logging:
|
|
|
|
|
Responsibilities:
|
|
|
|
|
- enumerates available verbs
|
|
|
|
|
- computes contextual action menus from world state
|
|
|
|
|
- ties actions to energy cost and room/character context
|
|
|
|
|
|
|
|
|
|
- `at_pre_move()` — logs departure from current room
|
|
|
|
|
- `at_post_move()` — records arrival with timestamp and coordinates
|
|
|
|
|
- `at_pre_cmd()` — increments command counter, logs command + args
|
|
|
|
|
- `at_pre_puppet()` — starts session timer
|
|
|
|
|
- `at_post_unpuppet()` — calculates session duration, updates total playtime
|
|
|
|
|
- `get_audit_summary()` — returns JSON summary of all tracked metrics
|
|
|
|
|
### `NPCAI`
|
|
|
|
|
The non-player decision layer.
|
|
|
|
|
|
|
|
|
|
Audit trail keeps last 1000 movements in `db.location_history`. Sensitive commands (password) are excluded from logging.
|
|
|
|
|
Responsibilities:
|
|
|
|
|
- chooses actions based on each character's goals and situation
|
|
|
|
|
- creates world motion without requiring live operator input
|
|
|
|
|
- in `world/game.py`, works alongside `DialogueSystem`
|
|
|
|
|
|
|
|
|
|
### Commands (the player interface)
|
|
|
|
|
### `GameEngine`
|
|
|
|
|
The orchestration layer.
|
|
|
|
|
|
|
|
|
|
Command implementations are covered by integration tests (see `tests/test_evennia_local_world_game.py`) and auto-generated unit tests (`tests/test_genome_generated.py`).
|
|
|
|
|
Responsibilities:
|
|
|
|
|
- bootstraps a fresh run with `start_new_game()`
|
|
|
|
|
- rehydrates from storage via `load_game()`
|
|
|
|
|
- advances the simulation with `run_tick()` / `play_turn()`
|
|
|
|
|
- records log entries and world events
|
|
|
|
|
|
|
|
|
|
| Command | Aliases | Purpose |
|
|
|
|
|
|---------|---------|---------|
|
|
|
|
|
| `examine` | `ex`, `exam` | Inspect room or object — shows description, atmosphere, objects, contents |
|
|
|
|
|
| `rooms` | — | List all rooms with wing color coding |
|
|
|
|
|
| `@status` | `status` | Show agent status: location, wing, mood, online players, uptime |
|
|
|
|
|
| `@map` | `map` | ASCII map of current wing |
|
|
|
|
|
| `@academy` | `academy` | Full academy overview with room counts |
|
|
|
|
|
| `smell` | `sniff` | Perceive room through atmosphere scent data |
|
|
|
|
|
| `listen` | `hear` | Perceive room through atmosphere sound data |
|
|
|
|
|
| `@who` | `who` | Show connected players with locations and idle time |
|
|
|
|
|
Grounded interface details from live import of `evennia/timmy_world/game.py`:
|
|
|
|
|
- methods visible on the instance: `load_game`, `log`, `play_turn`, `run_tick`, `start_new_game`
|
|
|
|
|
- `play_turn('look')` returns a dict with keys:
|
|
|
|
|
- `tick`
|
|
|
|
|
- `time`
|
|
|
|
|
- `phase`
|
|
|
|
|
- `phase_name`
|
|
|
|
|
- `timmy_room`
|
|
|
|
|
- `timmy_energy`
|
|
|
|
|
- `room_desc`
|
|
|
|
|
- `here`
|
|
|
|
|
- `world_events`
|
|
|
|
|
- `npc_actions`
|
|
|
|
|
- `choices`
|
|
|
|
|
- `log`
|
|
|
|
|
|
|
|
|
|
### World Structure (5 wings, 21+ rooms)
|
|
|
|
|
### `PlayerInterface`
|
|
|
|
|
A thin operator-facing adapter.
|
|
|
|
|
|
|
|
|
|
**Central Hub (LIMBO)** — Nexus connecting all wings. North=Dormitory, South=Workshop, East=Commons, West=Gardens.
|
|
|
|
|
Grounded behavior:
|
|
|
|
|
- when loaded from `evennia/timmy_world/game.py` after `start_new_game()`, `PlayerInterface(engine).get_available_actions()` exposes room navigation and social verbs like:
|
|
|
|
|
- `move:north -> Tower`
|
|
|
|
|
- `move:east -> Garden`
|
|
|
|
|
- `move:west -> Forge`
|
|
|
|
|
- `move:south -> Bridge`
|
|
|
|
|
- `speak:Allegro`
|
|
|
|
|
- `speak:Claude`
|
|
|
|
|
- `rest`
|
|
|
|
|
|
|
|
|
|
**Dormitory Wing** — Master Suites, Corridor, Novice Hall, Residential Services, Dorm Entrance.
|
|
|
|
|
### Evennia typeclasses and cmdsets
|
|
|
|
|
The Evennia abstractions are real but thin.
|
|
|
|
|
|
|
|
|
|
**Commons Wing** — Grand Commons Hall (main gathering, 60ft ceilings, marble columns), Hearthside Dining, Entertainment Gallery, Scholar's Corner, Upper Balcony.
|
|
|
|
|
Notable files:
|
|
|
|
|
- `evennia/timmy_world/typeclasses/objects.py`
|
|
|
|
|
- `evennia/timmy_world/typeclasses/characters.py`
|
|
|
|
|
- `evennia/timmy_world/typeclasses/rooms.py`
|
|
|
|
|
- `evennia/timmy_world/typeclasses/exits.py`
|
|
|
|
|
- `evennia/timmy_world/typeclasses/accounts.py`
|
|
|
|
|
- `evennia/timmy_world/typeclasses/scripts.py`
|
|
|
|
|
- `evennia/timmy_world/commands/command.py`
|
|
|
|
|
- `evennia/timmy_world/commands/default_cmdsets.py`
|
|
|
|
|
|
|
|
|
|
**Workshop Wing** — Great Smithy, Alchemy Labs, Woodworking Shop, Artificing Chamber, Workshop Entrance.
|
|
|
|
|
|
|
|
|
|
**Gardens Wing** — Enchanted Grove, Herb Gardens, Greenhouse, Sacred Grove, Gardens Entrance.
|
|
|
|
|
|
|
|
|
|
Each room has rich `db.atmosphere` data: mood, lighting, sounds, smells, temperature.
|
|
|
|
|
Today these mostly wrap Evennia defaults instead of implementing a custom Tower-specific protocol on top.
|
|
|
|
|
|
|
|
|
|
## API Surface
|
|
|
|
|
|
|
|
|
|
### Web API
|
|
|
|
|
### Network surfaces
|
|
|
|
|
Grounded from `README.md`, `web/urls.py`, and `server/conf/mssp.py`:
|
|
|
|
|
- Telnet on port `4000`
|
|
|
|
|
- Browser / webclient on `http://localhost:4001`
|
|
|
|
|
- admin surface under `/admin/`
|
|
|
|
|
- Evennia default URLs appended via `evennia.web.urls`
|
|
|
|
|
- Evennia REST/web surface inherits the default `/api/` patterns rather than defining custom project-specific endpoints here
|
|
|
|
|
|
|
|
|
|
- `web/api/__init__.py` — Evennia REST API (Django REST Framework)
|
|
|
|
|
- `web/urls.py` — URL routing for web interface
|
|
|
|
|
- `web/admin/` — Django admin interface
|
|
|
|
|
- `web/website/` — Web frontend
|
|
|
|
|
### Operator / script surfaces
|
|
|
|
|
- `python3 evennia/timmy_world/play_200.py`
|
|
|
|
|
- importable pure-Python engine in `evennia/timmy_world/game.py`
|
|
|
|
|
- alternate engine in `evennia/timmy_world/world/game.py`
|
|
|
|
|
|
|
|
|
|
### Telnet
|
|
|
|
|
|
|
|
|
|
- Standard MUD protocol on port 4000
|
|
|
|
|
- Supports MCCP (compression), MSDP (data), GMCP (protocol)
|
|
|
|
|
|
|
|
|
|
### Hermes Bridge
|
|
|
|
|
|
|
|
|
|
- `hermes-agent/config.yaml` — Configuration for AI agent connection
|
|
|
|
|
- Allows Hermes agents to connect as characters and interact with the world
|
|
|
|
|
|
|
|
|
|
## Dependencies
|
|
|
|
|
|
|
|
|
|
No `requirements.txt` or `pyproject.toml` found. Dependencies come from Evennia:
|
|
|
|
|
|
|
|
|
|
- **evennia** — MUD framework (Django-based)
|
|
|
|
|
- **django** — Web framework (via Evennia)
|
|
|
|
|
- **twisted** — Async networking (via Evennia)
|
|
|
|
|
### Content/model surfaces
|
|
|
|
|
- object prototype definitions: `evennia/timmy_world/world/prototypes.py`
|
|
|
|
|
- file-based help entries: `evennia/timmy_world/world/help_entries.py`
|
|
|
|
|
|
|
|
|
|
## Test Coverage Gaps
|
|
|
|
|
|
|
|
|
|
| Metric | Value |
|
|
|
|
|
|--------|-------|
|
|
|
|
|
| Source modules | 35 |
|
|
|
|
|
| Test modules | 1 |
|
|
|
|
|
| Estimated coverage | 0% |
|
|
|
|
|
| Untested modules | 35 |
|
|
|
|
|
### Current verified state
|
|
|
|
|
The original genome here was stale. The live repo now shows two different categories of test coverage:
|
|
|
|
|
|
|
|
|
|
The academy test suite includes:
|
|
|
|
|
- `tests/test_evennia_local_world_game.py` — live game integration
|
|
|
|
|
- `tests/test_genome_generated.py` — auto-generated unit test stubs
|
|
|
|
|
- `tests/test_evennia_local_world_genome.py` — validates this GENOME document
|
|
|
|
|
- `tests/test_bezalel_evennia_layout.py` — spatial layout verification
|
|
|
|
|
- `tests/test_evennia_mind_palace.py` — memory palace integration
|
|
|
|
|
- `tests/test_evennia_telemetry.py` — event logging
|
|
|
|
|
- `tests/test_evennia_training.py` — training workflow validation
|
|
|
|
|
- `tests/test_evennia_vps_repair.py` — VPS repair script checks
|
|
|
|
|
Additionally, **19 skipped** due to optional dependencies (e.g., Evennia not installed in the test environment).
|
|
|
|
|
1. Host-repo generated tests already exist in `tests/test_genome_generated.py`
|
|
|
|
|
- they reference `evennia/timmy_world/game.py`
|
|
|
|
|
- they reference `evennia/timmy_world/world/game.py`
|
|
|
|
|
- they reference `server/conf/web_plugins.py`
|
|
|
|
|
2. Those generated tests are not trustworthy as-is for this target
|
|
|
|
|
- running `python3 -m pytest tests/test_genome_generated.py -k 'EvenniaTimmyWorld' -q -rs`
|
|
|
|
|
- result: `19 skipped, 31 deselected`
|
|
|
|
|
- skip reason on every case: `Module not importable`
|
|
|
|
|
|
|
|
|
|
### Critical Untested Paths
|
|
|
|
|
This matters because the codebase-genome pipeline reported zero local tests for the subproject, but the host repo does contain tests. The real issue is not “no tests exist.” The real issue is “the existing generated tests are disconnected from the actual import path and therefore do not execute the critical path.”
|
|
|
|
|
|
|
|
|
|
1. **AuditedCharacter** — audit logging is the primary value-add. No tests verify movement tracking, command counting, or playtime calculation.
|
|
|
|
|
2. **Commands** — no tests for any of the 8 commands. The `@map` wing detection, `@who` session tracking, and atmosphere-based commands (`smell`, `listen`) are all untested.
|
|
|
|
|
3. **World rebuild** — `rebuild_world.py` and `fix_world.py` can destroy and recreate the entire world. No tests ensure they produce valid output.
|
|
|
|
|
4. **Typeclass hooks** — `at_pre_move`, `at_post_move`, `at_pre_cmd` etc. are never tested in isolation.
|
|
|
|
|
### New critical-path tests added for #677
|
|
|
|
|
This issue refresh adds a dedicated executable test file:
|
|
|
|
|
- `tests/test_evennia_local_world_game.py`
|
|
|
|
|
|
|
|
|
|
Covered behaviors:
|
|
|
|
|
- narrative phase boundaries across Quietus / Fracture / Breaking / Mending
|
|
|
|
|
- player-facing action surface from the Threshold start state
|
|
|
|
|
- deterministic `run_tick('move:north')` flow into the Tower with expected log and world-event output
|
|
|
|
|
|
|
|
|
|
### Genome artifact coverage added for #677
|
|
|
|
|
This issue refresh also adds:
|
|
|
|
|
- `tests/test_evennia_local_world_genome.py`
|
|
|
|
|
|
|
|
|
|
That test locks:
|
|
|
|
|
- artifact path
|
|
|
|
|
- required analysis sections
|
|
|
|
|
- grounded snippets for real files and verification output
|
|
|
|
|
|
|
|
|
|
### Remaining gaps
|
|
|
|
|
Still missing strong runtime coverage for:
|
|
|
|
|
- Evennia typeclass behavior under a real Evennia test harness
|
|
|
|
|
- URL routing under Django/Evennia integration
|
|
|
|
|
- `world/game.py` parity versus root `game.py`
|
|
|
|
|
- persistence portability around `/Users/apayne/.timmy/evennia/timmy_world`
|
|
|
|
|
- `at_initial_setup.py` and `world/batch_cmds.ev` actually building a playable world in the Evennia path
|
|
|
|
|
|
|
|
|
|
## Security Considerations
|
|
|
|
|
|
|
|
|
|
- ⚠️ Uses `eval()`/`exec()` — Evennia's inlinefuncs module uses eval for dynamic command evaluation. Risk level: inherent to MUD framework.
|
|
|
|
|
- ⚠️ References secrets/passwords — `settings.py` references `secret_settings.py` for sensitive config. Ensure this file is not committed.
|
|
|
|
|
- ⚠️ Telnet on 0.0.0.0 — server accepts connections from any IP. Consider firewall rules.
|
|
|
|
|
- ⚠️ Web client on 0.0.0.0 — same exposure as telnet. Ensure authentication is enforced.
|
|
|
|
|
- ⚠️ Agent bridge (`hermes-agent/config.yaml`) — verify credentials are not hardcoded.
|
|
|
|
|
1. Plaintext telnet exposure
|
|
|
|
|
- `server/conf/mssp.py` advertises port `4000`
|
|
|
|
|
- telnet is unencrypted by default
|
|
|
|
|
- acceptable for localhost/dev, risky for exposed deployment
|
|
|
|
|
|
|
|
|
|
2. Hardcoded absolute persistence path
|
|
|
|
|
- both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py` hardcode `/Users/apayne/.timmy/evennia/timmy_world`
|
|
|
|
|
- this couples runtime writes to one operator machine and one home-directory layout
|
|
|
|
|
- portability and accidental overwrite risk are both real
|
|
|
|
|
- filed follow-up: `timmy-home #831` — `https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/831`
|
|
|
|
|
|
|
|
|
|
3. Admin/web surfaces inherit defaults
|
|
|
|
|
- `web/urls.py` exposes admin and Evennia defaults
|
|
|
|
|
- if the service is made remotely reachable, Django/Evennia auth and proxy boundaries matter immediately
|
|
|
|
|
|
|
|
|
|
4. Secret handling is externalized but optional
|
|
|
|
|
- `server/conf/settings.py` silently falls back if `secret_settings.py` is missing
|
|
|
|
|
- convenient for local development, but secrets discipline lives outside the repo contract
|
|
|
|
|
|
|
|
|
|
5. Template hooks can hide missing security posture
|
|
|
|
|
- `server/conf/web_plugins.py` is pass-through
|
|
|
|
|
- `server/conf/at_initial_setup.py` is pass-through
|
|
|
|
|
- the absence of custom code here means there are no local hardening hooks yet for startup, proxying, or world bootstrap
|
|
|
|
|
|
|
|
|
|
## Dependencies
|
|
|
|
|
|
|
|
|
|
Directly evidenced imports and framework coupling:
|
|
|
|
|
- Evennia 6.0 game-directory structure
|
|
|
|
|
- Django via Evennia web/admin stack
|
|
|
|
|
- Twisted via Evennia networking/web hooks
|
|
|
|
|
- Python stdlib heavy use in standalone simulator:
|
|
|
|
|
- `json`
|
|
|
|
|
- `time`
|
|
|
|
|
- `os`
|
|
|
|
|
- `random`
|
|
|
|
|
- `datetime`
|
|
|
|
|
- `pathlib`
|
|
|
|
|
- `sys`
|
|
|
|
|
|
|
|
|
|
Dependency caveat:
|
|
|
|
|
- the standalone Tower simulator is largely pure Python and importable in isolation
|
|
|
|
|
- the typeclass / cmdset / web files depend on Evennia and Django runtime wiring to do real work
|
|
|
|
|
|
|
|
|
|
## Deployment
|
|
|
|
|
|
|
|
|
|
Timmy Academy runs as an Evennia world on dedicated VPS and localhost.
|
|
|
|
|
### Evennia path
|
|
|
|
|
```bash
|
|
|
|
|
cd evennia/timmy_world
|
|
|
|
|
evennia migrate
|
|
|
|
|
evennia start
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Production (Bezalel VPS)** — telnet on port 4000, web client on 4001:
|
|
|
|
|
- Telnet: `telnet 167.99.126.228 4000`
|
|
|
|
|
- Web: `http://167.99.126.228:4001`
|
|
|
|
|
Expected local surfaces from repo docs/config:
|
|
|
|
|
- telnet: `localhost:4000`
|
|
|
|
|
- browser/webclient: `http://localhost:4001`
|
|
|
|
|
|
|
|
|
|
**Local development** — clone and run `evennia start --name timmy_world` from `evennia/timmy_world/`. The default runtime path is `/Users/apayne/.timmy/evennia/timmy_world`.
|
|
|
|
|
### Standalone simulation path
|
|
|
|
|
```bash
|
|
|
|
|
cd evennia/timmy_world
|
|
|
|
|
python3 play_200.py
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Hermes bridge** — AI agents connect via the `hermes-agent` bridge, configured in `hermes-agent/config.yaml` to point at the local Evennia socket.
|
|
|
|
|
This does not require the full Evennia network stack. It exercises the root `game.py` engine directly.
|
|
|
|
|
|
|
|
|
|
## Configuration Files
|
|
|
|
|
### Verification commands run for this genome refresh
|
|
|
|
|
```bash
|
|
|
|
|
python3 ~/.hermes/pipelines/codebase-genome.py --path /tmp/BURN-7-7/evennia/timmy_world --output /tmp/evennia-local-world-GENOME-base.md
|
|
|
|
|
python3 -m pytest tests/test_genome_generated.py -k 'EvenniaTimmyWorld' -q -rs
|
|
|
|
|
python3 -m pytest tests/test_evennia_local_world_genome.py tests/test_evennia_local_world_game.py -q
|
|
|
|
|
python3 -m py_compile evennia/timmy_world/game.py evennia/timmy_world/world/game.py evennia/timmy_world/play_200.py evennia/timmy_world/server/conf/settings.py evennia/timmy_world/web/urls.py
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- `server/conf/settings.py` — Main Evennia settings (server name, ports, typeclass paths)
|
|
|
|
|
- `hermes-agent/config.yaml` — Hermes agent bridge configuration
|
|
|
|
|
- `world/build_academy.ev` — Evennia batch build script
|
|
|
|
|
- `world/batch_cmds.ev` — Batch command definitions
|
|
|
|
|
## Key Findings
|
|
|
|
|
|
|
|
|
|
## What's Missing
|
|
|
|
|
|
|
|
|
|
1. **Tests** — 0% coverage is a critical gap. Priority: AuditedCharacter hooks, command func() methods, world rebuild integrity.
|
|
|
|
|
2. **CI/CD** — No automated testing pipeline. No GitHub Actions or Gitea workflows.
|
|
|
|
|
3. **Documentation** — `world/BUILDER_GUIDE.md` exists but no developer onboarding docs.
|
|
|
|
|
4. **Monitoring** — No health checks, no metrics export, no alerting on server crashes.
|
|
|
|
|
5. **Backup** — No automated database backup for the Evennia SQLite/PostgreSQL database.
|
|
|
|
|
1. The current custom product logic is the standalone Tower simulator, not the Evennia typeclass layer.
|
|
|
|
|
2. The repo contains two parallel simulation engines: `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
|
|
|
|
3. The stock Evennia scaffolding is still mostly template code (`README.md`, `at_initial_setup.py`, `world/batch_cmds.ev`, pass-through cmdsets/web hooks).
|
|
|
|
|
4. The codebase-genome pipeline undercounted test reality because subproject-local tests are absent while host-repo tests exist one level up.
|
|
|
|
|
5. The existing generated tests were present but functionally inert: `19 skipped` because their import path does not match the current host-repo layout.
|
|
|
|
|
6. The most concrete portability hazard is the hardcoded `/Users/apayne/.timmy/evennia/timmy_world` state path in both simulation engines.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
*Generated by Codebase Genome Pipeline. Review and update manually.*
|
|
|
|
|
This refreshed genome supersedes the earlier auto-generated `evennia/timmy_world/GENOME.md` summary by grounding the analysis in live source inspection, live import of `evennia/timmy_world/game.py`, current file metrics, and executable host-repo verification.
|
