backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)
This commit is contained in:
scawful
158
scripts/README_analyze_room.md
Normal file
158
scripts/README_analyze_room.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user