DEPRECATION NOTICE

This implementation plan has been completed. The checkboxes below were not updated during implementation and do not reflect current status. Please refer to the actual codebase for the current implementation state. Key implemented features include:

Grid System (packages/maid-engine/src/maid_engine/core/grid.py)

Grid Builder Commands (packages/maid-engine/src/maid_engine/commands/grid.py)

Procedural Generation (packages/maid-engine/src/maid_engine/world/procedural/)

Wilderness Manager (packages/maid-engine/src/maid_engine/world/procedural/wilderness.py)

Extended Room Component (packages/maid-stdlib/src/maid_stdlib/components/extended_room.py)

Building Commands (packages/maid-stdlib/src/maid_stdlib/commands/building/)

World System Enhancements - Implementation Plan¶

Summary¶

This plan implements three major world system enhancements to achieve feature parity with Evennia:

XYZ Coordinate Grid System - Optional coordinate-based room indexing with A* pathfinding, automatic exit creation, and spatial queries
Wilderness/Procedural Generation - On-demand procedural room generation using noise functions, biomes, and deterministic seeding
Extended Room Features - Dynamic room descriptions with time-of-day, seasonal, weather, and conditional variations

These features build upon existing MAID infrastructure (Coordinates class, RoomManager) and follow the monorepo package architecture (maid-engine for core, maid-stdlib for components).

Tasks¶

Phase 1: Core Grid Infrastructure (maid-engine)¶

1.1 GridCoord and Data Structures¶

[x] Create packages/maid-engine/src/maid_engine/core/grid.py module
[x] Implement GridCoord frozen dataclass with x, y, z coordinates
[x] Add GridCoord arithmetic operators (__add__, __sub__)
[x] Implement distance methods: distance_to(), manhattan_distance(), chebyshev_distance()
[x] Implement neighbors() method with diagonal/vertical options
[x] Implement direction_to() and from_direction() static method for compass directions
[x] Implement GridRoom dataclass (room_id, coord, movement_cost, blocked, terrain_type, metadata)
[x] Implement PathResult dataclass for pathfinding results

1.2 GridManager Core¶

[x] Implement GridManager class with World reference
[x] Add primary index: _grid: dict[GridCoord, GridRoom]
[x] Add reverse index: _room_to_grid: dict[UUID, GridRoom]
[x] Add blocked coordinates set: _blocked: set[GridCoord]
[x] Add configuration flags: auto_create_exits, allow_diagonals, allow_vertical
[x] Implement register_room() method with duplicate/blocked validation
[x] Implement unregister_room() method
[x] Implement _connect_to_neighbors() for automatic exit creation
[x] Implement _create_exit() integration point with room/exit system

1.3 Grid Queries¶

[x] Implement get_room_at(x, y, z) - O(1) point lookup
[x] Implement get_coord(room_id) - reverse lookup
[x] Implement rooms_in_radius() - Euclidean distance query
[x] Implement rooms_in_rect() - rectangular region query
[x] Implement nearest_room() - find closest room to point

1.4 A* Pathfinding¶

[x] Implement find_path() public method accepting room UUIDs
[x] Implement _astar() core algorithm with priority queue
[x] Add movement cost weighting (including diagonal cost multiplier)
[x] Add can_pass callback support for custom passability checks
[x] Add max_length limit for path search
[x] Implement _reconstruct_path() for path building
[x] Implement _path_to_directions() for direction list output
Depends on: 1.1 GridCoord.direction_to()

1.5 Blocking and Bulk Operations¶

[x] Implement block_coordinate() method
[x] Implement unblock_coordinate() method
[x] Implement is_blocked() query method
[x] Implement create_grid_area() bulk room creation
Depends on: 1.2 register_room()

1.6 Grid Serialization¶

[x] Implement export_grid() for persistence
[x] Implement import_grid() for restoration
Depends on: 1.2 register_room()

1.7 World Integration¶

[x] Add grid: GridManager attribute to World class
[x] Implement World.register_room_at_coord() convenience method
[x] Emit events when rooms are added/removed from grid (GridRoomAddedEvent, GridRoomRemovedEvent)

1.8 Grid Unit Tests¶

[x] Test GridCoord arithmetic and distance calculations
[x] Test GridManager room registration and duplicate rejection
[x] Test automatic exit creation between adjacent rooms
[x] Test A* pathfinding with known paths
[x] Test pathfinding respects blocked cells and movement costs
[x] Test radius and rectangular queries
[x] Test grid export/import round-trip
Depends on: 1.1-1.6

Phase 2: Procedural Generation Infrastructure (maid-engine)¶

2.1 Noise Generation¶

