Goldstar item formatting and comments

Items/goldstar.asm

@@ -1,8 +1,10 @@
+; =========================================================
 ; Goldstar ASM disassembly/restoration
 ; Originally from the all in patch by Conn
 ; Restored by scawful with help from Zarby
 ;
 ; $22XXXX - Denotes the source address from all in patch
+; =========================================================
 
 org $07D576
   Hookshot_CheckTileCollision:
@@ -17,8 +19,7 @@ TransferGFXinRAM:
     LDX #$80
   --
     LDA.l .morningstargfx, X : STA.l $7EA180, X
-  DEX : DEX
-  BPL --
+    DEX : DEX : BPL --
 
     PLP
     PLX
@@ -35,7 +36,8 @@ org $0085C4
 pullpc
 
 ; =========================================================
-; Start Zarby
+; Zarby Code
+; Handles the layout of OAM tile patterns for the hookshot
 
 pushpc
 org $0DABA2 ; LinkOAM_SetWeaponVRAMOffsets
@@ -51,12 +53,12 @@ org $008542
   dw $A1C0, $A1C0, $A1E0, $A1E0
 pullpc
 
-
 HookMaskCheck:
 {
     LDA GoldstarOrHookshot : AND.w #$00FF :  CMP.w #$0002 : BNE .not_mask
       LDA $0202 : AND.w #$00FF : CMP.w #$0003 : BNE .not_mask
-    LDA.w $0109 : AND #$FF00 : ORA.w #$004A ; morning star graphics oam tile pattern id 
+         ; morning star graphics oam tile pattern id 
+        LDA.w $0109 : AND #$FF00 : ORA.w #$004A
         RTL
   .not_mask
     ; return hookshot graphics oam tile pattern id
@@ -65,11 +67,6 @@ HookMaskCheck:
     RTL
 }
 
-; End Zarby 
-; =========================================================
-
-
-
 ; =========================================================
 ; $22D4A0 - Hooked into LinkItem_Hookshot @ _07AB5A
 ; Call this routine to start the gfx transfer of the handle
@@ -120,11 +117,14 @@ BallChain_ExtraCollisionLogic:
     TXA
   ++ ; $22D4F3
     CMP #$FF : BEQ +++
-    JML $08BF10 ; AncillaDraw_Hookshot - JSR Ancilla_SetOAM_XY, skips hookshot char
+      ; AncillaDraw_Hookshot - JSR Ancilla_SetOAM_XY, skips hookshot char
+      JML $08BF10 
+
   +++ ; $22D4FB
     JML $08BF32 ; AncillaDraw_Hookshot_skip
 }
 
+; =========================================================
 ;; 22D520
 LinkItem_BallChain_GfxTransfer:
 {
@@ -174,11 +174,10 @@ LinkItem_BallChain_GfxTransfer:
 }
 
 ; 22D5C0 ; Unreached
-  LDA $8580,Y
-  CMP #$02
-  BEQ $22D5CA
-  JMP $DA80
-
+; LDA $8580,Y
+; CMP #$02
+; BEQ $22D5CA
+; JMP $DA80
 
 ; Graphics data for transferring the handle oam slot
 GoldstarHandleGfx:
@@ -240,9 +239,9 @@ pullpc
 ; Sets Link state to 0x00 and resets the hookshot timer
 BallChain_ResetTimer:
 {
-  LDA GoldstarOrHookshot : CMP #$02 : BNE +
+    LDA GoldstarOrHookshot : CMP #$02 : BNE .dont_clear_timer
       STZ $7A ; Clear the timer
-+
+  .dont_clear_timer
     STZ $5D ; Return to LinkState_Default
     RTL
 }
@@ -366,29 +365,36 @@ HookshotChain_AncillaDraw:
     ; Compare rotation progress
     CLC : CMP #$FB : BNE +++
       LDA #$06 : STA $2143 
+
   +++ ; 22D930
     BCC ++++
       JMP StartChainRotation ; $D960
+
   ++++ ; 22D935
     ; Compare rotation progress
     CLC : CMP #$AB : BNE +++++ 
       LDA #$06 : STA $2143
+
   +++++ ;22D93F
     ; Compare rotation progress
     CLC : CMP #$5B : BNE ++++++ 
       LDA #$06 : STA $2143
+
   ++++++ ;22D949
     CLC : CMP #$E6 : BCC +++++++
       JMP Routine_22D9A0 ; $D9A0
+
   +++++++ ; 22D951
     CLC : CMP #$05 : BCC ++++++++
     LDA $F8 : CMP.b #$40 : BEQ +
-
       JMP Routine_22D9A0 ; $D9A0
+
   ++++++++ ; 22D959
     JMP Routine_22DBD0 ; $DBD0
 }
 
+; =========================================================
+
 !RotationState = $7F5803
 
 ; 22D960
@@ -405,6 +411,8 @@ StartChainRotation:
     JML $08BFD0 ; AncillaDraw_HookshotChain before Hookshot_CheckProximityToLink
 }
 
