add docs for asm style guide and oracle system architecture
This commit is contained in:
scawful
540
Docs/Core/StyleGuide.md
Normal file
540
Docs/Core/StyleGuide.md
Normal file
@@ -0,0 +1,540 @@
|
||||
# Oracle of Secrets: 65816 ASM Style Guide
|
||||
|
||||
**Version**: 1.0
|
||||
**Purpose**: Reduce AI errors and ensure consistent code quality across the codebase.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
### Label Naming
|
||||
|
||||
| Type | Pattern | Example |
|
||||
|------|---------|---------|
|
||||
| Sprite function | `Sprite_{Name}_{Type}` | `Sprite_Booki_Main`, `Sprite_Darknut_Draw` |
|
||||
| Menu function | `Menu_{Purpose}` | `Menu_InitGraphics`, `Menu_DrawBackground` |
|
||||
| Link/Player | `Link_{Action}` | `Link_ConsumeMagicBagItem`, `Link_HandleYItem` |
|
||||
| Oracle namespace | `Oracle_{Function}` | `Oracle_CheckIfNight`, `Oracle_MainEntry` |
|
||||
| Local labels | `.lowercase_with_underscores` | `.not_being_pushed`, `.nextTile` |
|
||||
| Constants (macro) | `!UPPERCASE` | `!SPRID`, `!Health`, `!Damage` |
|
||||
| Memory addresses | `CamelCase` | `SprAction`, `LinkState`, `OOSPROG` |
|
||||
|
||||
### Processor State Checklist
|
||||
|
||||
- [ ] Always use size suffixes (`.b`, `.w`, `.l`) for ambiguous operations
|
||||
- [ ] Use `PHP`/`PLP` for functions called from unknown context
|
||||
- [ ] `REP #$30` = 16-bit A and X/Y, `SEP #$30` = 8-bit
|
||||
- [ ] `REP #$20` / `SEP #$20` = A only
|
||||
- [ ] `REP #$10` / `SEP #$10` = X/Y only
|
||||
|
||||
### Call Convention Checklist
|
||||
|
||||
- [ ] `JSL`/`RTL` for cross-bank calls (3-byte return address)
|
||||
- [ ] `JSR`/`RTS` for same-bank calls (2-byte return address)
|
||||
- [ ] **NEVER MIX** - mismatch causes crashes
|
||||
- [ ] External hooks use `JSL`, internal helpers use `JSR`
|
||||
|
||||
---
|
||||
|
||||
## 1. File Structure
|
||||
|
||||
### 1.1 File Header (Required for new files)
|
||||
|
||||
```asm
|
||||
; =========================================================
|
||||
; File: sprites/enemies/my_enemy.asm
|
||||
; Purpose: [Brief description of what this file implements]
|
||||
; Author: [Your name or handle]
|
||||
; =========================================================
|
||||
```
|
||||
|
||||
### 1.2 Section Organization
|
||||
|
||||
```asm
|
||||
; =========================================================
|
||||
; Sprite Properties
|
||||
; =========================================================
|
||||
!SPRID = $XX
|
||||
!NbrTiles = 02
|
||||
; ... (30 properties in standard order)
|
||||
|
||||
; =========================================================
|
||||
; Entry Points
|
||||
; =========================================================
|
||||
Sprite_MyEnemy_Long:
|
||||
{ ... }
|
||||
|
||||
Sprite_MyEnemy_Prep:
|
||||
{ ... }
|
||||
|
||||
; =========================================================
|
||||
; Main Logic
|
||||
; =========================================================
|
||||
Sprite_MyEnemy_Main:
|
||||
{ ... }
|
||||
|
||||
; =========================================================
|
||||
; Drawing
|
||||
; =========================================================
|
||||
Sprite_MyEnemy_Draw:
|
||||
{ ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Naming Conventions
|
||||
|
||||
### 2.1 Labels
|
||||
|
||||
**PascalCase with underscores for hierarchy:**
|
||||
|
||||
```asm
|
||||
; Good
|
||||
Sprite_Booki_Main
|
||||
Menu_InitGraphics
|
||||
Link_ConsumeMagicBagItem
|
||||
Oracle_CheckIfNight
|
||||
|
||||
; Bad
|
||||
spriteBookiMain ; No underscores
|
||||
sprite_booki_main ; All lowercase
|
||||
SPRITE_BOOKI_MAIN ; All uppercase
|
||||
```
|
||||
|
||||
### 2.2 Local Labels
|
||||
|
||||
**Lowercase with dot prefix:**
|
||||
|
||||
```asm
|
||||
Sprite_Move:
|
||||
{
|
||||
LDA.w SprAction, X : BNE .already_moving
|
||||
; Start movement
|
||||
INC.w SprAction, X
|
||||
.already_moving
|
||||
RTS
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 Constants and Macros
|
||||
|
||||
```asm
|
||||
; Macro parameters: !UPPERCASE
|
||||
!SPRID = $D5
|
||||
!Health = 08
|
||||
!Damage = 02
|
||||
|
||||
; Debug flags: !UPPERCASE with LOG prefix
|
||||
!DEBUG = 1
|
||||
!LOG_MUSIC = 1
|
||||
!LOG_SPRITES = 0
|
||||
|
||||
; Memory addresses: CamelCase (matching vanilla convention)
|
||||
SprAction = $0D80
|
||||
LinkState = $5D
|
||||
OOSPROG = $7EF3D6
|
||||
```
|
||||
|
||||
### 2.4 Sprite Property Standard Order
|
||||
|
||||
All sprites MUST define properties in this order:
|
||||
|
||||
```asm
|
||||
!SPRID = Sprite_MyEnemyID
|
||||
!NbrTiles = 02
|
||||
!Harmless = 00
|
||||
!Health = 08
|
||||
!Damage = 02
|
||||
!DeathAnimation = 00
|
||||
!ImperviousArrow = 00
|
||||
!ImperviousSword = 00
|
||||
!Boss = 00
|
||||
!Shadow = 01
|
||||
!Palette = 00
|
||||
!Hitbox = $00
|
||||
!Persist = 00
|
||||
!Statis = 00
|
||||
!CollisionLayer = 00
|
||||
!CanFall = 01
|
||||
!DeflectProjectiles = 00
|
||||
!WaterSprite = 00
|
||||
!Blockable = 00
|
||||
!Prize = 00
|
||||
!Sound = $00
|
||||
!Interaction = $00
|
||||
!Subtype2 = 00
|
||||
%Set_Sprite_Properties(Sprite_MyEnemy_Prep, Sprite_MyEnemy_Long)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Scoping and Indentation
|
||||
|
||||
### 3.1 Bracket Scoping
|
||||
|
||||
**ALL functions use `{ }` brackets** (NOT `subroutine`/`endsubroutine`):
|
||||
|
||||
```asm
|
||||
Sprite_Booki_Main:
|
||||
{
|
||||
LDA.w SprAction, X
|
||||
JSL JumpTableLocal
|
||||
dw StalkPlayer
|
||||
dw HideFromPlayer
|
||||
dw ApproachPlayer
|
||||
|
||||
StalkPlayer:
|
||||
{
|
||||
%PlayAnimation(0,1,16)
|
||||
JSR Sprite_Booki_Move
|
||||
RTS
|
||||
}
|
||||
|
||||
HideFromPlayer:
|
||||
{
|
||||
; Nested content indented 2 spaces
|
||||
LDA.b #$00
|
||||
STA.w SprAction, X
|
||||
RTS
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Indentation Rules
|
||||
|
||||
- **2-space indentation** for all nested content
|
||||
- Local labels at same indentation as containing block
|
||||
- Conditional code indented under branch:
|
||||
|
||||
```asm
|
||||
JSL Sprite_CheckActive : BCC .inactive
|
||||
; Active sprite code (indented)
|
||||
JSR DoActiveStuff
|
||||
.inactive
|
||||
PLB
|
||||
RTL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Processor State Management
|
||||
|
||||
### 4.1 Size Suffixes (REQUIRED)
|
||||
|
||||
Always use explicit size suffixes when processor state matters:
|
||||
|
||||
```asm
|
||||
; Good - explicit sizes
|
||||
LDA.w #$1234 ; 16-bit load
|
||||
LDA.b #$12 ; 8-bit load
|
||||
STA.l $7E0000 ; Long address
|
||||
|
||||
; Bad - ambiguous
|
||||
LDA #$12 ; Is this 8-bit or 16-bit?
|
||||
```
|
||||
|
||||
### 4.2 State Preservation
|
||||
|
||||
```asm
|
||||
; Functions called from unknown context
|
||||
SomePublicFunction:
|
||||
{
|
||||
PHP ; Save caller's state
|
||||
SEP #$30 ; Set known state (8-bit A, X/Y)
|
||||
|
||||
; ... function body ...
|
||||
|
||||
PLP ; Restore caller's state
|
||||
RTL
|
||||
}
|
||||
|
||||
; Internal helpers can assume state from caller
|
||||
.helper:
|
||||
; Assume 8-bit A from caller
|
||||
LDA.b #$00
|
||||
RTS
|
||||
```
|
||||
|
||||
### 4.3 Processor Mode Macros
|
||||
|
||||
Use these macros for clarity:
|
||||
|
||||
```asm
|
||||
%m8() ; SEP #$20 - 8-bit accumulator
|
||||
%m16() ; REP #$20 - 16-bit accumulator
|
||||
%a8() ; SEP #$20 - 8-bit A (alias)
|
||||
%a16() ; REP #$20 - 16-bit A (alias)
|
||||
%index8() ; SEP #$10 - 8-bit X/Y
|
||||
%index16() ; REP #$10 - 16-bit X/Y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Hook and Patch Patterns
|
||||
|
||||
### 5.1 Small Patches (pushpc/pullpc)
|
||||
|
||||
```asm
|
||||
pushpc
|
||||
org $1EF27D
|
||||
ShopItem_Banana:
|
||||
{
|
||||
JSR $F4CE ; SpriteDraw_ShopItem
|
||||
; Custom code here
|
||||
RTS
|
||||
}
|
||||
assert pc() <= $1EF2AB ; Ensure we fit
|
||||
pullpc
|
||||
```
|
||||
|
||||
### 5.2 Hook Pattern
|
||||
|
||||
```asm
|
||||
; In patches.asm or near related code
|
||||
pushpc
|
||||
org $02XXXX ; Vanilla address
|
||||
JSL MyCustomHook ; 4-byte JSL
|
||||
NOP ; Pad if needed
|
||||
pullpc
|
||||
|
||||
; The hook implementation
|
||||
MyCustomHook:
|
||||
{
|
||||
; Preserve any clobbered code
|
||||
JSL OriginalRoutine
|
||||
|
||||
; Add custom logic
|
||||
LDA.w CustomFlag : BEQ .skip
|
||||
JSL DoCustomThing
|
||||
.skip
|
||||
|
||||
RTL
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Hook Documentation
|
||||
|
||||
```asm
|
||||
; =========================================================
|
||||
; Hook: $02XXXX - Link's Y-Button Handler
|
||||
; Purpose: Add custom item handling for Magic Bag
|
||||
; Vanilla Code Replaced: JSL $07F44C
|
||||
; Side Effects: Clobbers A
|
||||
; =========================================================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Comments and Documentation
|
||||
|
||||
### 6.1 Section Dividers
|
||||
|
||||
Use exactly 57 equal signs:
|
||||
|
||||
```asm
|
||||
; =========================================================
|
||||
; Section Name
|
||||
; =========================================================
|
||||
```
|
||||
|
||||
### 6.2 Bitfield Documentation
|
||||
|
||||
```asm
|
||||
; Bitfield: hmwo oooo
|
||||
; o - OAM slot count (bits 0-4)
|
||||
; w - Wall-seeking behavior
|
||||
; m - Master sword ceremony flag
|
||||
; h - Harmless (no contact damage)
|
||||
SprNbrOAM = $0E40
|
||||
```
|
||||
|
||||
### 6.3 TODO Comments
|
||||
|
||||
```asm
|
||||
; TODO: Add chase animation when player is detected
|
||||
; TODO(scawful): Refactor this to use lookup table
|
||||
```
|
||||
|
||||
### 6.4 Magic Number Documentation
|
||||
|
||||
```asm
|
||||
LDA.b #$08 ; 8-frame animation delay
|
||||
CMP.w #$0100 ; Check if past screen boundary (256px)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Memory and Data Structures
|
||||
|
||||
### 7.1 Struct Definitions
|
||||
|
||||
```asm
|
||||
struct TimeState $7EE000
|
||||
{
|
||||
.Hours: skip 1
|
||||
.Minutes: skip 1
|
||||
.Speed: skip 1
|
||||
.Padding: skip 13
|
||||
.BlueVal: skip 2
|
||||
.GreenVal: skip 2
|
||||
.RedVal: skip 2
|
||||
}
|
||||
endstruct
|
||||
```
|
||||
|
||||
### 7.2 Inline Data Tables
|
||||
|
||||
```asm
|
||||
Sprite_Draw:
|
||||
{
|
||||
; ... draw code ...
|
||||
RTS
|
||||
|
||||
; Data tables use dot notation
|
||||
.start_index
|
||||
db $00, $04, $08, $0C
|
||||
.nbr_of_tiles
|
||||
db 3, 3, 3, 3
|
||||
.x_offsets
|
||||
dw 4, -4, 4, -4
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Prevention Checklist
|
||||
|
||||
### Before Submitting Code
|
||||
|
||||
- [ ] All labels use correct PascalCase_With_Underscores
|
||||
- [ ] All local labels use .dot_notation
|
||||
- [ ] Size suffixes on all ambiguous loads/stores
|
||||
- [ ] JSL/RTL and JSR/RTS pairs matched correctly
|
||||
- [ ] Hooks have `assert` statements to prevent overflow
|
||||
- [ ] Magic numbers have inline comments explaining purpose
|
||||
- [ ] Sprite properties in standard order
|
||||
- [ ] Section dividers between major code blocks
|
||||
|
||||
### Common Crash Causes
|
||||
|
||||
1. **JSL/JSR mismatch** - Using RTL with JSR or RTS with JSL
|
||||
2. **Bank crossing** - Forgetting to set DBR with PHK:PLB
|
||||
3. **Processor state** - Assuming 8-bit when 16-bit or vice versa
|
||||
4. **Hook overflow** - Patch exceeds available space
|
||||
5. **Missing pullpc** - Stack imbalance from pushpc
|
||||
|
||||
---
|
||||
|
||||
## 9. Oracle of Secrets Specific Patterns
|
||||
|
||||
### 9.1 Sprite Entry Point Pattern
|
||||
|
||||
```asm
|
||||
Sprite_MyEnemy_Long:
|
||||
{
|
||||
PHB : PHK : PLB ; Set data bank to current bank
|
||||
JSR Sprite_MyEnemy_Draw
|
||||
JSL Sprite_DrawShadow
|
||||
JSL Sprite_CheckActive : BCC .inactive
|
||||
JSR Sprite_MyEnemy_Main
|
||||
.inactive
|
||||
PLB
|
||||
RTL
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 State Machine Pattern
|
||||
|
||||
```asm
|
||||
Sprite_MyEnemy_Main:
|
||||
{
|
||||
LDA.w SprAction, X
|
||||
JSL JumpTableLocal
|
||||
dw State_Idle
|
||||
dw State_Chase
|
||||
dw State_Attack
|
||||
dw State_Retreat
|
||||
|
||||
State_Idle:
|
||||
{
|
||||
%PlayAnimation(0,1,16)
|
||||
; Check for player proximity
|
||||
JSL Sprite_CheckDamageToLink
|
||||
BCC .stay_idle
|
||||
INC.w SprAction, X ; Transition to Chase
|
||||
.stay_idle
|
||||
RTS
|
||||
}
|
||||
; ... more states ...
|
||||
}
|
||||
```
|
||||
|
||||
### 9.3 SRAM Flag Checking
|
||||
|
||||
```asm
|
||||
; Check Oracle progression flag
|
||||
LDA.l OOSPROG : AND.b #$01 : BEQ .not_complete
|
||||
; Player has completed this milestone
|
||||
.not_complete
|
||||
|
||||
; Bitfield reference for OOSPROG ($7EF3D6):
|
||||
; .fmp h.i.
|
||||
; i = Intro complete
|
||||
; h = Hall of Secrets visited
|
||||
; p = Pendant progress
|
||||
; m = Master Sword acquired
|
||||
; f = Fortress of Secrets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. AI Agent Instructions
|
||||
|
||||
### 10.1 Before Writing Code
|
||||
|
||||
1. **Read existing patterns** - Search for similar implementations
|
||||
2. **Check memory map** - Verify address usage won't conflict
|
||||
3. **Identify hook points** - Use Hyrule Historian to find vanilla code
|
||||
4. **Verify bank space** - Check MemoryMap.md for free space
|
||||
|
||||
### 10.2 When Modifying Code
|
||||
|
||||
1. **Always read the file first** - Never assume structure
|
||||
2. **Match existing style** - Follow patterns in the same file
|
||||
3. **Use explicit sizes** - Never rely on assumed processor state
|
||||
4. **Add assert statements** - Prevent silent overflow errors
|
||||
|
||||
### 10.3 After Writing Code
|
||||
|
||||
1. **Run build** - Use `mcp__book-of-mudora__run_build()`
|
||||
2. **Run lint** - Use `mcp__book-of-mudora__lint_asm()`
|
||||
3. **Verify in emulator** - Test before marking complete
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Common Macro Reference
|
||||
|
||||
### Animation and Drawing
|
||||
- `%PlayAnimation(start, end, speed)` - Animate sprite frames
|
||||
- `%DrawSprite(...)` - Draw sprite OAM
|
||||
- `%SetFrame(n)` - Set current animation frame
|
||||
|
||||
### Sprite Control
|
||||
- `%GotoAction(n)` - Change sprite state
|
||||
- `%SetTimer*(n)` - Set various timers
|
||||
- `%SetSpriteSpeed*(n)` - Set movement speed
|
||||
- `%SetHarmless()` / `%SetImpervious()` - Damage flags
|
||||
|
||||
### Player
|
||||
- `%PreventPlayerMovement()` / `%AllowPlayerMovement()`
|
||||
- `%GetPlayerRupees()` - Return rupee count
|
||||
- `%ShowUnconditionalMessage(id)` - Display dialogue
|
||||
- `%ShowSolicitedMessage(id)` - Display on interaction
|
||||
|
||||
### Audio
|
||||
- `%PlaySFX1(id)` / `%PlaySFX2(id)` - Sound effects
|
||||
- `%PlayMusic(id)` - Change music
|
||||
|
||||
### Debugging
|
||||
- `%print_debug(msg)` - Build-time debug output
|
||||
- `%log_section(name, flag)` - Conditional section logging
|
||||
472
Docs/Core/SystemArchitecture.md
Normal file
472
Docs/Core/SystemArchitecture.md
Normal file
@@ -0,0 +1,472 @@
|
||||
# Oracle of Secrets: System Architecture
|
||||
|
||||
**Purpose**: Document how major systems interact to help AI agents understand the codebase structure.
|
||||
|
||||
---
|
||||
|
||||
## 1. High-Level Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Oracle_main.asm │
|
||||
│ (Master include file - controls ROM layout and build order) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────┼─────────────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ Core/ │ │ Sprites/ │ │ Overworld/ │
|
||||
│ - link.asm │ │ - all_sprites│ │ - ZSCustomOW │
|
||||
│ - sram.asm │ │ - Bosses/ │ │ - time_system│
|
||||
│ - symbols.asm│ │ - NPCs/ │ │ - overlays │
|
||||
│ - patches.asm│ │ - Enemies/ │ │ - lost_woods │
|
||||
│ - message.asm│ │ - Objects/ │ └───────────────┘
|
||||
└───────────────┘ └───────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ Items/ │ │ Menu/ │
|
||||
│ - all_items │ │ - menu.asm │
|
||||
│ - ocarina │ │ - menu_select│
|
||||
│ - magic_bag │ │ - menu_journal│
|
||||
└───────────────┘ └───────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Namespace Organization
|
||||
|
||||
### 2.1 Oracle Namespace
|
||||
|
||||
All custom Oracle of Secrets code lives inside the `Oracle` namespace:
|
||||
|
||||
```asm
|
||||
namespace Oracle
|
||||
{
|
||||
; Core systems
|
||||
incsrc "Core/link.asm"
|
||||
incsrc "Core/sram.asm"
|
||||
incsrc "Core/symbols.asm"
|
||||
|
||||
; Content
|
||||
incsrc "Music/all_music.asm"
|
||||
incsrc "Sprites/all_sprites.asm"
|
||||
incsrc "Items/all_items.asm"
|
||||
|
||||
; Patches go last
|
||||
incsrc "Core/patches.asm"
|
||||
}
|
||||
namespace off
|
||||
|
||||
; ZScream code is OUTSIDE the namespace
|
||||
incsrc "Overworld/ZSCustomOverworld.asm"
|
||||
```
|
||||
|
||||
### 2.2 Why This Matters
|
||||
|
||||
- Labels inside `namespace Oracle` become `Oracle.LabelName`
|
||||
- ZScream uses its own conventions and must be outside
|
||||
- Patches at end to ensure all labels are defined
|
||||
|
||||
---
|
||||
|
||||
## 3. Memory Map Overview
|
||||
|
||||
### 3.1 Bank Organization
|
||||
|
||||
| Bank Range | Purpose | Notes |
|
||||
|------------|---------|-------|
|
||||
| $00-$1F | Vanilla ALTTP + small patches | Limited free space |
|
||||
| $20-$29 | ZScream Overworld Data | ~1.5MB reserved |
|
||||
| $30 | Sprite prep/initialization | Oracle sprites start here |
|
||||
| $31 | Main sprite logic | Enemy/NPC behavior |
|
||||
| $32 | Boss logic | Complex sprite code |
|
||||
| $33-$3F | Free space | Available for expansion |
|
||||
|
||||
### 3.2 RAM Regions
|
||||
|
||||
| Region | Purpose |
|
||||
|--------|---------|
|
||||
| $7E0000-$7E1FFF | Scratch RAM (volatile) |
|
||||
| $7E2000-$7EFFFF | Game state RAM |
|
||||
| $7EE000-$7EE0FF | TimeState struct |
|
||||
| $7EF000-$7EFFFF | SRAM (saved data) |
|
||||
| $7EF3C5-$7EF3D6 | Oracle progression flags |
|
||||
| $7EF410 | Dreams bitfield |
|
||||
|
||||
### 3.3 Key SRAM Variables
|
||||
|
||||
```asm
|
||||
; GameState ($7EF3C5) - Overall progression
|
||||
; 0x00 = Very start
|
||||
; 0x01 = Uncle reached
|
||||
; 0x02 = Zelda rescued / Farore intro
|
||||
; 0x03 = Agahnim defeated
|
||||
|
||||
; OOSPROG ($7EF3D6) - Oracle progression bitfield
|
||||
; .fmp h.i.
|
||||
; i = Intro complete, Maku Tree met
|
||||
; h = Hall of Secrets visited
|
||||
; p = Pendant quest progress
|
||||
; m = Master Sword acquired
|
||||
; f = Fortress of Secrets
|
||||
|
||||
; OOSPROG2 ($7EF3C6) - Secondary progression
|
||||
; .fbh .zsu
|
||||
; u = Uncle visited
|
||||
; s = Priest visited in sanctuary
|
||||
; z = Zelda brought to sanctuary
|
||||
; h = Uncle left house
|
||||
; b = Book of Mudora obtained
|
||||
; f = Fortune teller flag
|
||||
|
||||
; Dreams ($7EF410) - Dream sequence tracking
|
||||
; .dts fwpb
|
||||
; (Individual dream completion flags)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. System Interactions
|
||||
|
||||
### 4.1 ZScream Custom Overworld (ZSOW) Integration
|
||||
|
||||
ZSOW manages:
|
||||
- Overworld map transitions
|
||||
- Palette events
|
||||
- Overlay data
|
||||
- Custom collision
|
||||
|
||||
**Hook Points**:
|
||||
```
|
||||
OverworldHandleTransitions ($028000 area)
|
||||
└── Oracle_CheckIfNight (time-based sprite loading)
|
||||
└── LostWoods_PuzzleHandler (navigation puzzle)
|
||||
└── SongOfStorms overlay effects
|
||||
```
|
||||
|
||||
**Known Conflicts**:
|
||||
- Lost Woods puzzle directly modifies transition logic
|
||||
- Day/Night sprites must check `Oracle_CheckIfNight`
|
||||
- Song of Storms overlays need coordination with ZSOW
|
||||
|
||||
### 4.2 Time System
|
||||
|
||||
**File**: `Overworld/time_system.asm`
|
||||
|
||||
**Structure**:
|
||||
```asm
|
||||
struct TimeState $7EE000
|
||||
{
|
||||
.Hours, .Minutes, .Speed
|
||||
.BlueVal, .GreenVal, .RedVal
|
||||
.TempColor, .SubColor
|
||||
}
|
||||
```
|
||||
|
||||
**Flow**:
|
||||
```
|
||||
RunClock (called each frame)
|
||||
├── TimeSystem_CheckCanRun
|
||||
│ └── Check game mode, indoors status
|
||||
├── TimeSystem_IncrementTime
|
||||
│ └── Update Hours/Minutes based on Speed
|
||||
└── TimeSystem_UpdatePalettes
|
||||
└── Apply color tinting based on time
|
||||
```
|
||||
|
||||
**Integration Points**:
|
||||
- `Oracle_CheckIfNight` - Called by ZSOW for sprite loading
|
||||
- Palette system - Affects overworld colors
|
||||
- NPC behavior - Some NPCs react to time
|
||||
|
||||
### 4.3 Sprite System
|
||||
|
||||
**Entry Points** (standard pattern):
|
||||
|
||||
```
|
||||
Sprite_*_Long (JSL entry from sprite table)
|
||||
├── PHB : PHK : PLB (set data bank)
|
||||
├── Sprite_*_Draw (JSR - render)
|
||||
├── Sprite_CheckActive (JSL - is active?)
|
||||
│ └── Sprite_*_Main (JSR - if active)
|
||||
├── PLB
|
||||
└── RTL
|
||||
```
|
||||
|
||||
**State Machine**:
|
||||
```
|
||||
SprAction (per-sprite state variable)
|
||||
└── JumpTableLocal dispatches to state handlers
|
||||
├── State_Idle
|
||||
├── State_Chase
|
||||
├── State_Attack
|
||||
└── State_Retreat
|
||||
```
|
||||
|
||||
**Key Variables** (indexed by X):
|
||||
| Address | Name | Purpose |
|
||||
|---------|------|---------|
|
||||
| $0D00 | SprY | Y position (low byte) |
|
||||
| $0D10 | SprX | X position (low byte) |
|
||||
| $0D80 | SprAction | Current state |
|
||||
| $0DA0 | SprHealth | Hit points remaining |
|
||||
| $0E40 | SprNbrOAM | OAM slot count |
|
||||
|
||||
### 4.4 Menu System
|
||||
|
||||
**File**: `Menu/menu.asm`
|
||||
|
||||
**State Machine**:
|
||||
```
|
||||
MenuMode ($0200) - Current menu state
|
||||
├── $00 = Not in menu
|
||||
├── $01 = Opening animation
|
||||
├── $02 = Item select
|
||||
├── $0C = Magic Bag submenu
|
||||
├── $0D = Ring Box submenu
|
||||
└── $0E = Song select submenu
|
||||
```
|
||||
|
||||
**Flow**:
|
||||
```
|
||||
Menu_Entry (from pause input)
|
||||
├── Menu_InitGraphics
|
||||
├── Menu_Upload* (VRAM transfers)
|
||||
└── Menu_MainLoop
|
||||
├── Handle input
|
||||
├── Update selection
|
||||
└── Menu_Draw*
|
||||
```
|
||||
|
||||
### 4.5 Dialogue System
|
||||
|
||||
**Files**: `Core/message.asm`, `Core/messages.org`
|
||||
|
||||
**Message Format** (in messages.org):
|
||||
```
|
||||
** 20 - Maku Tree Part1
|
||||
[W:02][S:03]Ah, [L]!
|
||||
[2]Thank the Goddesses you are
|
||||
[3]alright. I feared the worst.
|
||||
[V]A dark shadow has befallen us.[K]
|
||||
```
|
||||
|
||||
**Control Codes**:
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| `[2]`, `[3]` | Line 2, Line 3 |
|
||||
| `[K]` | Wait for button press |
|
||||
| `[V]` | Continue on same line |
|
||||
| `[W:XX]` | Wait time |
|
||||
| `[S:XX]` | Text speed |
|
||||
| `[SFX:XX]` | Play sound effect |
|
||||
| `[CH2I]` | 2-choice prompt |
|
||||
| `[CH3]` | 3-choice prompt |
|
||||
| `[L]` | Player name |
|
||||
|
||||
**Display Macros**:
|
||||
```asm
|
||||
%ShowUnconditionalMessage($20) ; Force display
|
||||
%ShowSolicitedMessage($20) ; On interaction only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Hook Architecture
|
||||
|
||||
### 5.1 Hook Types
|
||||
|
||||
**Type 1: Inline Patch** (replace vanilla code)
|
||||
```asm
|
||||
pushpc
|
||||
org $02XXXX ; Vanilla address
|
||||
JSL MyHook ; Replace original instruction
|
||||
NOP : NOP ; Pad to match original size
|
||||
pullpc
|
||||
```
|
||||
|
||||
**Type 2: Table Override** (jump table entry)
|
||||
```asm
|
||||
pushpc
|
||||
org $07F000+($ID*2) ; Jump table for sprite $ID
|
||||
dw Sprite_Custom_Prep
|
||||
pullpc
|
||||
```
|
||||
|
||||
**Type 3: Extended Logic** (call original + extend)
|
||||
```asm
|
||||
MyHook:
|
||||
{
|
||||
JSL OriginalRoutine ; Preserve original behavior
|
||||
; Add custom logic
|
||||
LDA.w CustomFlag
|
||||
BEQ .skip
|
||||
JSL CustomHandler
|
||||
.skip
|
||||
RTL
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 Hook Documentation Pattern
|
||||
|
||||
Every hook should document:
|
||||
|
||||
```asm
|
||||
; =========================================================
|
||||
; Hook: $XXBANK:ADDR
|
||||
; Purpose: [What this hook adds/changes]
|
||||
; Vanilla Code: [What original code did]
|
||||
; Clobbered: [Registers modified]
|
||||
; Dependencies: [Other systems affected]
|
||||
; =========================================================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Build System
|
||||
|
||||
### 6.1 Build Order (Critical)
|
||||
|
||||
```
|
||||
1. Core/symbols.asm - Memory declarations
|
||||
2. Core/sram.asm - SRAM layout
|
||||
3. Core/link.asm - Player modifications
|
||||
4. Music/all_music.asm - SPC700 data
|
||||
5. Sprites/all_sprites.asm - All sprite code
|
||||
6. Items/all_items.asm - Item handlers
|
||||
7. Menu/menu.asm - Menu system
|
||||
8. Dungeons/ - Dungeon-specific code
|
||||
9. Core/patches.asm - Vanilla patches (LAST)
|
||||
10. Overworld/ZSCustomOverworld.asm - ZSOW (OUTSIDE namespace)
|
||||
```
|
||||
|
||||
### 6.2 Build Commands
|
||||
|
||||
```bash
|
||||
# Fast build
|
||||
./run.sh
|
||||
|
||||
# MCP tools
|
||||
mcp__book-of-mudora__run_build() # Build ROM
|
||||
mcp__book-of-mudora__lint_asm() # Check style
|
||||
mcp__book-of-mudora__analyze_patches() # Review patches
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Debugging Workflow
|
||||
|
||||
### 7.1 Common Debug Points
|
||||
|
||||
| Symptom | Check First |
|
||||
|---------|-------------|
|
||||
| Crash on room enter | Sprite prep routine, invalid JSL target |
|
||||
| Wrong graphics | SprGfx assignment, DMA timing |
|
||||
| Frozen game | Infinite loop in Main, missing RTS/RTL |
|
||||
| Black screen | Palette loading, HDMA setup |
|
||||
| Corrupt saves | SRAM address conflict, missing bank setup |
|
||||
|
||||
### 7.2 Debug Tools
|
||||
|
||||
**Yaze MCP** (in-development):
|
||||
```python
|
||||
mcp__yaze_mcp__read_memory("7E0010", 2) # Read RAM
|
||||
mcp__yaze_mcp__add_breakpoint("02XXXX") # Set breakpoint
|
||||
mcp__yaze_mcp__get_game_state() # Dump current state
|
||||
```
|
||||
|
||||
**Hyrule Historian**:
|
||||
```python
|
||||
mcp__hyrule-historian__lookup_address("02XXXX")
|
||||
mcp__hyrule-historian__search_oracle_code("Sprite_Booki")
|
||||
mcp__hyrule-historian__get_ram_info("SprAction")
|
||||
```
|
||||
|
||||
### 7.3 Logging
|
||||
|
||||
```asm
|
||||
; Build-time logging
|
||||
%log_section("Sprites", !LOG_SPRITES)
|
||||
|
||||
; Enable in build:
|
||||
!LOG_SPRITES = 1 ; Set in config
|
||||
|
||||
; Output appears in build log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Common Integration Patterns
|
||||
|
||||
### 8.1 Adding a New Sprite
|
||||
|
||||
1. Create file: `Sprites/Enemies/my_sprite.asm`
|
||||
2. Define properties using standard order
|
||||
3. Implement `_Long`, `_Prep`, `_Main`, `_Draw`
|
||||
4. Add include to `Sprites/all_sprites.asm`
|
||||
5. Add to sprite table with `org` directive
|
||||
6. Build and test
|
||||
|
||||
### 8.2 Adding a Quest Flag
|
||||
|
||||
1. Find free bit in OOSPROG/OOSPROG2
|
||||
2. Document in `Core/sram.asm`
|
||||
3. Update this file's SRAM section
|
||||
4. Use in code:
|
||||
```asm
|
||||
LDA.l OOSPROG : ORA.b #$XX : STA.l OOSPROG
|
||||
```
|
||||
|
||||
### 8.3 Adding a New Hook
|
||||
|
||||
1. Find vanilla address with Hyrule Historian
|
||||
2. Document what original code does
|
||||
3. Create hook with `pushpc`/`pullpc`
|
||||
4. Add `assert` to verify space
|
||||
5. Test vanilla behavior still works
|
||||
|
||||
---
|
||||
|
||||
## 9. System Dependency Graph
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ TimeSystem │
|
||||
└──────┬──────┘
|
||||
│ Oracle_CheckIfNight
|
||||
▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Lost Woods │────▶│ ZSOW │◀────│ Overlays │
|
||||
│ Puzzle │ │ Transitions │ │ System │
|
||||
└─────────────┘ └──────┬──────┘ └─────────────┘
|
||||
│
|
||||
┌────────────┴────────────┐
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ Sprites │ │ Events │
|
||||
│ (Loading) │ │ (Triggers) │
|
||||
└──────┬──────┘ └──────┬──────┘
|
||||
│ │
|
||||
└───────────┬─────────────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Player │
|
||||
│ (Link) │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. AI Agent Checklist
|
||||
|
||||
When working on Oracle of Secrets:
|
||||
|
||||
1. [ ] Check `oracle.org` for related tasks
|
||||
2. [ ] Read existing code in affected files
|
||||
3. [ ] Verify memory map for conflicts
|
||||
4. [ ] Use Hyrule Historian for vanilla lookups
|
||||
5. [ ] Follow StyleGuide.md conventions
|
||||
6. [ ] Run build after changes
|
||||
7. [ ] Document any new hooks
|
||||
8. [ ] Update this file if adding new systems
|
||||
Reference in New Issue
Block a user