timmy-home/evennia/timmy_world/GENOME.md

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

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:

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)