+; =========================================================
+
 struct Ancilla_GetRadialProjection $0FFBC2
   .multiplier_x : skip 64
   .multiplier_y : skip 64
@@ -446,10 +454,10 @@ Routine_22D9A0:
     JSL $08DA17 ; Sparkle_PrepOAMFromRadial
     PLY : PLX
     CPY #$04 : BNE ++ ; $22DA14
-
       JSR Routine_22DA70 ; $DA70
       NOP #7
       JSR BallChain_SpinAncilla ; $22DB90
+
   ++ ;22DA14
     NOP #3
     LDA #$F0 : CPY #$1C : BNE +++ ; $22DA1F
@@ -460,7 +468,9 @@ Routine_22D9A0:
     JML $08BFD0 ; AncillaDraw_HookshotChain before Hookshot_CheckProximityToLink
 }
 
-;; 22DA30
+; =========================================================
+; 22DA30
+
 Goldstar_GetPlayerPosY:
 {
     ADC $20 : CLC : ADC #$000C
@@ -474,7 +484,9 @@ Goldstar_GetPlayerPosY:
     RTS
 }
 
+; =========================================================
 ; 22DA50
+
 Goldstar_GetPlayerPosX:
 {
     LDA $22 : CLC : ADC #$0008
@@ -488,7 +500,9 @@ Goldstar_GetPlayerPosX:
     RTS
 }
 
+; =========================================================
 ; 22DA70
+
 Routine_22DA70:
 {
     LDY #$00 : LDA $02 ; set sign of projected distance X
@@ -501,7 +515,9 @@ Routine_22DA70:
     RTS
 }
 
+; =========================================================
 ; 22DA80 Possibly unused
+
 Routine_22DA80:
 {
     LDA $7EF34A : CMP #$02
@@ -516,7 +532,9 @@ Routine_22DA80:
     RTL
 }
 
+; =========================================================
 ; 22DAA0
+
 Routine_22DAA0:
 {
   CPY #$04 : BNE .alpha
@@ -546,7 +564,9 @@ Routine_22DAA0:
   RTS
 }
 
+; =========================================================
 ; 22DAD0
+
 Routine_22DAD0:
 {
     CPX #$00 : BNE + ; $22DAD7
@@ -565,6 +585,8 @@ Routine_22DAD0:
     RTS
 }
 
+; =========================================================
+
 pushpc
 org $08BF94
   JML BallChain_TryAncillaDraw
@@ -577,14 +599,15 @@ pullpc
 BallChain_TryAncillaDraw:
 {
   ; Ball Chain timer should be $FF here on first run
-  LDA $7A : AND #$00FF
-  CMP #$0000 : BEQ + 
+    LDA $7A : AND #$00FF :CMP #$0000 : BEQ + 
       CMP #$0001 : BEQ +
         SEP #$20
         JML HookshotChain_AncillaDraw ; $22D900 
+
   + ; $22DB15
     LDA Hookshot_box_size_y,X : BNE ++ 
       JML $08BF99 ; AncillaDraw_HookshotChain
+
   ++ ; $22DB1F
     JML $08BFA1 ; Resume AncillaDraw_HookshotChain
 }
@@ -609,7 +632,9 @@ BallChain_CheckProximityToLink:
     JML $08F820 ; Hookshot_CheckProximityToLink too_far
 }
 
+; =========================================================
 ; 22DB50
+
 Routine_22DB50:
 {
     ; Ball Chain Timer
@@ -626,13 +651,13 @@ Routine_22DB50:
     RTS
 }
 
-
+; =========================================================
 ; $22DB90
+
 BallChain_SpinAncilla:
 {
     REP #$20
-  LDA $00 : CLC : ADC $E8 : CPX #$02
-  BNE .alpha
+    LDA $00 : CLC : ADC $E8 : CPX #$02 : BNE .alpha
       CLC : ADC #$0010
   .alpha
     STA $04
@@ -645,6 +670,8 @@ BallChain_SpinAncilla:
     RTS
 }
 
+; =========================================================
+
 struct AncillaAdd_HookshotData $099AF8
   .speed_y: skip 4
   .speed_x: skip 4
@@ -711,7 +738,9 @@ HookshotOrBallChain_Extending_ignore_collision:
   JML $08BEDC ; AncillaDraw_Hookshot
 }
 
+; =========================================================
 ; 22DC70
+
 ClearAncillaVariables:
 {
     REP #$30
@@ -745,8 +774,10 @@ BallChain_SFX_Control:
     RTL
 }
 
+; =========================================================
 ; 22DCA0
 ; SFX Pan flags?
+
 Routine_22DCA0:
 {
     LDA $7A : CMP #$00 : BNE + ;$A2DCAB
@@ -757,7 +788,10 @@ Routine_22DCA0:
     RTL
 }
 
-;; 22DD90
+; =========================================================
+; 22DD90
+; TODO: Investigate the purpose of the $7A timer here
+
 CheckAndClearAncillaId:
 {
     SEP #$30
@@ -785,8 +819,12 @@ CheckAndClearAncillaId:
     RTS
 }
 
