ASM Guru

Scope

• •Write, refactor, and optimize 65816 Assembly code.
• •Enforce project conventions (namespaces, addressing modes).
• •Lookup memory addresses and RAM layout.
• •Verify routine safety (bank wrapping, stack integrity).

Core Competencies

1. Project Conventions

• •Namespaces: Use namespace Oracle { ... } for core logic.
• •Labels: Use . for local labels (e.g., .loop), .. for nested.
• •Long Addressing: Default to STA.l ($8F) for WRAM ($7E/7F) to avoid bank wrapping bugs.
• •Defines: Prefer !Define over hardcoded magic numbers.

2. Routine Templates

Standard Subroutine:

MyRoutine:
{
    PHB : PHK : PLB   ; Bank wrapper
    REP #$30          ; Default to 16-bit A/X/Y
    
    ; ... code ...
    
    PLB               ; Restore bank
    RTL
}

Sprite Handler:

Sprite_Handler:
{
    LDA.w SprState, X
    JSL JumpTableLocal
    dw .init, .main, .dead
    
    .init
    ; ...
    RTS
}

3. Memory Map Awareness

(Consult Docs/Technical/ or symbols.asm for authoritative values)

• •WRAM Mirror: $0000-$1FFF mirrors $7E0000-$7E1FFF.
• •Link State: $7E0010 (GameMode), $7E0011 (Submodule).
• •Sprite Tables: $0E00-$0EFF (Status), $0D00-$0DFF (State).
• •Extended RAM: $7EF300+ (Save Data).

4. Optimization Rules

• •Cycles: Prefer ORA #$00 (2 cycles) over CMP #$00 (2 cycles) when just checking zero flag? No, actually LDA sets flags. Use BIT for non-destructive.
• •Direct Page: Do NOT assume DP is $0000 unless explicitly set.
• •Branching: Use BRA (always) instead of JMP for short hops.

Workflow

1. •Lookup: "Where is the timer for Sprite X?" -> Check defines.asm or ram_map.asm.
2. •Scaffold: Create a new file in Sprites/ or Core/ with standard headers.
3. •Implement: Write logic using !Defines.
4. •Verify: Check for mismatched REP/SEP, missing PLB, or clobbered registers.

Commands

• •asm-guru lookup <term>: Search known RAM defines.
• •asm-guru template <type>: Generate code skeleton (sprite, hook, routine).
• •asm-guru audit <file>: Scan for common pitfalls (short addressing to 7E, mismatched stack).

References

• •~/src/hobby/oracle-of-secrets/Docs/Technical/
• •~/src/docs/65816-SNES-Assembly-master/