yaze/scripts/README_analyze_room.md

Room Object Analyzer (analyze_room.py)

A Python script for analyzing dungeon room object data from A Link to the Past ROMs. Useful for debugging layer compositing, understanding room structure, and validating draw routine implementations.

Requirements

• Python 3.6+
• A Link to the Past ROM file (vanilla .sfc)

Basic Usage

# Analyze a single room
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1

# Analyze multiple rooms
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1 2 3

# Analyze a range of rooms
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc --range 0 10

# Analyze all 296 rooms (summary only)
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc --all

Common Options

Option	Description
--rom PATH	Path to the ROM file
--compositing	Include layer compositing analysis
--list-bg2	List all rooms with BG2 overlay objects
--json	Output as JSON for programmatic use
--summary	Show summary only (object counts)
--quiet	Minimal output

Layer Analysis

The script identifies objects by their layer assignment:

Layer	Buffer	Description
Layer 0	BG1 Main	Primary floor/walls
Layer 1	BG2 Overlay	Background details (platforms, statues)
Layer 2	BG1 Priority	Priority objects on BG1 (torches)

Finding Rooms with BG2 Overlay Issues

# List all 94 rooms with BG2 overlay objects
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc --list-bg2

# Analyze specific room's layer compositing
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1 --compositing

Output Format

Default Output

======================================================================
ROOM 001 (0x001) OBJECT ANALYSIS
======================================================================
Room data at PC: 0x5230F (SNES: 0x8AA30F)
Floor: BG1=6, BG2=6, Layout=4

OBJECTS (Layer 0=BG1 main, Layer 1=BG2 overlay, Layer 2=BG1 priority)
======================================================================
  L0 (BG1_Main): [FC 21 C0] -> T2 ID=0x100 @ ( 2, 7) sz= 0 - Corner NW (concave)
  ...
  L1 (BG2_Overlay): [59 34 33] -> T1 ID=0x033 @ (22,13) sz= 4 - Floor 4x4
  ...

JSON Output

python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1 --json > room_001.json

{
  "room_id": 1,
  "floor1": 6,
  "floor2": 6,
  "layout": 4,
  "objects_by_layer": {
    "0": [...],
    "1": [...],
    "2": [...]
  }
}

Object Decoding

Objects are decoded based on their type:

Type	Byte Pattern	ID Range	Description
Type 1	xxxxxxss yyyyyyss iiiiiiii	0x00-0xFF	Standard objects
Type 2	111111xx xxxxyyyy yyiiiiii	0x100-0x1FF	Layout corners
Type 3	xxxxxxii yyyyyyii 11111iii	0xF00-0xFFF	Interactive objects

Integration with yaze Development

Validating Draw Routine Fixes

1. Find rooms using a specific object:

   python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc --all --json | \
     python3 -c "import json,sys; d=json.load(sys.stdin); print([r['room_id'] for r in d if any(o['id']==0x033 for l in r['objects_by_layer'].values() for o in l)])"
   

2. Test BG2 masking on affected rooms:

   for room in $(python3 scripts/analyze_room.py --list-bg2 | grep "Room" | awk '{print $2}'); do
     echo "Testing room $room"
   done
   

Debugging Object Dimensions

Compare script output with CalculateObjectDimensions in object_drawer.cc:

# Get Room 001 Layer 1 objects with sizes
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1 | grep "L1"

Expected dimension calculations:

• 0x033 @ (22,13) size=4: routine 16, count=5, width=160px, height=32px
• 0x034 @ (23,16) size=14: routine 25, count=18, width=144px, height=8px

ROM Address Reference

Data	Address	Notes
Object Pointers	0x874C	3 bytes per room
Header Pointers	0xB5DD	Room header data
Total Rooms	296	0x128 rooms

Example: Room 001 Analysis

Room 001 is a good test case for BG2 overlay debugging:

python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1 --compositing

Key objects on Layer 1 (BG2):

• Platform floor (0x033) at center
• Statues (0x038) near stairs
• Solid tiles (0x034, 0x071) for platform edges
• Inter-room stairs (0x13B)

These objects should create "holes" in BG1 floor tiles to show through.