+; =========================================================
 ; 22E5A0
 ; Checks for the Somaria block before moving on
+; TODO: Replace the JMP $E5DB with the proper code 
+; to handle the somaria block case.
+
 Routine_22E5A0:
 {
     SEP #$30
@@ -795,18 +833,22 @@ Routine_22E5A0:
     LDA $0C4C : CMP #$2C : BNE + ; $22E5B2
       INC $0C4C
       ;JMP $E5DB
+
   + ; 22E5B2
     LDA $0C4D : CMP #$2C : BNE ++ ; $22E5BF
       INC $0C4D
       ;JMP $E5DB
+
   ++ ; 22E5BF
     LDA $0C4E : CMP #$2C : BNE +++ ; $22E5CC
       INC $0C4E
       ;JMP $E5DB
+
   +++ ; 22E5CC
     LDA $0C4F : CMP #$2C : BNE ++++ ; $22E5D9
       INC $0C4F
       ;JMP $E5DB
+
   ++++ ; 22E5D9
     BRA +++++ ; $22E5E0
 
@@ -827,40 +869,51 @@ Routine_22E5F0:
     JMP $E108
 }
 
+; =========================================================
 ;22EE80
 ; TODO: Handle the somaria blast case, these JMPs are invalid.
+
 CheckForSomariaBlast:
 {
     LDA $0300 : BEQ + ; $22EE88
-  JMP $E5DB
+      ;JMP $E5DB
+
   + ; 22EE88
     LDA $0C4A : CMP #$01 : BNE ++ ; $22EE92
-  JMP $EEC0
+      ;JMP $EEC0
+
   ++ ; 22EE92
     LDA $0C4B : CMP #$01 : BNE +++ ; $22EE9C
-  JMP $EEC0
+      ;JMP $EEC0
+
   +++ ; 22EE9C
     LDA $0C4C : CMP #$01 : BNE ++++ ; $22EEA6
-  JMP $EEC0
+      ;JMP $EEC0
+
   ++++ ; 22EEA6
     LDA $0C4D : CMP #$01 : BNE +++++ ; $22EEB0
-  JMP $EEC0
+      ;JMP $EEC0
+
   +++++ ; 22EEB0
     LDA $0C4E : CMP #$01 : BNE ++++++ ; $22EEBA
-  JMP $EEC0
+      ;JMP $EEC0
+
   ++++++ ; 22EEBA
     JMP Routine_22E5A0_22E5A5 ; $E5A5
 }
 
-
-;; 22EF00
+; =========================================================
+; 22EF00
 ; Hooked inside LinkItem_Hookshot @ 07AB5E
+
 BallChain_StartAnimationFlag:
 {
-  LDA #$01 : STA $037B ; Restore vanilla code
+    ; Restore vanilla code
+    LDA #$01 : STA $037B 
     ; Check if we are rotating the goldstar
     LDA $037A : CMP #$04 : BNE + 
-  LDA #$01 : STA $0112 ; Animation flag, prevent menu from opening
+      ; Animation flag, prevent menu from opening
+      LDA #$01 : STA $0112 
   +
     RTL
 }
@@ -884,10 +937,10 @@ BallChain_Finish:
     RTL
 }
 
+; =========================================================
 ; 22EF30
 ; Hooked at $07AC98
 
-
 Hookshot_Init:
 {
   ; ResetAllAcceleration:
@@ -912,6 +965,8 @@ Hookshot_Init:
   RTL
 }
 
+; =========================================================
+
 Goldstar_Begin:
 {
     JSL CheckForBallChain
@@ -923,6 +978,8 @@ Goldstar_Begin:
     RTL
 }
 
+; =========================================================
+
 CheckForSwitchToGoldstar:
 {
     %CheckNewR_ButtonPress() : BEQ .continue
@@ -932,11 +989,12 @@ CheckForSwitchToGoldstar:
       .set_hookshot:
         LDA #$02 : STA GoldstarOrHookshot
   .continue:
-  ; Restore vanilla code
-  LDA.b $3A : AND.b #$40
+    LDA.b $3A : AND.b #$40 ; Restore vanilla code
     RTL
 }
 
+; =========================================================
+
 BeginGoldstarOrHookshot:
 {
     LDA GoldstarOrHookshot : CMP #$02 : BEQ .begin_goldstar
@@ -956,13 +1014,12 @@ BeginGoldstarOrHookshot:
     RTL
 }
 
+; =========================================================
+
 MaybeUploadBirdGraphicsToOam:
 {
-  LDY $037A
-  CPY #$0104
-  BEQ .here
-  LDY #$40E0
-  STY $2116
+    LDY $037A : CPY #$0104 : BEQ .here
+      LDY #$40E0 : STY $2116
       JML $008B30
   .here
     JML $008B50
@@ -970,6 +1027,9 @@ MaybeUploadBirdGraphicsToOam:
 
 pushpc
 
+; =========================================================
+; Main Hookshot/Goldstar hooks
+
 org $07AB25
   JSL CheckForSwitchToGoldstar