SCHG How-to:Port Knuckles into Sonic 2

(Original guide by MainMemory)
Note: this guide is written with the Sonic 2 Hg disassembly in mind.

Getting the Knuckles object and putting it in Sonic 2

First you will need s2k.asm from the Knuckles in Sonic 2 disassembly.
Open s2k.asm, select everything from Obj01: (line 27324) to the end of ArtConvTable (line 30585), and copy it into a new asm file called Knuckles.asm in your S2 disasm folder. This is so we don't accidentally change something in our Sonic 2 disassembly while we're fixing Knuckles.
Open Knuckles.asm and do a Find and Replace operation to replace every instance of "Obj01" (without quotes) with "ObjXX", where XX is the object ID you want Knuckles to use. The following IDs are unused in Sonic 2: 4C, 4D, 4E, 4F, 62, D0, D1, and everything from DD to FF. Use that ID whenever I refer to ObjXX.
Next, do the following replacements: "CheckGameOver" to "ObjXX_CheckGameOver", "JmpTo_KillCharacter" to "JmpToK_KillCharacter", "Player_CheckFloor" to "Sonic_CheckFloor".
Find the line <asm> bsr.w Adjust2PArtPointer2_Useless</asm> and change it to <asm> jsr Adjust2PArtPointer2</asm> Now you'll need to copy some more code from s2k.asm. Specifically, sub_3192E6, loc_318FE8, sub_318FF6, loc_319208 and loc_3193D2. Because they're all small routines, I'll paste them here: <asm>; =============== S U B R O U T I N E =======================================

Doesn't exist in S2

sub_3192E6:  ; ... move.b $17(a0),d0 ext.w d0 sub.w d0,d2 eor.w #$F,d2 lea ($FFFFF768).w,a4 move.w #-$10,a3 move.w #$800,d6 bsr.w FindFloor move.b #$80,d2

loc_319306: bra.w loc_318FE8

End of function sub_3192E6

START OF FUNCTION CHUNK FOR CheckRightWallDist

loc_318FE8:  ; ... move.b ($FFFFF768).w,d3 btst #0,d3 beq.s return_318FF4 move.b d2,d3

return_318FF4:  ; ... rts

END OF FUNCTION CHUNK FOR CheckRightWallDist

=============== S U B R O U T I N E =======================================

sub_318FF6:  ; ... move.b $17(a0),d0 ext.w d0 add.w d0,d2 lea ($FFFFF768).w,a4 move.w #$10,a3 move.w #0,d6 bsr.w FindFloor move.b #0,d2 bra.s loc_318FE8

End of function sub_318FF6

---------------------------------------------------------------------------

This doesn't exist in S2...

START OF FUNCTION CHUNK FOR sub_315C22

loc_319208:  ; ... move.b $17(a0),d0 ext.w d0 add.w d0,d3 lea ($FFFFF768).w,a4 move.w #$10,a3 move.w #0,d6 bsr.w FindWall move.b #$C0,d2 bra.w loc_318FE8

END OF FUNCTION CHUNK FOR sub_315C22

---------------------------------------------------------------------------

START OF FUNCTION CHUNK FOR sub_315C22

loc_3193D2:  ; ... move.b $17(a0),d0 ext.w d0 sub.w d0,d3 eor.w #$F,d3 lea ($FFFFF768).w,a4 move.w #$FFF0,a3 move.w #$400,d6 bsr.w FindWall move.b #$40,d2 bra.w loc_318FE8

END OF FUNCTION CHUNK FOR sub_315C22</asm>

Put this code at the end of Knuckles' asm.

Now we're ready to put the code in our S2 disassembly, so open s2.asm. You can place Knuckles' code wherever you want, but the place that seems to cause the fewest errors is right before Obj79. You can either add the line <asm>include "Knuckles.asm"</asm> or just copy and paste his code in.
When you do that, run build.bat in the S2 disassembly. It should tell you there are 14 errors and to check s2.log, so that's what we'll do. Everything in the log will be in this format:

> > >s2.asm(line#): error: jump distance too big
> > > 	bsr.w	label

What you need to do is go to each line and change the bsr.w to jsr. There is one line that's a bra.w instead, change that to jmp.

Importing Knuckles' art and mappings

If you try to build now, you will see three "symbol undefined" errors: SK_Map_Knuckles, SK_PLC_Knuckles and SK_ArtUnc_Knux. So let's fix those.