[x] Create packages/maid-engine/src/maid_engine/world/procedural/ package
[x] Implement SimplexNoise class in noise.py
[x] Add _generate_permutation() from seed for determinism
[x] Implement noise2d() method returning -1 to 1 range
[x] Implement octave_noise() for multi-octave terrain

2.2 Terrain Generation¶

[x] Implement TerrainConfig dataclass (seed, scale, octaves, thresholds)
[x] Implement TerrainGenerator class
[x] Add secondary noise for moisture and temperature
[x] Implement get_terrain() biome selection from elevation/moisture
[x] Implement get_elevation() normalized elevation query

2.3 Biome Definitions¶

[x] Create biomes.py module
[x] Implement BiomeDefinition dataclass
[x] Add description templates, name templates, movement cost, sector type
[x] Add resource/encounter type lists with spawn chances
[x] Implement generate_name() and generate_description() methods
[x] Define DEFAULT_BIOMES dict (plains, forest, mountains, desert, water, swamp, etc.)

2.4 Wilderness Manager Core¶

[x] Create wilderness.py module
[x] Implement GeneratedRoom dataclass with staleness checking
[x] Implement Landmark dataclass for fixed locations
[x] Implement WildernessConfig dataclass (seed, terrain, boundaries, cleanup settings)
[x] Implement WildernessManager class with World and GridManager references
[x] Add _generated: dict[tuple[int, int], GeneratedRoom] tracking
[x] Add _landmarks: dict[tuple[int, int], Landmark] tracking
Depends on: 2.1-2.3, 1.2 GridManager

2.5 Room Generation¶

[x] Implement get_or_create_room() main entry point
[x] Implement _generate_room() with deterministic RNG from coordinates
[x] Integrate terrain generation for biome selection
[x] Implement _create_room_entity() integration point
[x] Implement _spawn_contents() for resource/encounter placement
[x] Register generated rooms in GridManager
Depends on: 2.4, 1.2

2.6 Landmarks¶

[x] Implement add_landmark() with radius support
[x] Implement remove_landmark()
[x] Ensure landmarks override procedural generation

2.7 Boundaries and Cleanup¶

[x] Implement _in_bounds() boundary checking
[x] Implement get_edge_description() for world edge messages
[x] Implement player tracking: player_entered(), player_left()
[x] Implement _cleanup_loop() async task
[x] Implement _cleanup_stale_rooms() with room destruction
[x] Implement start() and stop() lifecycle methods
Depends on: 2.5

2.8 Wilderness Queries¶

[x] Implement preview_terrain() for terrain preview without generation
[x] Implement get_stats() for statistics reporting
[x] Implement _count_by_biome() helper

2.9 Movement Integration¶

[x] Create movement handler for wilderness areas
[x] Integrate with existing movement system
[x] Handle boundary messages and room generation
Depends on: 2.5, 2.7

2.10 Wilderness Unit Tests¶

[x] Test noise determinism (same seed = same output)
[x] Test terrain generation biome selection
[x] Test room generation determinism (same coord = same room)
[x] Test landmark override of procedural generation
[x] Test cleanup removes stale empty rooms
[x] Test boundary blocking
[x] Benchmark room generation < 10ms
Depends on: 2.1-2.8

Phase 3: Extended Room Features (maid-stdlib)¶

3.1 Time/Season/Weather Enums¶

[x] Create packages/maid-stdlib/src/maid_stdlib/components/extended_room.py
[x] Define TimeOfDay enum (DAWN, MORNING, NOON, AFTERNOON, DUSK, EVENING, NIGHT, MIDNIGHT)
[x] Define Season enum (SPRING, SUMMER, AUTUMN, WINTER)
[x] Define Weather enum (CLEAR, CLOUDY, RAIN, STORM, SNOW, FOG, WIND)

3.2 Room Detail System¶

[x] Implement RoomDetail dataclass with text, weight, and conditions
[x] Implement check_conditions() method with various comparison types
[x] Support list membership, callable, and equality conditions

3.3 Extended Descriptions¶

[x] Implement ExtendedDescriptions dataclass
[x] Add time_variants dict and time_mode (append/replace)
[x] Add season_variants dict and season_mode
[x] Add weather_effects dict
[x] Add random_details list with max_random_details limit
[x] Add conditional_details list
[x] Add mood/atmosphere system
[x] Implement render() method combining all variants
[x] Implement weighted random selection for details
Depends on: 3.1, 3.2

3.4 Extended Exit Descriptions¶

[x] Implement ExtendedExitDescription dataclass
[x] Add state-based variants (open, closed, locked)
[x] Add time variants
[x] Implement render() method

