BreakEscape/planning_notes/new_room_layout/TERMINOLOGY.md

Terminology Guide

Tile vs Grid Unit

Tile (32px)

• Definition: The smallest visual unit in Tiled
• Size: 32px × 32px
• Usage: Building block for all room graphics
• Example: A door is 1 tile wide × 2 tiles tall

Grid Unit (5×4 tiles = 160×128px)

• Definition: The minimum stackable room size unit
• Size: 5 tiles wide × 4 tiles tall (excluding top 2 visual rows)
• Usage: Room sizes are specified as multiples of grid units
• Example: A standard room is 2×2 grid units (10×8 tiles)

Why 5×4?

• 5 tiles wide: 1 for each side wall + 3 floor tiles minimum
• 4 tiles tall: Excludes the 2 top visual wall tiles, counts stackable area only

Room Dimensions

Total Size

• Definition: Complete room including all walls and visual elements
• Measurement: Includes top 2 visual wall rows
• Example: Standard room is 10 tiles wide × 8 tiles tall total

Stacking Size

• Definition: The area that cannot overlap with other rooms
• Measurement: Excludes top 2 visual wall rows
• Example: Standard room has 10×6 tiles stacking size (but we think in grid units: 2×1.5)
• Note: For positioning, we use grid units (2×2) since we always align to grid boundaries

Floor Area

• Definition: Interior walkable space (excluding walls)
• Measurement: Total size minus all walls
• Example: Standard room (10×8 tiles) has ~6×4 floor area

Directions

Connection Directions

• North: Rooms above current room
• South: Rooms below current room
• East: Rooms to the right of current room
• West: Rooms to the left of current room

Visual Direction

• Top of Screen: North (furthest from player viewpoint)
• Bottom of Screen: South (closest to player viewpoint)

Positioning

World Coordinates

• Definition: Absolute pixel positions in the game world
• Origin: (0, 0) typically at the starting room's top-left
• Usage: Final position where room sprites are rendered

Grid Coordinates

• Definition: Position in grid units from origin
• Origin: Starting room at grid position (0, 0)
• Usage: Used for deterministic door placement calculations
• Conversion: worldX = gridX × 160, worldY = gridY × 128

Room Position

• Definition: The top-left corner of a room's stacking area in world coordinates
• Usage: Where Phaser renders the room tilemap
• Note: This is the position used in window.roomPositions[roomId]

Connections

Single Connection

"connections": {
  "north": "office2"
}

• One room connected in the specified direction

Multiple Connections

"connections": {
  "north": ["office2", "office3"]
}

• Array of rooms connected in the same direction
• Rooms are positioned left-to-right (west-to-east)

Bidirectional Connections

// In room1:
"connections": { "north": "room2" }

// In room2:
"connections": { "south": "room1" }

• Connections must be reciprocal for doors to work correctly

Doors

Door Position

• North/South Doors: Placed in corners of the room
• East/West Doors: Placed at edges based on connection count
• Alignment: Doors from two connecting rooms must align perfectly

Door Sprite

• North/South: 1 tile wide × 2 tiles tall (door_32.png)
• East/West: 1 tile wide × 1 tile tall (door_side_sheet_32.png)
• Layered: Two door sprites (one for each room) stack at same position

Door State

• Closed: Collision enabled, blocks passage
• Open: Sprite destroyed, collision removed, passage clear
• Locked: Requires unlock minigame before opening

Walls

Visual Wall

• Definition: The top 2 rows of tiles showing wall from orthogonal view
• Behavior: Overlaps the room to the north visually
• Collision: No collision (purely visual)

Collision Wall

• Definition: Invisible collision boxes at room boundaries
• Placement: At the border between wall tiles and floor tiles
• Exception: No collision at door positions

Wall Tiles

• Side Walls: Leftmost and rightmost columns of tiles
• Top Wall: Top 2 rows of tiles
• Bottom Wall: Bottom row of tiles (treated specially)

Validation

Overlap Detection

• Definition: Checking if two rooms' stacking areas occupy the same grid units
• Timing: Performed during scenario load
• Action: Log clear error but attempt to continue

Grid Alignment

• Definition: Ensuring all rooms are positioned at grid unit boundaries
• Requirement: Room positions must be multiples of grid unit size (160×128px)
• Purpose: Ensures consistent layout and door alignment

Special Cases

Hallway

• Definition: A connector room explicitly defined in scenario
• Typical Size: 2×1 or 4×1 grid units (long and narrow)
• Purpose: Connects multiple rooms without gaps
• Example:

[Room1][Room2]
[--Hallway--]
[--Room0---]

Closet

• Definition: Smallest room size (1×1 grid unit)
• Size: 5 tiles wide × 4 tiles tall
• Usage: Small storage rooms, utility spaces

Corner Alignment

• Definition: When a room's corner touches another room's corner
• Current Behavior: Creates a gap (undesired)
• New Behavior: Rooms stack flush against each other