159 lines
4.5 KiB
Markdown
159 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
python3 scripts/analyze_room.py --rom roms/alttp_vanilla.sfc 1 --json > room_001.json
|
|
```
|
|
|
|
```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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
|