Direct addressing of KosM pieces: the bane of novice Sonic 3 hackers

Today's topic is something I personally fell prey to when I started hacking. Sonic Retro user VMordecai semi-recently ran into a problem while working on their Sonic 3 hack:

I've encountered some bugs on my way, and I have no idea what to do with them yet. Like this sprite for special stage, that consists of two files. Second half doesn't read properly.

The sprites in question are compressed in Kosinski Moduled format. Recall that in the KosM format, data is first split into $1000 byte-long pieces, and then each piece is compressed using regular Kosinski compression. Jet's continue icon (Sonic's in the original) happens to straddle the $1000 byte boundary:

However, if you look through the files in the disassembly, you won't actually find these graphics in the KosinskiM Art folder. The definition for ArtKosM_SSResults in sonic3k.asm reveals why:

ArtKosM_SSResults:
    dc.b  $12, $A0
ArtKos_SSResultsGeneral:
    binclude "General/Special Stage/Kosinski Art/SSResults General.bin"
    even
ArtKos_SSResultsTKIcons:
    binclude "General/Special Stage/Kosinski Art/SSResults Tails Knuckles Icons.bin"
    even

Holy goodness, what is happening here?

Recall that in the KosM format, data is first split into $1000 byte-long pieces, and then each piece is compressed using regular Kosinski compression. This means that each individual piece is a actually a valid Kosinski archive, and as such can be decompressed directly by the regular Kosinski decompressor!

And that's exactly what happens in the Competition results screen. You see, some clever programmer thought, "gosh, we already have the continue icons from the Special Stage results, so I'll just use those. But I don't need the letters or the Chaos Emeralds, so I'll decompress the individual KosM pieces to RAM and then copy the fully assembled icons from RAM to VRAM."

The solution to this madness is to compress the whole thing directly in KosM format and compare it to the split version: there's usually some padding that needs to be added at the end of the split version's first piece.

The better solution is to give the Competition screen its own set of icons. If it hurts when you do that then don’t do that.