Disassembly + Zelda Docs

February 27th, 2014 Update:

http://math.arc-nova.org/Releases/Banks_02_27_2014.zip
MIRROR 1: http://www.bwass.org/bucket/Banks_02_27_2014.zip
MIRROR 2: http://assassin17.brinkster.net/mathonnapkins/Banks_02_27_2014.zip

It's that time again! Accomplishments this time around are that most of the bosses are pretty well filled out (branches labeled, no raw address jsrs / jsls), and some even have symbolic variable names now. The bosses still left to finish for good are:
- Armos Knights
- Agahnim
- Helmasaur King (Much code, wow)
- Arrghus
- Trinexx
- Ganon

Next release will likely see either these bosses completed or more of the player engine documented, because I'm running out of places to document.

Statistics:

75.7% of JSRs are named.
93.1% of JSLs are named.
7332 usages of BRANCH_* type label remain.
Address Range Gaps: 181.

---

January 22, 2014 Update:

http://assassin17.brinkster.net/mathonnapkins/Banks_01_22_2014.zip

Hello folks, been a long time since I made a new release. I'm trying to make sure enough new material has been documented for it to be worthwhile to release though. I continue to divide the disassembly into smaller pieces, but still need to finish the assembler upgrades that will let me compile the rom when I'm finished naming everything. This release adds another analysis script that can be run in Python to assess how many gaps remain in the disassembly. Before I began working on this release there were about 560 gaps (address ranges not accounted for). Now there are about 320, which is pretty good progress. This helps identify missing data tables, data files, and sometimes has helped locate unused code or code that was somehow missed earlier on.

Statistics:
72.8% of JSRs are named.
91.0% of JSLs are named.
8,501 usages of BRANCH_* type label remain. Thats a lot of sublabels left to go, but very down from where I started.
320 address range gaps.

Epilogue: The next release will probably see a lot more naming of some of the bosses' labels and documentation of how they function.

---

August 15, 2013 Update:

http://math.arc-nova.org/Releases/Banks_08_15_2013.zip

Ancillary objects are basically finished - fully labeled, data arrays are filled in and labeled.

Statistics:
69.6% of JSRs are labeled.
87.4% of JSLs are labeled.
9,517 unnamed usages of BRANCH_* type labels. This means that over 1,000 previously unnamed nodes are now understood (some are still mysterious but are marked as '.unknown' or the like).

Other fun facts: there are no known unlabeled JSLs, JSRs, or branch locations in Bank 0x08 now.

---

August 1, 2013 Update:

http://math.arc-nova.org/Releases/Banks_08_01_2013.zip

