# Oracle of Secrets ROM Hack Expert Knowledge

## Custom Memory Regions

### WRAM ($7E0730-$7E078F) - 96 bytes custom
- $7E0730: MenuScrollLevelV (menu system)
- $7E0731: MenuScrollLevelH  
- $7E0739: GoldstarOrHookshot (item differentiation)
- $7E073A: Neck_Index (multi-part boss sprites)
- $7E0741-0743: Offspring IDs (boss mechanics)
- $7E0745: FishingOrPortalRod

### SRAM Custom Variables
- $7EF3D6: OOSPROG (main progression bitfield)
- $7EF3C6: OOSPROG2 (secondary progression)
- $7EF347-358: Masks (Zora, Bunny, Deku, Wolf, Stone)
- $7EF38A-3C4: Collectibles (Bananas, Seashells, Scrolls, etc.)
- $7EF410: Dreams (Courage/Power/Wisdom collectibles)

## Custom ROM Banks
- Bank $20 ($208000): Expanded Music
- Bank $28 ($288000): ZSCustomOverworld data/code
- Bank $2B ($2B8000): Items
- Bank $2C ($2C8000): Dungeons
- Bank $2D ($2D8000): Menu
- Bank $30-32 ($308000+): Sprites (3 banks)
- Bank $33-3B: Mask transformation graphics
- Bank $40-41: Custom overworld maps (LW/DW)

## Namespace Architecture

### Oracle Namespace
Most custom code in `namespace Oracle {}`:
- Items/, Menu/, Masks/, Sprites/, Core/

### ZScream (No Namespace)
ZSCustomOverworld.asm operates outside namespace
Hook vanilla addresses directly

### Cross-Namespace Pattern
**Oracle calling ZScream:**
```asm
namespace Oracle {
  JSL Oracle_ZScreamFunction  // Use Oracle_ prefix
}
```

**ZScream calling Oracle (bridge):**
```asm
ZSO_BridgeFunction:
  JSL Oracle_OracleFunction
  RTL

namespace Oracle {
  Oracle_ZSO_BridgeFunction = ZSO_BridgeFunction
}
```

## ZScream Tables ($288000+)
- BGColorTable: Background colors per screen
- MainPaletteTable: Palette group indices
- AnimatedTable: Animated tile GFX IDs
- OverlayTable: Weather/effect overlays (0x9F=rain, 0xFF=none)
- OWGFXGroupTable: 8 GFX sheets per screen
- Overworld_ActualScreenID_New: Parent screen for 2x2 areas
- Overworld_SpritePointers_state_X: Sprite sets per game state

## Day/Night System Integration
Oracle adds time system with 6 states:
- State 0-2: Day (base game states)
- State 3-5: Night (parallel states)
- CheckIfNight16Bit: Returns state offset for night

Sprite loading checks time and uses offset pointers

## Processor State Safety
**CRITICAL:** Always PHP/PLP when crossing namespaces
ZScream uses 8-bit mode, Oracle often uses 16-bit
Mismatch = BRK crash

## Common Debugging
**BRK Crash:** Check stack with Mesen-S, look for RTL without JSL
**Missing Graphics:** Verify GFX slot assignment (0-6)
**Wrong Sprites:** Check sprite pointer table for current game state
**Palette Issues:** Day/night transition may need palette reload

## Tool Usage for Oracle ROMs
When analyzing custom features:
1. hex-read custom WRAM ($7E0730+) to check states
2. hex-read SRAM ($7EF3D6, $7EF410) for progression
3. hex-search for custom sprite IDs (>0xF3 often custom)
4. palette-analyze for day/night palette differences

When editing Oracle ROMs:
1. Check OOSPROG flags before major edits
2. Verify namespace exports exist
3. Test day AND night variants
4. Ensure processor state preserved across boundaries