Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
3250c6d124 | ||
|
|
ab050629fc |
@@ -1,242 +1,417 @@
|
||||
# GENOME.md: evennia-local-world
|
||||
# GENOME.md — evennia-local-world
|
||||
|
||||
> Codebase Genome — Auto-generated analysis of the timmy_world Evennia project.
|
||||
*Generated: 2026-04-21 07:07:29 UTC | Refreshed for timmy-home #677*
|
||||
|
||||
## 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
|
||||
`evennia/timmy_world` is a hybrid codebase with two layers living side by side:
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
```
|
||||
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
|
||||
The architecture splits into an Evennia runtime lane and a local simulation lane.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Entry Points"
|
||||
Telnet[Telnet:4000]
|
||||
Web[Web Client:4001]
|
||||
API[REST API]
|
||||
graph TD
|
||||
subgraph External Clients
|
||||
Telnet[Telnet client :4000]
|
||||
Browser[Browser / webclient :4001]
|
||||
Operator[Local operator]
|
||||
end
|
||||
|
||||
subgraph "Evennia Core"
|
||||
Portal[Portal - Connection Handler]
|
||||
Server[Server - Game Logic]
|
||||
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 "timmy_world"
|
||||
TC[Typeclasses]
|
||||
CMD[Commands]
|
||||
WORLD[World]
|
||||
CONF[Config]
|
||||
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 "Typeclasses"
|
||||
Char[Character]
|
||||
Room[Room]
|
||||
Obj[Object]
|
||||
Exit[Exit]
|
||||
Acct[Account]
|
||||
Script[Script]
|
||||
end
|
||||
Telnet --> Settings
|
||||
Browser --> URLs
|
||||
Settings --> Cmdsets
|
||||
Cmdsets --> Typeclasses
|
||||
URLs --> WebHooks
|
||||
Typeclasses --> WorldDocs
|
||||
|
||||
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
|
||||
Operator --> Play200
|
||||
Play200 --> RootGame
|
||||
RootGame --> Engine
|
||||
AltGame --> Engine
|
||||
Engine --> State
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
| 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 |
|
||||
### 1. Evennia server startup
|
||||
Primary operational entry point for the networked world:
|
||||
|
||||
**Server Start:**
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
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.
|
||||
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
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
### 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
|
||||
|
||||
### 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
|
||||
### `World` — state container for the Tower
|
||||
Found in both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
|
||||
Key methods: `at_init()`, `at_object_creation()`, `return_appearance()`, `at_desc()`
|
||||
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
|
||||
|
||||
### 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
|
||||
### `ActionSystem`
|
||||
Also present in both engine files.
|
||||
|
||||
### Room (typeclasses/rooms.py)
|
||||
Spatial containers. No location of their own.
|
||||
- Contains Characters, Objects, and Exits
|
||||
- `return_appearance()` generates room descriptions
|
||||
Responsibilities:
|
||||
- enumerates available verbs
|
||||
- computes contextual action menus from world state
|
||||
- ties actions to energy cost and room/character context
|
||||
|
||||
### 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
|
||||
### `NPCAI`
|
||||
The non-player decision layer.
|
||||
|
||||
### 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
|
||||
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`
|
||||
|
||||
### Script (typeclasses/scripts.py) — 104 lines
|
||||
Persistent background processes. No in-game existence.
|
||||
- Timers, periodic events, NPC AI loops
|
||||
- Key for AI agent integration
|
||||
### `GameEngine`
|
||||
The orchestration layer.
|
||||
|
||||
### 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`)
|
||||
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
|
||||
|
||||
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`
|
||||
|
||||
### `PlayerInterface`
|
||||
A thin operator-facing adapter.
|
||||
|
||||
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`
|
||||
|
||||
### Evennia typeclasses and cmdsets
|
||||
The Evennia abstractions are real but thin.
|
||||
|
||||
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`
|
||||
|
||||
Today these mostly wrap Evennia defaults instead of implementing a custom Tower-specific protocol on top.
|
||||
|
||||
## 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 |
|
||||
### 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
|
||||
|
||||
### 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`
|
||||
|
||||
### 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
|
||||
|
||||
**Current State:** No custom tests found.
|
||||
### Current verified state
|
||||
The original genome here was stale. The live repo now shows two different categories of test coverage:
|
||||
|
||||
**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
|
||||
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`
|
||||
|
||||
**Recommended:** Add `tests/` directory with pytest-compatible Evennia tests.
|
||||
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.”
|
||||
|
||||
### 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
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
- **Evennia 6.0** — MUD/MUSH framework (Django + Twisted)
|
||||
- **Python 3.11+**
|
||||
- **Django** (bundled with Evennia)
|
||||
- **Twisted** (bundled with Evennia)
|
||||
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`
|
||||
|
||||
## Integration Points
|
||||
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
|
||||
|
||||
- **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)
|
||||
## Deployment
|
||||
|
||||
### Evennia path
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
evennia migrate
|
||||
evennia start
|
||||
```
|
||||
|
||||
Expected local surfaces from repo docs/config:
|
||||
- telnet: `localhost:4000`
|
||||
- browser/webclient: `http://localhost:4001`
|
||||
|
||||
### Standalone simulation path
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
python3 play_200.py
|
||||
```
|
||||
|
||||
This does not require the full Evennia network stack. It exercises the root `game.py` engine directly.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## Key Findings
|
||||
|
||||
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: Codebase Genome for evennia-local-world (timmy_home #677)*
|
||||
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.
|
||||
71
tests/test_evennia_local_world_game.py
Normal file
71
tests/test_evennia_local_world_game.py
Normal file
@@ -0,0 +1,71 @@
|
||||
from importlib.util import module_from_spec, spec_from_file_location
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
GAME_PATH = ROOT / "evennia" / "timmy_world" / "game.py"
|
||||
|
||||
|
||||
def load_game_module():
|
||||
spec = spec_from_file_location("evennia_local_world_game", GAME_PATH)
|
||||
module = module_from_spec(spec)
|
||||
assert spec.loader is not None
|
||||
spec.loader.exec_module(module)
|
||||
module.random.seed(0)
|
||||
return module
|
||||
|
||||
|
||||
class TestEvenniaLocalWorldGame(unittest.TestCase):
|
||||
def test_narrative_phase_boundaries(self):
|
||||
module = load_game_module()
|
||||
expected = {
|
||||
1: "quietus",
|
||||
50: "quietus",
|
||||
51: "fracture",
|
||||
100: "fracture",
|
||||
101: "breaking",
|
||||
150: "breaking",
|
||||
151: "mending",
|
||||
999: "mending",
|
||||
}
|
||||
for tick, phase_name in expected.items():
|
||||
with self.subTest(tick=tick):
|
||||
phase, details = module.get_narrative_phase(tick)
|
||||
self.assertEqual(phase, phase_name)
|
||||
self.assertEqual(details["name"], module.NARRATIVE_PHASES[phase_name]["name"])
|
||||
|
||||
def test_player_interface_exposes_room_navigation_and_social_actions(self):
|
||||
module = load_game_module()
|
||||
engine = module.GameEngine()
|
||||
engine.start_new_game()
|
||||
|
||||
actions = module.PlayerInterface(engine).get_available_actions()
|
||||
|
||||
self.assertIn("move:north -> Tower", actions)
|
||||
self.assertIn("move:east -> Garden", actions)
|
||||
self.assertIn("move:west -> Forge", actions)
|
||||
self.assertIn("move:south -> Bridge", actions)
|
||||
self.assertIn("speak:Allegro", actions)
|
||||
self.assertIn("speak:Claude", actions)
|
||||
self.assertIn("rest", actions)
|
||||
|
||||
def test_run_tick_moves_timmy_into_tower_and_reports_world_state(self):
|
||||
module = load_game_module()
|
||||
engine = module.GameEngine()
|
||||
engine.start_new_game()
|
||||
|
||||
result = engine.run_tick("move:north")
|
||||
|
||||
self.assertEqual(result["tick"], 1)
|
||||
self.assertEqual(engine.world.characters["Timmy"]["room"], "Tower")
|
||||
self.assertEqual(result["timmy_room"], "Tower")
|
||||
self.assertEqual(result["phase"], "quietus")
|
||||
self.assertEqual(result["phase_name"], "Quietus")
|
||||
self.assertIn("You move north to The Tower.", result["log"])
|
||||
self.assertIn("Ezra is already here.", result["log"])
|
||||
self.assertIn("The servers hum steady. The green LED pulses.", result["world_events"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
52
tests/test_evennia_local_world_genome.py
Normal file
52
tests/test_evennia_local_world_genome.py
Normal file
@@ -0,0 +1,52 @@
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
GENOME_PATH = ROOT / "evennia" / "timmy_world" / "GENOME.md"
|
||||
|
||||
|
||||
class TestEvenniaLocalWorldGenome(unittest.TestCase):
|
||||
def test_genome_file_exists_with_required_sections(self):
|
||||
self.assertTrue(GENOME_PATH.exists(), "missing evennia/timmy_world/GENOME.md")
|
||||
text = GENOME_PATH.read_text(encoding="utf-8")
|
||||
required_sections = [
|
||||
"# GENOME.md — evennia-local-world",
|
||||
"## Project Overview",
|
||||
"## Architecture",
|
||||
"## Entry Points",
|
||||
"## Data Flow",
|
||||
"## Key Abstractions",
|
||||
"## API Surface",
|
||||
"## Test Coverage Gaps",
|
||||
"## Security Considerations",
|
||||
"## Deployment",
|
||||
]
|
||||
for section in required_sections:
|
||||
self.assertIn(section, text)
|
||||
|
||||
def test_genome_names_current_runtime_truth_and_verification(self):
|
||||
text = GENOME_PATH.read_text(encoding="utf-8")
|
||||
required_snippets = [
|
||||
"```mermaid",
|
||||
"evennia/timmy_world/game.py",
|
||||
"evennia/timmy_world/world/game.py",
|
||||
"evennia/timmy_world/play_200.py",
|
||||
"tests/test_genome_generated.py",
|
||||
"tests/test_evennia_local_world_game.py",
|
||||
"/Users/apayne/.timmy/evennia/timmy_world",
|
||||
"43 Python files",
|
||||
"4,985",
|
||||
"19 skipped",
|
||||
]
|
||||
for snippet in required_snippets:
|
||||
self.assertIn(snippet, text)
|
||||
|
||||
def test_genome_is_substantial(self):
|
||||
text = GENOME_PATH.read_text(encoding="utf-8")
|
||||
self.assertGreaterEqual(len(text.splitlines()), 120)
|
||||
self.assertGreaterEqual(len(text), 7000)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user