Much more fleshing out of Ancillary objects. The Bombs and the Somarian block are the main hold outs in Bank08.asm (they're also the most spaghetti-coded and among the least efficient objects in the game)

Statistics:
66.4% of JSRs are labeled.
84.4% of JSLs are labeled.
10,881 unnamed usages of BRANCH_* type labels. This leaves approximately 60% unlabeled so far.

Note: Subdirectory has been changed to "Releases" as to not mislead.

---

July 19, 2013 (First in Thread) Update:

I'm sure some of you have seen my disassembly, and I'd like to present a more current version of it that might prove more useful. If it's still as incomprehensible to you as before, please make sure to blame Nintendo.

http://math.arc-nova.org/Releases/Banks_07_19_2013.zip

Statistics:
61.5% of JSRs are labeled.
79.7% of JSLs are labeled.
11,966 unnamed usages of BRANCH_* type labels.

~MoN

This surely is the biggest documentation on Zelda3 ever.

I remember that the Gibdo really pissed me off last time I looked at it. I think it's implementation might actually be buggy, but I don't have proof of this yet. It is different in that its direction index is not like any other sprite I've seen so far. It has 8 directions, but half of those consist of it not moving at all. Anyways, here's a rough draft that should give you enough info to modify those speeds. I always thought of them as mummies though. They look like Stalfos with bandages on, just like they are shown to be in Zelda 1.

Code:



; ==============================================================================

    ; *$F39A9-$F39BF JUMP LOCATION
    Sprite_Gibdo:
    {
        JSR Gibdo_Draw
        JSR Sprite3_CheckIfActive
        JSR Sprite3_CheckIfRecoiling
        JSR Sprite3_CheckDamage
       
        LDA $0D80, X
       
        JSL UseImplicitRegIndexedLocalJumpTable
       
        dw Gibdo_ApproachTargetDirection
        dw Gibdo_CanMove
    }

; ==============================================================================

    ; $F39C0-$F39CB DATA
    pool Gibdo_ApproachTargetDirection:
    {
   
    .target_direction length 8
        db $02, $06, $04, $00
   
    .animation_states
        db $04, $08, $0B, $0A, $00, $06, $03, $07
    }

; ==============================================================================

    ; *$F39CC-$F39FF JUMP LOCATION
    Gibdo_ApproachTargetDirection:
    {
        LDY $0DE0, X
       
        LDA .animation_states, Y : STA $0DC0, X
       
        LDA $1A : AND.b #$07 : BNE .delay
       
        LDY $0D90, X
       
        LDA $0DE0, X : CMP .target_direction, Y
       
        BEQ .reset_timer
        BPL .rotate_towards_target_direction
       
        INC $0DE0, X
       
        BRA .return
   
    .rotate_towards_target_direction
   
        DEC $0DE0, X
   
    .delay
    .return
   
        RTS
   
    .reset_timer
   
        JSL GetRandomInt : AND.b #$1F : ADC.b #$30 : STA $0DF0, X
       
        INC $0D80, X
       
        RTS
    }

; ==============================================================================

    ; $F3A00-$F3A11 DATA
    pool Gibdo_CanMove:
    {
   
    .y_speeds length 8
        db -16,  0
   
    .x_speeds
        db  0,  0,  16,  0,  0,  0, -16,  0
   
    .animation_states
        db 9, 2, 0, 4, 11, 3, 1, 5
    }

; ==============================================================================

    ; *$F3A12-$F3A5F JUMP LOCATION
    Gibdo_CanMove:
    {
        LDY $0DE0, X
       
        ; Note that half of these states will have a speed of zero, or that the
        ; sprite is standing still. Gibdos are kind of weird in that regard.
        LDA .x_speeds, Y : STA $0D50, X
       
        LDA .y_speeds, Y : STA $0D40, X
       
        JSR Sprite3_Move
        JSR Sprite3_CheckTileCollision
       
        LDA $0DF0, X : BEQ .timer_expired_so_face_player
       
        LDA $0E70, X : BEQ .no_tile_collision
   
    .timer_expired_so_face_player
   
        JSR Sprite3_DirectionToFacePlayer
       
        TYA : CMP $0D90, X : BEQ .already_facing_player
       
        ; Need to go back to the seeking state to rotate to the direction
        ; that is towards the player.
        STA $0D90, X
       
        STZ $0D80, X
       
        RTS
   
    .no_tile_collision
    .already_facing_player
   
        DEC $0DA0, X : BPL .dont_tick_animation_timer
       
        LDA.b #$0E : STA $0DA0, X
       
        INC $0E80, X
   
    .dont_tick_animation_timer
   
        LDA $0E80, X : ASL #2 : AND.b #$04 : ORA $0D90, X : TAY
       
        LDA .animation_states, Y : STA $0DC0, X
       
        RTS
    }

; ==============================================================================

    ; $F3A60-$F3B1F DATA
    pool Gibdo_Draw:
    {
   
    .oam_groups
        dw 0, -9 : db $80, $00, $00, $02
        dw 0,  0 : db $8A, $00, $00, $02
       
        dw 0, -8 : db $80, $00, $00, $02
        dw 0,  1 : db $8A, $40, $00, $02
       
        dw 0, -9 : db $82, $00, $00, $02
        dw 0,  0 : db $8C, $00, $00, $02
       
        dw 0, -8 : db $82, $00, $00, $02
        dw 0,  0 : db $8E, $00, $00, $02
       
        dw 0, -9 : db $84, $00, $00, $02
        dw 0,  0 : db $A0, $00, $00, $02
       
        dw 0, -8 : db $84, $00, $00, $02
        dw 0,  1 : db $A0, $40, $00, $02
       
        dw 0, -9 : db $86, $00, $00, $02
        dw 0,  0 : db $A2, $00, $00, $02
       
        dw 0, -9 : db $88, $00, $00, $02
        dw 0,  0 : db $A4, $00, $00, $02
       
        dw 0, -9 : db $88, $40, $00, $02
        dw 0,  0 : db $A4, $40, $00, $02
       
        dw 0, -9 : db $82, $40, $00, $02
        dw 0,  0 : db $8C, $40, $00, $02
       
        dw 0, -9 : db $86, $40, $00, $02
        dw 0,  0 : db $A2, $40, $00, $02
       
        dw 0, -8 : db $82, $40, $00, $02
        dw 0,  1 : db $8E, $40, $00, $02
    }
; ==============================================================================

    ; *$F3B20-$F3B41 LOCAL
    Gibdo_Draw:
    {
        LDA.b #$00  : XBA
        LDA $0DC0, X : REP #$20 : ASL #4 : ADC.w .oam_groups : STA $08
       
        SEP #$20
       
        LDA.b #$02 : JSR Sprite3_DrawMultiple
       
        LDA $0F00, X : BNE .no_shadow
       
        JSL Sprite_DrawShadowLong
   
    .no_shadow
   
        RTS
    }

; ==============================================================================


SePH wrote:Do you think it's actually possible for the sprite to follow you diagonally, similar to that bomb hack you made that trows the bombs in eight directions?

Yes, it is certainly possible to hack them to do that, but you'd probably have to shitcan some of this weird direction selection logic that's going on.

Hrm.... like I said they're a bit of a clusterfuck, logic wise. If you test them out in a vanilla rom, you'll notice that for some transitions when it follows you around in a square pattern that it has to turn itself all the way around in order to face you. And that's what I mean by I think it's buggy, because it's not consistent, and it's not determined by a randomizer or anything (though the timer for how long it will wait before again checking whether to face the player *is* randomized, so don't get that confused). In other words, it seems like someone was not quite fully awake when writing this guy, or maybe they thought the bug was amusing and left it in. I can't see this behavior being on purpose.

A true dynamic Gibdo would basically call Sprite_ProjectSpeedTowardsPlayer and then use those derived speeds for $0D50, X and $0D40, X. If you wanted it to adhere to only 8 directions, though, you'd have to find some way to clip the projection to a set number of angles, which I don't think any sprite does in the normal game. It'd be doable, but it wouldn't be a 5 minute project.

*Bump*
Disassembly has been updated, see first post: http://zeldix.forumotion.com/t143-disassembly-zelda-docs#1100

Thank you for sharing :-)

I think I should clarify that these files aren't exactly "new", they've just been split off of previously larger files. e.g. see module_death.asm and tagalong.asm. Those were inside Bank09.asm in previous releases. Gradually I've been trying to split off files when logical to do so, but some routines are kind of mishmashed together and it becomes a bit harder to justify splitting sections off. Now, there might be data added to these files that was previously missing.

Also, there are a number of (doxygen-like) tags embedded in the comments for anyone interested:

\tcrf - Potential fodder for The Cutting Room Floor, a wiki for hidden / disabled stuff in video games. Course, I would appreciate y'all crediting me if you post anything found in these comments. Some of them are not verified yet, though. The Kholdstare Melting bug is marked as \tcrf for example.

\bug - Something that I think might be a bug or might not quite correct.

\wtf - Not necessarily a bug, but code or data that is strange, hard to understand, or held together with duct tape. Take these with a grain of salt though, I don't always playtest to verify these findings. Sometimes they end up making perfect sense when I sit down and debug it.

\warning - Be careful when modifying this code.

\unused - Code that was compiled in but not actually referenced by anything.

\covered - A sort of tallying analysis where i occasionally try to mark a region of the rom as fully mapped out with near certainty.

\note - Comments that are usually explanatory above and beyond the usual line comments that try to ease understanding of smaller pieces of code.

\return - Some subroutines return a numerical value, these comments try to explain what the routine returns and what the values mean.

\optimize - Code that could potentially be optimized. Fairly new tag with only one usage so far. Might get more mileage by searching for just the word optimize for now.

\task - Procrastination tag that indicates I should come back here later and finish doing something.

Well, it handles all the button input on the normal item equip menu. "Normal" in this case basically is in opposition to the "Bottle" menu that pops up with 4 possible slots when you set the cursor on the Bottle slot. Or did you have a more specific question, like what is BYSTudlr exactly? Preemptively, BYSTudlr is the bit pattern one of the game variables uses to store the button input from a joypad. The capitalized letters are the B button, Y button, Select Button, and Start Button, and the 'udlr' portion are the directions of the d-pad. See the documentation for $F0, $F1, $F4, and $F5 in the ram map.

Great job with your Disassembly Math. This is excellent work!!!

And best wishes on Black Magic!

*Bump*
Disassembly has been updated, see first post: http://zeldix.forumotion.com/t143-disassembly-zelda-docs#1100

*Bump*
Disassembly has been updated, see first post: http://zeldix.forumotion.com/t143-disassembly-zelda-docs#1100

Great, thank you!

Also my deepest thanks. Without your docs, my hacks clearly would not have been advanced that much!

You're very welcome. If you guys have any requests for areas for me to delve into please let me know, as I kind of just randomly pick off what I think is easiest or interesting at the moment when trying to make releases.

Thank for this offer, i am sure i will make use of it   

*Bump*
Disassembly has been updated, see first post: http://zeldix.forumotion.com/t143-disassembly-zelda-docs#1100

I don't think there is such another game in this world that is this timeless. Everytime you post your updated docs i am so amazed! Thank you   

It's interesting that out of all of the games released for the SNES that there is one game that I've spent years learning about and designing for.

Why is Zelda that is able to do this? Why don't we hack Madden Football or Super Punch Out or Addams Family?

I just think special care was giving to this game and its one of my all time favorites.

And just think, Zelda was released for the SNES early on in the SNES's lifespan. Just think if Zelda was released at the end of the SNES? The graphics and everything may have been even better!

so MathOnNapkins' website disappeared, he's nowhere to be seen, and idiot archive.org is letting some domain squatter retroactively disable all archived pages from there.

thankfully, i've used a computer with so much free space i never delete temp files.  so i'm mirroring a couple things:

http://assassin17.brinkster.net/mathonnapkins/Banks_02_27_2014.zip
(i also have the 1/22/14 edition, if anybody wants it.)
http://assassin17.brinkster.net/mathonnapkins/Black_Magic_2015_04_04.7z

assassin17 wrote:so MathOnNapkins' website disappeared, he's nowhere to be seen, and idiot archive.org is letting some domain squatter retroactively disable all archived pages from there.

This is because of robot.txt.

assassin17 wrote:
thankfully, i've used a computer with so much free space i never delete temp files.  so i'm mirroring a couple things:

http://assassin17.brinkster.net/mathonnapkins/Banks_02_27_2014.zip
(i also have the 1/22/14 edition, if anybody wants it.)
http://assassin17.brinkster.net/mathonnapkins/Black_Magic_2015_04_04.7z

I'm interested in that document. Also was Black Magic open source all along? I forget.

assassin17 wrote:so MathOnNapkins' website disappeared...

I was just talking to him over at RHDN. He's pretty easy to reach over there.

here's the slightly older revision (pardon the laziness delay):
http://assassin17.brinkster.net/mathonnapkins/Banks_01_22_2014.zip