# Test Scenarios for Grid-Based Room Layout System

This directory contains test scenarios designed to validate and demonstrate the new grid-based room layout system.

## Grid Unit System Overview

- **Base Grid Unit (GU)**: 5 tiles wide × 4 tiles tall (160px × 128px)
- **Tile Size**: 32px × 32px
- **Valid Room Widths**: Multiples of 5 tiles (5, 10, 15, 20, 25...)
- **Valid Room Heights**: Formula `2 + (N × 4)` where N ≥ 1
  - Valid: 6, 10, 14, 18, 22, 26...
  - Invalid: 7, 8, 9, 11, 12, 13...

## Room Size Examples

| Type | Size (GU) | Tiles (W×H) | Pixels (W×H) | File |
|------|-----------|-------------|--------------|------|
| Closet | 1×1 | 5×6 | 160×192 | small_room_1x1gu.json* |
| Hall (Vertical) | 1×2 | 5×10 | 160×320 | hall_1x2gu.json* |
| Standard | 2×2 | 10×10 | 320×320 | room_office2.json, room_ceo2.json, etc. |
| Wide Hall | 4×1 | 20×6 | 640×192 | (to be created) |

*Note: These room files are referenced in test scenarios but need to be created in assets/rooms/

## Test Scenarios

### 1. test_vertical_layout.json
**Purpose**: Test traditional vertical stacking with north/south connections

**Layout**:
```
    [CEO Office]
         ↑
 [Office1][Office2]
     ↑       ↑
   [Reception]
```

**Tests**:
- Single north connection (Reception → Offices)
- Multiple north connections (Offices → CEO)
- Door alignment between 2x2 GU rooms
- Grid-based positioning
- Deterministic door placement (alternating corners)

**Rooms Used**: All 2×2 GU (room_reception2, room_office2, room_ceo2)

---

### 2. test_horizontal_layout.json
**Purpose**: Test east/west connections and four-direction navigation

**Layout**:
```
[Storage] ← [Office] → [Servers]
               ↑
          [Reception]
```

**Tests**:
- East/West connections
- Single door placement on east/west edges
- Four-direction connection support
- Side door alignment
- Mixed direction connections in one room

**Rooms Used**: All 2×2 GU

---

### 3. test_complex_multidirection.json
**Purpose**: Test complex layouts using all four directions

**Layout**:
```
   [Storage]    [CEO]
       ↑          ↑
   [Office1] ← [Office2] → [Servers]
                  ↑
             [Reception]
```

**Tests**:
- All four directions in use
- Central hub room with 4 connections
- Complex navigation requiring backtracking
- Door alignment in all directions
- Grid-based positioning for complex layouts

**Rooms Used**: All 2×2 GU

---

### 4. test_multiple_connections.json
**Purpose**: Test multiple room connections in the same direction

**Layout**:
```
   [Server1][Server2][Server3]
        ↑       ↑       ↑
      [---- Hub ----]
             ↑
        [Reception]
```

**Tests**:
- Multiple connections in one direction (Hub has 3 north connections)
- Door spacing across room width
- Alignment of multiple doors
- Array-based connection syntax
- Asymmetric connection handling (hub: 3 north doors, each server: 1 south door)

**Rooms Used**: All 2×2 GU

---

### 5. test_mixed_room_sizes.json
**Purpose**: Test different room sizes and door alignment between them

**Layout** (when smaller rooms are available):
```
  [Closet-1×1] [CEO-2×2]
         ↑        ↑
    [Hall-1×2 GU]
         ↑
  [Reception-2×2]
```

**Tests**:
- Different room sizes in same scenario
- Door alignment between different-sized rooms
- Centering of smaller rooms on larger rooms
- Grid-based positioning with varied dimensions

**Rooms Used**:
- Currently: All 2×2 GU placeholders
- Future: small_room_1x1gu.json, hall_1x2gu.json, room_reception2.json, room_ceo2.json

**Note**: This scenario includes documentation about the proper room sizes and will demonstrate true size variety once the 1×1 GU and 1×2 GU room files are created.

---

## How to Test

1. **Load a test scenario** in the game
2. **Check the console** for positioning and validation logs:
   - Room positions (grid coordinates)
   - Door placement calculations
   - Overlap detection results
3. **Verify visually**:
   - Rooms align properly on grid boundaries
   - Doors connect rooms correctly
   - No visual gaps or overlaps
   - Player can navigate through all doors
4. **Check door alignment**:
   - Doors should align perfectly between connecting rooms
   - Multiple doors should be evenly spaced
   - East/West doors should be on room edges

## Expected Console Output

When loading a test scenario, you should see:
```
=== Room Positioning Algorithm ===
Room reception: 10×10 tiles (2×2 grid units)
Room office1: 10×10 tiles (2×2 grid units)
...
Starting room: reception at (0, 0)

Processing: reception at (0, 0)
  north: office1, office2
    office1 positioned at (-160, -256)
    office2 positioned at (160, -256)
...

=== Validating Room Positions ===
✅ No overlaps detected

=== Final Room Positions ===
reception: (0, 0) [320×320px]
office1: (-160, -256) [320×320px]
...
```

## Validation Checks

Each test scenario should pass these checks:
- [ ] All rooms load without errors
- [ ] No room overlap warnings
- [ ] All doors align correctly (verified in console)
- [ ] Player can navigate through all connections
- [ ] Rooms appear visually aligned to grid
- [ ] Multiple doors are evenly spaced
- [ ] Door sprites face the correct direction

## Creating Additional Room Files

To fully test the mixed room sizes scenario, create these room files in Tiled:

### small_room_1x1gu.json (1×1 GU Closet)
- Dimensions: 5 tiles wide × 6 tiles tall
- Layers: walls, room, doors
- Use closet/storage tileset
- Place door markers in appropriate positions

### hall_1x2gu.json (1×2 GU Hallway)
- Dimensions: 5 tiles wide × 10 tiles tall
- Layers: walls, room, doors
- Use hallway tileset
- Suitable for vertical corridors

## Troubleshooting

**Doors don't align**:
- Check room dimensions follow the formula (2 + 4N for height)
- Verify rooms are positioned on grid boundaries
- Check console for positioning logs

**Rooms overlap**:
- Check connection definitions (ensure no circular dependencies)
- Verify room dimensions are valid
- Check validation output in console

**Can't navigate through doors**:
- Verify door collision is set up correctly
- Check that both rooms reference each other in connections
- Ensure lockType/requires properties are correct if doors are locked

## Future Enhancements

Additional test scenarios to create:
- [ ] Wide hallway connector (4×1 GU)
- [ ] Maximum connections (testing limits)
- [ ] East/West multiple connections (stacked vertically)
- [ ] Mixed size complex layout (all sizes together)
- [ ] Edge cases (single-tile-wide rooms, very tall rooms)

---

**Last Updated**: 2025-11-16
**Grid System Version**: 2.0
**Compatible with**: New grid-based room layout system