Create a project roadmap

[bonimy]

Right now, there's a lot of changes that need to be done for the disassembly. It would be helpful to find out the order we want to do these tasks in. Below is a short list of objectives we want to do. Let's take some time to figure out the order to do them in.

• - Move all large binary data into .bin folders that we can incbin. This will severely reduce compilation time. I'd also suggest making a tool that gets this binary data from a clean SMAS ROM and not keeping the data in the repo. This also reduces the risk of us hosting licensed Nintendo data without permission.
• - Synchronize this dis with mine where I already started splitting up files. Also we need to sync comments and documentation. There are helpful comments I have that you don't, and vice-versa.
• - Update the RAM map. We've discovered what a lot of RAM address do, but we haven't bothered to update/document their meanings. Some RAM values could also use more comprehensive descriptions, like $7E:00DB, which is currently defined as "Layer 2 BG index", but it better named as Area Index. This address does a lot and would take a few paragraphs defining everything it does.
• - Put SPC assembly into dis and not just binary data.
• - Do not put unused db $FF,$FF,$FF... into the dis where it's only purpose is to pad code. I suggest every bank start with fillbyte $FF : fill $8000 and then we add an ORG command to skip free space.
• - We need to label all pointers and correctly reference them in the dis. This is a nightmare task, but a very important one. If we do this along with the "remove unused db fills" task, we can freely inject code anywhere without corrupting the compiled product. Getting these two done is huge for development.
• - Split files into smaller files. Currently, each bank is contained in one file. This is a nightmare scenario. It's so easy for two people to modify the same bank file and we keep getting merge conflicts that are so hard to fix. It's how we got out of sync in the first place. I think this should be our first priority.
• - Put comments above code, not next to it. This is another way we get merge conflicts. Git diffs are done by line, so putting comments on the same line as code makes everything disgusting. In short, I want us to go from this:

CODE_00807D:    LDA $0122               ; $00:807D: AD 22 01    ;\ Wait for NMI
                BEQ CODE_00807D         ; $00:8080: F0 FB       ;/
                JSR CODE_0086CC         ; $00:8082: 20 CC 86    ;
                CLI                     ; $00:8085: 58          ;Enable IRQ
                INC $FD                 ; $00:8086: E6 FD       ;Frame counter increment

to this:

; Wait for NMI
-
{
   
    LDA $0122               ; $00:807D: AD 22 01
    BEQ -                   ; $00:8080: F0 FB
}

JSR CODE_0086CC             ; $00:8082: 20 CC 86
CLI                         ; $00:8085: 58

;Update frame counter
INC $FD                 ; $00:8086: E6 FD

• - Change short branch labels to + and - labels. If a code label is used only by a branch and no other code labels exist inbetween it, then they should be converted to a + or - label. The above shows a working example.

• - Place brackets in branch code. This helps visualize the program flow. Rather than every line having the same white-space padding, every branch code should increase the indent to improve readablity, as the below example shows.

LoadCustomAreaNumberAndType:
{
    PHB
    PHK
    PLB

    ; AreaNumber = GetAreaNumber()
    JSL.l GetCustomAreaNumber
    STA.w !AreaNumber

    JSL.l GetCustomAreaType
    STA.b !AreaType

    PLB
    RTL
}

GetCustomAreaNumber:
{
    PHB
    PHK
    PLB

    ; if CurrentWorld >= MaxWorldCount
    LDX.w !CurrentWorld
    CPX.b !MaxWorldCount
    BCC   +
    {
        ; MenuLevelNumber = CurrentLevel = CurrentWorld = 0
        STZ.w !MenuLevelNumber
        STZ.w !CurrentLevel
        LDX.b #$00
        STX.w !CurrentWorld
    }
+
    ; Y = CustomWorldAreaOffsetTable[CurrentWorld] + CurrentLevel
    LDA.w CustomWorldAreaOffsetTable,x
    CLC
    ADC.w !CurrentLevel
    TAX

    ; return CustomAreaNumberTable[Y]
    LDA.w CustomAreaNumberTable,x
    PLB
    RTL
}

This one may be hard to implement and the exact schematic is not well-defined yet, so I feel this is a very low-priority task, but it would be really helpful.

• - Name RAM addresses. Simply put, replaced instances of $0750 and $0756 with !AreaNumber and !CurrentPowerup where appropriate. This may also have some challenges with interpretation, so it's low-priority.

Right now, we need to figure the order we should do these tasks in and if there are any others we should do as well.