sonicretro/skdisasm — pull request #1 by Clownacy (2014-06-04 23:52:37+00:00)
Title: Some documentation, some added macros/variables/equates

;------------------------------------------------------------------
Changes
;------------------------------------------------------------------

Commented Tails' Tails object

Commented S2 Shield object

Commented Insta-Shield object

Commented Fire Shield object

Commented Bubble Shield object

Commented Lightning Shield object (and nearby related code)

Commented Lightning Shield Spark object (unsure if the code I found was the entire object, however)

Commented KosArt_To_VDP

Macro-ised VRAM-related data moved to a2 before KosArt_To_VDP is branched to

Greatly documented (and renamed) SuperSonic_PalFlash (wish all my work on this disasm was like this)

Started documenting Obj_Sonic in S2 disasm style

Sonic_InstaAndShieldMoves is in a better place now... (label name used in a more appropriate area)

Commented Shield attacks and some Super/Hyper code

Renamed HyperSonic_Create_Spark

Labelled Subroutines:
sub_12006
sub_F894
loc_FC4A

Added S2 macros:
make_art_tile
tiles_to_bytes

Added Elemental Shield DPLC variable equates, applied them to Elemental Shields and PLCLoad_Shields

Added player status variables equates, used in some areas

Added player status_secondary variables equates, used in some areas

Added RAM constants:
Palette_frame
Palette_timer
Super_Hyper_palette_status
Palette_frame_Tails
Palette_timer_Tails
WindTunnel_flag
Primary_Angle
Secondary_Angle
Water_entered_counter

I may have forgotten a fair portion of information, I've been on/off with this thing and my smaller changes may have fallen from memory, I've been mostly assembling this changelog as I've been making said changes, so, with hope, this is accurate.

;------------------------------------------------------------------
Notes
;------------------------------------------------------------------

I would have used more temporary labels, but you've seen how people bitch

I've tried to keep all old labels commented above the new ones

Whatever code I've touched has had most, if not all, 'bcs/bcc's after 'cmp's changed to 'blo/bhi', respectively, to enhance readability. This still produces a bit-perfect ROM

I'm suspicious that SuperHyper_PalCycle_ApplyTails's designation as a 'subroutine' is erroneous (or at the very least, messy =P), as similar code lacks this formatting and title (after noting this, I've been fooling with IDA's formatting for neater code, see the area around HyperSonic_Create_Spark for what I mean)

Sod it, Obj_Sonic has S2 labels now, I can't settle on an in-between

Late into the commenting, I started commenting the labels that would be temporary with "; +", also adding this to some of the older code, but wasn't thorough

I had started on Obj_Sonic, but have given up for now. The approach I had used, starting from the label and commenting everything following it, was very tiring and error-prone. I prefer the approach I had used elsewhere: 'Focus on small, individual sections that will eventually form a whole' Or, to word it differently: 'Working on the small internal sections of code, then, once fully understood, work on the code that uses said code'. With my work on Obj_Sonic being 'work on the framework first', it was like walking around in the dark: "This code branches to this sprawling subroutine and uses the registers it writes to, I should work on that subroutine first, but that code is later in the file, I have to work on this first... even though I don't know what it's doing..." I'll work on it more, but not now

;------------------------------------------------------------------
Foggy areas
;------------------------------------------------------------------

Some areas I don't understand, but don't want to clutter with confused comments:

My understanding of the 'Target_water_palette-Water_palette' relationship is non-existent, but, if my guesswork is right, Target is storage, not what is going to be pushed to CRAM on the next H-Int, while Water_palette IS. If that's the case, then isn't LightningShield_FlashWater just a 'part 1' to the 'part 2' that is LightningShield_Destroy? With FlashWater setting up the palette in Target, and Destroy then writing the edited palette to Water_palette to be displayed? Or, throwing the theory behind it out of the window, LightningShield_FlashWater makes the palette black and white, and LightningShield_Destroy restores it to its coloured state almost immediately afterwards?

loc_193CA moves 2 to d2, then branches to LightningShield_Create_Spark_Part2. The only instruction that branching to LightningShield_Create_Spark would have added? Moving 2 to d2. What the heck? Why? Is there any reason for such a redundancy? Granted, I already found another Hyper Sonic-related redundancy under SuperSonic_PalFlash, but seriously! Was Hyper really THAT slapped-on?

Obj_Lightning_Shield_Spark, what the heck interacts with Obj_Lightning_Shield_Spark's byte 5?

In these areas with this confusion, documentation can be lacking.

;------------------------------------------------------------------
Other
;------------------------------------------------------------------

Given how on/off I've been with this, I worry about how long it will be before this work sees the light of day, so, while somewhat incomplete (especially in Obj_Sonic's case), I'm submitting what I've done so far. I will be contributing more at some point or another. The work is based on my own documentation and understanding of objects gathered whilst porting them to my Sonic 2 hack, hence the selectiveness. Among these elements are Obj_Sonic and Render_Sprites, but they've yet to be fully documented, leading to the former's incompleteness and the latter's absence. This should produce a bit-perfect ROM, and has been frequently tested for just this during development.