3.5 Extended Room Component¶

[x] Implement ExtendedRoomComponent ECS component
[x] Add descriptions and exit_descriptions fields
[x] Implement get_description() with caching
[x] Implement get_exit_description()
[x] Implement invalidate_cache()
[x] Use deterministic RNG based on cache key for consistent random details
Depends on: 3.3, 3.4

3.6 Room Renderer¶

[x] Create packages/maid-stdlib/src/maid_stdlib/utils/room_renderer.py
[x] Implement RoomRenderer class with World reference
[x] Implement render_room() main method
[x] Add _get_time_of_day() integration with GameTimeSystem
[x] Add _get_season() integration with GameTimeSystem
[x] Add _get_weather() integration with WeatherSystem
[x] Implement _build_context() for conditional rendering
[x] Implement _format_room_name() with ANSI colors
[x] Implement _render_exits() with extended exit support
[x] Implement _render_contents() for room occupants
Depends on: 3.5

3.7 Extended Room Unit Tests¶

[x] Test ExtendedDescriptions rendering with all variants
[x] Test time-based description selection
[x] Test season-based description selection
[x] Test weather effect injection
[x] Test conditional detail filtering
[x] Test random detail weighted selection
[x] Test description caching
[x] Test exit state-based descriptions
[x] Benchmark cached vs uncached rendering
Depends on: 3.3-3.6

Phase 4: Builder Commands¶

4.1 Grid Builder Commands (maid-engine)¶

[x] Implement @grid.create command for bulk room creation
[x] Implement @grid.path command for pathfinding display
[x] Implement @grid.map command for ASCII map rendering
[x] Register commands in maid-engine command registry
Note: Grid commands are in maid-engine (not maid-stdlib) because they directly interface with GridManager
Depends on: Phase 1

4.2 Extended Room Builder Commands (maid-stdlib)¶

[x] Implement @room.desc.time command for time variants
[x] Implement @room.desc.season command for season variants
[x] Implement @room.desc.weather command for weather effects
[x] Implement @room.detail.add command for random details
[x] Implement @room.detail.list command for viewing details
[x] Implement @room.detail.remove command for removing details
[x] Register commands in maid-stdlib command registry
Depends on: Phase 3

4.3 Wilderness Builder Commands¶

[x] Implement @wilderness.landmark command for adding landmarks
[x] Implement @wilderness.preview command for terrain preview
[x] Implement @wilderness.stats command for statistics
[x] Register commands
Depends on: Phase 2

Phase 5: Integration and Polish¶

5.1 Content Pack Integration¶

[x] Create grid system ContentPack hooks
[x] Create wilderness ContentPack hooks
[x] Create extended room ContentPack hooks
[x] Update ContentPack protocol if needed
Depends on: Phases 1-4

5.2 Persistence Integration¶

[x] Add grid data to world save/load
[x] Add wilderness config to world save/load
[x] Add extended room data to room persistence
[x] Ensure landmarks persist across restarts
Depends on: 1.6, 2.4, 3.5

5.3 Integration Tests¶

[x] Test Grid + Movement: player navigation through grid rooms
[x] Test Wilderness Exploration: generate rooms, return to same spot
[x] Test Wilderness Cleanup: timeout and cleanup verification
[x] Test Extended Descriptions: cycle through time/season/weather
[x] Test Builder Commands: create and verify changes persist
Depends on: Phases 1-4

5.4 Performance Benchmarks¶

[x] Benchmark grid registration (1000 rooms < 1s)
[x] Benchmark A* pathfinding (100 steps < 10ms)
[x] Benchmark wilderness generation (< 10ms per room)
[x] Benchmark description rendering (cached < 1ms, uncached < 5ms)
[x] Add benchmarks to CI if applicable
Depends on: Phases 1-3

5.5 Documentation¶

[x] Document grid system API in docstrings
[x] Document wilderness configuration options
[x] Document extended room builder workflow
[x] Add examples to docs/
[x] Update CLAUDE.md with new features if needed
Depends on: Phases 1-4

Priority Summary¶

Priority	Features
P0 (Critical)	Grid core, A* pathfinding, wilderness generation, time/weather descriptions
P1 (Important)	Radius/rect queries, biome transitions, seasonal descriptions, caching
P2 (Nice-to-have)	Path caching, height maps, mood system, multiple grids

Estimated Effort¶

Phase	Estimated Time
Phase 1: Grid Infrastructure	3-4 days
Phase 2: Procedural Generation	3-4 days
Phase 3: Extended Room Features	2-3 days
Phase 4: Builder Commands	1-2 days
Phase 5: Integration & Polish	2-3 days
Total	11-16 days