Task 4.4: Room Loading System

[niyazmft]

Task 4.4: Room Loading System

Phase: 4B - Content Foundation
Priority: HIGH
Duration: 4-5 days
Sprint: Sprint 3 (Weeks 5-6)

---

Objective

Create a room loading system that reads room definitions from JSON and configures the grid, elevation, cover, and enemy encounters.

Current State

• Room generation is stubbed in RunManager
• Seeds are generated but no actual room layouts exist
• GridSystem can load rooms from JSON but no room JSON files exist
• CombatRoom has hardcoded enemy spawns

---

Execution Order

Can Start: After Task 4.3 (Turn Manager) is functional
Blocked by: Task 4.3 (needs combat loop working first)
Blocks: None (content task, doesn't block others)

---

Implementation Details

1. Create Room JSON Files

// config/rooms/room_standard_01.json
{
  "id": "room_standard_01",
  "biome": "sanctum",
  "size": {"width": 12, "height": 12},
  "layout": {
    "elevation": [...],
    "cover": [...],
    "blocked": [...]
  },
  "encounters": [
    {
      "enemy_type": "grunt",
      "count": 3,
      "positions": [...]
    }
  ],
  "player_start": {"x": 1, "y": 1}
}

2. Create Room Loader

# scripts/combat/room_loader.gd
class_name RoomLoader
extends Node

const ROOMS_PATH := "res://config/rooms/"

func load_room(room_id: String) -> Dictionary:
    var path := ROOMS_PATH + room_id + ".json"
    # Read and parse JSON
    return json.data

func configure_grid(room_data: Dictionary) -> void:
    GridSystem.load_room(room_data)

func spawn_encounters(room_data: Dictionary, entity_container: Node) -> void:
    # Spawn enemies at defined positions

3. Hook into RunManager

# In RunManager._enter_room():
func _enter_room(_ctx: Dictionary) -> void:
    var room_data := _get_current_room_data()
    var room_id: String = room_data.get("room_id", "room_standard_01")
    var room_def := RoomLoader.load_room(room_id)
    
    if not room_def.is_empty():
        RoomLoader.configure_grid(room_def)
        RoomLoader.spawn_encounters(room_def, _entity_container)
        _spawn_player(room_def.get("player_start", {"x": 1, "y": 1}))

---

Acceptance Criteria

• 3-5 room JSON files created
• Room loader reads and parses JSON
• Grid configured from room definition (elevation, cover, blocked)
• Enemies spawned at defined positions
• Player spawned at defined start position
• Rooms have different layouts
• Rooms have different enemy encounters
• Hooked into RunManager room flow
• Test file: tests/test_room_loader.gd

---

Dependencies

• Task 4.3 (Turn Manager) - Good to have combat first
• Task 4.5 (Enemy Variety) - For different enemy types in rooms
• Uses existing: GridSystem.load_room(), BaseEnemy scenes

Parallel Work

• Can be done in parallel with: Task 4.5 (Enemy Variety)
• Best completed after: Task 4.3
• Shares files with: Task 4.5 (enemy scenes)

---

References

• scripts/autoload/grid_system.gd - Grid configuration
• scripts/state_machine/run_manager.gd - Room flow
• scripts/entities/base_enemy.gd - Enemy spawning

Notes for Jules

Create 3-5 simple room layouts first. Focus on different elevation and cover configurations.

[niyazmft]

@coderabbitai plan

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

Coding Plan

Summary

• Create 3-5 room JSON files using a compact, sparse-array format for ease of authoring, stored in config/rooms/
• Implement RoomLoader as a utility class with static methods that converts the compact format to GridSystem's flat tiles format and provides entity spawning helpers
• Integrate by having RunManager configure the grid on room entry and CombatRoom handle entity spawning via EventBus signal connection
• Maintain determinism by using topology_seed to select rooms, preserving the existing seed-driven architecture

Design Choices

Design Choice 1: Room JSON Format Choice

Options Considered:

1. Use GridSystem's flat tiles format directly in JSON files (no conversion needed, but verbose and harder to author)
2. Use compact ticket-style format with sparse arrays and convert in RoomLoader (readable, requires conversion code)

Chosen Option: 2

Rationale: Use the compact format from the ticket and implement conversion in RoomLoader, as it's more designer-friendly and aligns with the prototype room file pattern.

Design Choice 2: Entity Spawning Responsibility

Options Considered:

1. Have RunManager receive entity_container reference and handle all spawning directly
2. Have CombatRoom connect to room_entered signal and handle spawning using RoomLoader utilities
3. Make RoomLoader an autoload that receives container registration

Chosen Option: 2

Rationale: CombatRoom connects to EventBus.room_entered and uses RoomLoader utility methods for spawning, keeping concerns properly separated (grid config is global, spawning requires local container).

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Room JSON File Creation

Create the room data files that define grid layouts and encounters. These files will use a compact, author-friendly format with sparse coordinate arrays for non-default tiles.

Task 1: Create Room Directory Structure

Set up the rooms configuration directory following the project's config pattern.

• Create config/rooms/ directory to hold all room definition files
• Follow the existing config pattern with _description keys for inline documentation

Task 2: Create Room JSON Schema

Define and document the room file format that will be used consistently across all room definitions.

• Room file structure: id, biome, player_start (x, y coordinates), tiles (sparse arrays for elevation/cover/blocked), encounters (enemy definitions with positions)
• Elevation tiers use coordinate arrays: elevation.tier_1 for MID, elevation.tier_2 for HIGH
• Cover uses coordinate arrays: cover.light, cover.heavy
• Blocked tiles listed as coordinate pairs in blocked array
• Encounters define enemy_type, count, and positions array

Task 3: Create 3-5 Room Definition Files

Create varied room layouts demonstrating different tactical configurations.

• config/rooms/room_standard_01.json — Basic open room with minimal cover, grunt enemies in a diagonal spread
• config/rooms/room_elevated_01.json — Room with elevated terrain (tier_1 platforms), requiring vertical movement
• config/rooms/room_cover_heavy_01.json — Defensive layout with multiple heavy cover positions
• config/rooms/room_flanking_01.json — Layout encouraging flanking with blocked center pillars and light cover on sides
• config/rooms/room_chokepoint_01.json — Narrow corridor layout with limited approach angles
• Each room should have distinct player_start position and enemy configurations using only grunt type (the only available enemy)

🤖 Prompt for AI agents

Create the `config/rooms/` directory and populate it with 5 room definition JSON
files using a compact, sparse-array format. Each file should follow a consistent
schema.

**Directory:** `config/rooms/`

**JSON Schema per room file:**
- `id` (string): unique room identifier
- `biome` (string): room biome label
- `player_start` (object): `{ "x": int, "y": int }`
- `tiles` (object):
- `elevation` (object): `{ "tier_1": [[x,y], ...], "tier_2": [[x,y], ...] }` —
`tier_1` maps to elevation=1 (MID), `tier_2` maps to elevation=2 (HIGH)
  - `cover` (object): `{ "light": [[x,y], ...], "heavy": [[x,y], ...] }`
- `blocked` (array): `[[x,y], ...]` — tiles that block both movement and vision
- `encounters` (array): each entry has `enemy_type` (string), `count` (int),
`positions` (array of `[x,y]`)
- Include `_description` keys for inline documentation following the existing
config pattern

**Files to create:**
- `config/rooms/room_standard_01.json` — Basic open room, minimal cover, grunt
enemies in a diagonal spread
- `config/rooms/room_elevated_01.json` — Elevated terrain with tier_1 platforms
requiring vertical movement
- `config/rooms/room_cover_heavy_01.json` — Defensive layout with multiple heavy
cover positions
- `config/rooms/room_flanking_01.json` — Blocked center pillars with light cover
on the sides
- `config/rooms/room_chokepoint_01.json` — Narrow corridor with limited approach
angles

All encounters must use `"enemy_type": "grunt"` (the only available enemy type).
Each room must have a distinct `player_start` position.

Phase 2: RoomLoader Implementation

Create the room loading utility that reads JSON files, converts to GridSystem format, and provides spawning helpers.

Task 1: Create RoomLoader Class

Build the core room loading and parsing functionality.

• Create scripts/combat/ directory (new)
• Create scripts/combat/room_loader.gd with class_name RoomLoader extending RefCounted
• Implement static func load_room(room_id: String) -> Dictionary that reads from res://config/rooms/{room_id}.json
• Use FileAccess and JSON.parse_string() following existing config loading patterns
• Return empty Dictionary on file not found or parse error (with push_warning)
• Implement static func get_available_rooms() -> PackedStringArray that lists all room files in the directory

Task 2: Implement Grid Configuration Conversion

Convert the compact room format to GridSystem's expected flat tiles array format.

• Implement static func configure_grid(room_data: Dictionary) -> Error in room_loader.gd
• Build the flat tiles array by iterating all 144 grid positions (12×12)
• For each position, check against sparse arrays: elevation.tier_1/tier_2, cover.light/heavy, blocked
• Map tier_1 → elevation=1, tier_2 → elevation=2, light → cover=1, heavy → cover=2
• Set blocks_movement and blocks_vision for positions in blocked array
• Call GridSystem.load_room() (via AutoloadHelper.grid_system()) with the converted format
• Return the Error code from GridSystem.load_room()

Task 3: Implement Entity Spawning Methods

Create helper methods to spawn player and enemies at defined positions.

• Implement static func spawn_enemies(room_data: Dictionary, container: Node) -> Array[Node2D]
• Create an "Enemies" grouping Node2D under the container (matching CombatRoom's pattern)
• Iterate encounters array, for each entry load the appropriate scene (res://scenes/enemies/enemy_grunt.tscn for "grunt" type)
• Instantiate enemy, add to enemies node, set grid position via entity.set_grid_position(x, y)
• Implement static func spawn_player(room_data: Dictionary, container: Node) -> Node2D
• Load res://scenes/keeper.tscn, create Entity with position from player_start, set is_player = true
• Return references for the caller to track

🤖 Prompt for AI agents

Create the `scripts/combat/` directory and implement
`scripts/combat/room_loader.gd` as a static utility class.

**File:** `scripts/combat/room_loader.gd`
- `class_name RoomLoader` extending `RefCounted`

**Method: `static func load_room(room_id: String) -> Dictionary`**
- Construct path: `res://config/rooms/{room_id}.json`
- Use `FileAccess` to open the file; if it fails, call `push_warning` and return
an empty `Dictionary`
- Parse content with `JSON.parse_string()`; on parse error, call `push_warning`
and return an empty `Dictionary`
- Return the parsed dictionary

**Method: `static func get_available_rooms() -> PackedStringArray`**
- List all `.json` files in `res://config/rooms/` and return their names
(without extension) as a `PackedStringArray`

**Method: `static func configure_grid(room_data: Dictionary) -> Error`**
- Build a flat tiles array with 144 entries (12×12 grid, all positions)
- For each `(x, y)` position, produce a dictionary with keys: `x`, `y`,
`elevation`, `cover`, `blocks_movement`, `blocks_vision`
- Check the sparse arrays in `room_data.tiles`:
- `elevation.tier_1` → elevation=1, `elevation.tier_2` → elevation=2 (default 0)
  - `cover.light` → cover=1, `cover.heavy` → cover=2 (default 0)
  - `blocked` → `blocks_movement=true`, `blocks_vision=true` (default false)
- Call `GridSystem.load_room()` via `AutoloadHelper.grid_system()` with the flat
tiles array
- Return the `Error` code from `GridSystem.load_room()`

**Method: `static func spawn_enemies(room_data: Dictionary, container: Node) ->
Array[Node2D]`**
- Create a `Node2D` named `"Enemies"` and add it as a child of `container`
- Iterate `room_data.encounters`; for each entry:
  - If `enemy_type == "grunt"`, load `res://scenes/enemies/enemy_grunt.tscn`
- For each position in `positions`, instantiate the scene, add to the enemies
node, call `entity.set_grid_position(x, y)`
- Return an array of all spawned enemy nodes

**Method: `static func spawn_player(room_data: Dictionary, container: Node) ->
Node2D`**
- Load `res://scenes/keeper.tscn`
- Instantiate and add to `container`
- Set `is_player = true` and call `set_grid_position(x, y)` using
`room_data.player_start`
- Return the player node reference

Phase 3: System Integration

Hook the room loader into RunManager and CombatRoom to replace hardcoded spawning.

Task 1: Extend Room Data Generation

Add room_id selection to RunManager's room data generation.

• Update scripts/state_machine/run_manager.gd _action_generate_rooms() to include room_id in each room_data dictionary
• Use topology_seed with deterministic selection from available rooms: RoomLoader.get_available_rooms()[seed % count]
• This ensures room selection is deterministic and replayable from the run seed

Task 2: Update RunManager Room Entry

Configure the grid when entering a room.

• Update _enter_room() in run_manager.gd to load room definition and configure grid
• After existing _combat_resolved = false reset, call RoomLoader.load_room(room_data.room_id)
• Call RoomLoader.configure_grid() with loaded definition
• Pass room definition along with the room_entered signal (extend signal or use EventBus data passing)

Task 3: Update CombatRoom Signal Connection

Connect CombatRoom to room events and implement data-driven spawning.

• Update scripts/core/combat_room.gd _ready() to connect to EventBus.room_entered signal
• Add handler method _on_room_entered(room_index: int, room_data: Dictionary)
• In handler: if not test_mode, call RoomLoader.spawn_player() and RoomLoader.spawn_enemies() with entity_container
• Store returned player reference in _player and enemies container in _enemies_node
• Keep test_mode functional for isolated testing but set default to false for production flow

Task 4: Wire Up EventBus Room Data

Ensure room definition data flows through the event system.

• Update scripts/autoload/event_bus.gd if needed to relay room definition alongside room_entered
• Alternative: Store loaded room_def on RunManager as a property that CombatRoom can access via AutoloadHelper
• Choose approach that minimizes coupling while ensuring CombatRoom has access to spawn data

🤖 Prompt for AI agents

Integrate RoomLoader into the existing RunManager and CombatRoom systems,
replacing hardcoded spawning with data-driven room loading.

**File: `scripts/state_machine/run_manager.gd`**

- In `_action_generate_rooms()`:
  - Call `RoomLoader.get_available_rooms()` to retrieve available room IDs
- For each generated room, deterministically select a `room_id` using:
`RoomLoader.get_available_rooms()[topology_seed % count]`
  - Include `room_id` in each room_data dictionary

- In `_enter_room()`:
- After the existing `_combat_resolved = false` reset, call
`RoomLoader.load_room(room_data.room_id)` to load the room definition
  - Call `RoomLoader.configure_grid(room_definition)` to configure the grid
- Pass the room definition data through when emitting the `room_entered` signal
(either extend the signal signature or relay via EventBus)

**File: `scripts/autoload/event_bus.gd`**
- Update the `room_entered` signal if needed to include room definition data, OR
add a mechanism to store/relay the loaded room definition alongside the signal
- Choose the approach that minimizes coupling

**File: `scripts/core/combat_room.gd`**
- In `_ready()`, connect to `EventBus.room_entered` signal
- Add handler `_on_room_entered(room_index: int, room_data: Dictionary)`:
- If `test_mode` is false, call `RoomLoader.spawn_player(room_data,
entity_container)` and store the result in `_player`
- Call `RoomLoader.spawn_enemies(room_data, entity_container)` and store enemies
node in `_enemies_node`
- Keep `test_mode` functional for isolated testing
- Change the default value of `test_mode` to `false` for the production flow

Phase 4: Testing

Create comprehensive tests for the room loading system.

Task 1: Create Room Loader Test Suite

Build tests covering all RoomLoader functionality.

• Create tests/test_room_loader.gd extending GdUnitTestSuite
• Test load_room() with valid room_id returns expected dictionary structure
• Test load_room() with invalid room_id returns empty dictionary
• Test configure_grid() correctly converts compact format to flat tiles and calls GridSystem
• Use mock or verify GridSystem state after configuration

Task 2: Create Spawning Tests

Test entity spawning functionality in isolation.

• Test spawn_enemies() creates correct number of enemy nodes at specified positions
• Test spawn_player() creates player entity at correct position with is_player = true
• Use auto_free() pattern for all instantiated nodes
• Verify entity grid positions match room definition

Task 3: Create Integration Tests

Test the full room loading flow through RunManager.

• Test that _action_generate_rooms() produces room_data with valid room_id values
• Test that room_id selection is deterministic (same seed → same room sequence)
• Verify grid state after _enter_room() matches the loaded room definition

🤖 Prompt for AI agents

Create test files for the room loading system using the GdUnit4 framework,
following the project's existing `auto_free()` pattern.

**File: `tests/test_room_loader.gd`** (extending `GdUnitTestSuite`)

- **`load_room()` tests:**
- With a valid `room_id`, assert the returned dictionary contains expected
top-level keys (`id`, `biome`, `player_start`, `tiles`, `encounters`)
- With an invalid `room_id`, assert the returned value is an empty `Dictionary`

- **`configure_grid()` tests:**
- Provide a compact room data dictionary and assert `configure_grid()` correctly
converts it into a flat 144-entry tiles array
- Verify tile properties (elevation, cover, blocks_movement, blocks_vision) are
set correctly for sparse entries
- Verify or mock `GridSystem.load_room()` is called with the expected format;
alternatively verify GridSystem's state after configuration

- **`spawn_enemies()` tests:**
- Provide mock room data with a known encounter definition and a test container
node
  - Assert the correct number of enemy nodes are created
  - Assert each enemy is at the position specified in the room definition
  - Use `auto_free()` for all instantiated nodes

- **`spawn_player()` tests:**
- Provide mock room data with a `player_start` position and a test container
node
  - Assert a player node is returned with `is_player == true`
  - Assert the player's grid position matches `player_start`
  - Use `auto_free()` for all instantiated nodes

- **Integration tests (RunManager flow):**
- Assert `_action_generate_rooms()` produces room_data dictionaries containing a
valid `room_id`
- Assert room_id selection is deterministic: same `topology_seed` produces the
same `room_id` sequence
- After calling `_enter_room()`, verify GridSystem state matches the expected
room definition

Research

The project is a Godot 4 tactical combat game with a 12×12 grid system. GridSystem.load_room() already exists and expects a flat tiles array format with per-tile properties (x, y, elevation, cover, blocks_movement, blocks_vision). RunManager orchestrates room transitions via a state machine and emits room_entered signals with topology/encounter seeds. CombatRoom owns the entity_container where all entities (player/enemies) are spawned, currently using hardcoded test positions when test_mode=true. Only enemy_grunt.tscn exists as a spawnable enemy. No scripts/combat/ directory or config/rooms/ directory currently exists.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create the `config/rooms/` directory and populate it with 5 room definition JSON
files using a compact, sparse-array format. Each file should follow a consistent
schema.

**Directory:** `config/rooms/`

**JSON Schema per room file:**
- `id` (string): unique room identifier
- `biome` (string): room biome label
- `player_start` (object): `{ "x": int, "y": int }`
- `tiles` (object):
- `elevation` (object): `{ "tier_1": [[x,y], ...], "tier_2": [[x,y], ...] }` —
`tier_1` maps to elevation=1 (MID), `tier_2` maps to elevation=2 (HIGH)
  - `cover` (object): `{ "light": [[x,y], ...], "heavy": [[x,y], ...] }`
- `blocked` (array): `[[x,y], ...]` — tiles that block both movement and vision
- `encounters` (array): each entry has `enemy_type` (string), `count` (int),
`positions` (array of `[x,y]`)
- Include `_description` keys for inline documentation following the existing
config pattern

**Files to create:**
- `config/rooms/room_standard_01.json` — Basic open room, minimal cover, grunt
enemies in a diagonal spread
- `config/rooms/room_elevated_01.json` — Elevated terrain with tier_1 platforms
requiring vertical movement
- `config/rooms/room_cover_heavy_01.json` — Defensive layout with multiple heavy
cover positions
- `config/rooms/room_flanking_01.json` — Blocked center pillars with light cover
on the sides
- `config/rooms/room_chokepoint_01.json` — Narrow corridor with limited approach
angles

All encounters must use `"enemy_type": "grunt"` (the only available enemy type).
Each room must have a distinct `player_start` position.
===============================================================================

Task: 2

Create the `scripts/combat/` directory and implement
`scripts/combat/room_loader.gd` as a static utility class.

**File:** `scripts/combat/room_loader.gd`
- `class_name RoomLoader` extending `RefCounted`

**Method: `static func load_room(room_id: String) -> Dictionary`**
- Construct path: `res://config/rooms/{room_id}.json`
- Use `FileAccess` to open the file; if it fails, call `push_warning` and return
an empty `Dictionary`
- Parse content with `JSON.parse_string()`; on parse error, call `push_warning`
and return an empty `Dictionary`
- Return the parsed dictionary

**Method: `static func get_available_rooms() -> PackedStringArray`**
- List all `.json` files in `res://config/rooms/` and return their names
(without extension) as a `PackedStringArray`

**Method: `static func configure_grid(room_data: Dictionary) -> Error`**
- Build a flat tiles array with 144 entries (12×12 grid, all positions)
- For each `(x, y)` position, produce a dictionary with keys: `x`, `y`,
`elevation`, `cover`, `blocks_movement`, `blocks_vision`
- Check the sparse arrays in `room_data.tiles`:
- `elevation.tier_1` → elevation=1, `elevation.tier_2` → elevation=2 (default 0)
  - `cover.light` → cover=1, `cover.heavy` → cover=2 (default 0)
  - `blocked` → `blocks_movement=true`, `blocks_vision=true` (default false)
- Call `GridSystem.load_room()` via `AutoloadHelper.grid_system()` with the flat
tiles array
- Return the `Error` code from `GridSystem.load_room()`

**Method: `static func spawn_enemies(room_data: Dictionary, container: Node) ->
Array[Node2D]`**
- Create a `Node2D` named `"Enemies"` and add it as a child of `container`
- Iterate `room_data.encounters`; for each entry:
  - If `enemy_type == "grunt"`, load `res://scenes/enemies/enemy_grunt.tscn`
- For each position in `positions`, instantiate the scene, add to the enemies
node, call `entity.set_grid_position(x, y)`
- Return an array of all spawned enemy nodes

**Method: `static func spawn_player(room_data: Dictionary, container: Node) ->
Node2D`**
- Load `res://scenes/keeper.tscn`
- Instantiate and add to `container`
- Set `is_player = true` and call `set_grid_position(x, y)` using
`room_data.player_start`
- Return the player node reference
===============================================================================

Task: 3

Integrate RoomLoader into the existing RunManager and CombatRoom systems,
replacing hardcoded spawning with data-driven room loading.

**File: `scripts/state_machine/run_manager.gd`**

- In `_action_generate_rooms()`:
  - Call `RoomLoader.get_available_rooms()` to retrieve available room IDs
- For each generated room, deterministically select a `room_id` using:
`RoomLoader.get_available_rooms()[topology_seed % count]`
  - Include `room_id` in each room_data dictionary

- In `_enter_room()`:
- After the existing `_combat_resolved = false` reset, call
`RoomLoader.load_room(room_data.room_id)` to load the room definition
  - Call `RoomLoader.configure_grid(room_definition)` to configure the grid
- Pass the room definition data through when emitting the `room_entered` signal
(either extend the signal signature or relay via EventBus)

**File: `scripts/autoload/event_bus.gd`**
- Update the `room_entered` signal if needed to include room definition data, OR
add a mechanism to store/relay the loaded room definition alongside the signal
- Choose the approach that minimizes coupling

**File: `scripts/core/combat_room.gd`**
- In `_ready()`, connect to `EventBus.room_entered` signal
- Add handler `_on_room_entered(room_index: int, room_data: Dictionary)`:
- If `test_mode` is false, call `RoomLoader.spawn_player(room_data,
entity_container)` and store the result in `_player`
- Call `RoomLoader.spawn_enemies(room_data, entity_container)` and store enemies
node in `_enemies_node`
- Keep `test_mode` functional for isolated testing
- Change the default value of `test_mode` to `false` for the production flow
===============================================================================

Task: 4

Create test files for the room loading system using the GdUnit4 framework,
following the project's existing `auto_free()` pattern.

**File: `tests/test_room_loader.gd`** (extending `GdUnitTestSuite`)

- **`load_room()` tests:**
- With a valid `room_id`, assert the returned dictionary contains expected
top-level keys (`id`, `biome`, `player_start`, `tiles`, `encounters`)
- With an invalid `room_id`, assert the returned value is an empty `Dictionary`

- **`configure_grid()` tests:**
- Provide a compact room data dictionary and assert `configure_grid()` correctly
converts it into a flat 144-entry tiles array
- Verify tile properties (elevation, cover, blocks_movement, blocks_vision) are
set correctly for sparse entries
- Verify or mock `GridSystem.load_room()` is called with the expected format;
alternatively verify GridSystem's state after configuration

- **`spawn_enemies()` tests:**
- Provide mock room data with a known encounter definition and a test container
node
  - Assert the correct number of enemy nodes are created
  - Assert each enemy is at the position specified in the room definition
  - Use `auto_free()` for all instantiated nodes

- **`spawn_player()` tests:**
- Provide mock room data with a `player_start` position and a test container
node
  - Assert a player node is returned with `is_player == true`
  - Assert the player's grid position matches `player_start`
  - Use `auto_free()` for all instantiated nodes

- **Integration tests (RunManager flow):**
- Assert `_action_generate_rooms()` produces room_data dictionaries containing a
valid `room_id`
- Assert room_id selection is deterministic: same `topology_seed` produces the
same `room_id` sequence
- After calling `_enter_room()`, verify GridSystem state matches the expected
room definition

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!