Making an NPC
This page gives an outline of how one might make a custom NPC using ZOSE. Patch (interaction
$9400) will be used as a template.
This process may be easier with a pure disassembly approach, but for now, it's assumed that the disassembly can't be used directly for this purpose (since most hacks are using the mostly-incompatible ZOLE).
NPCs are interaction objects. They generally have two components: their assembly code, and their script. As a rough guideline, things that should be updated every frame are put in their assembly code, and sequences of events that occur over many frames are put into scripts.
The NPC's sprite and animations are tied to the high byte of their ID. So, interactions
$9400-$94ff must all use the same graphics (patch's sprites). This means you need to be careful when selecting an NPC to modify.
You should preferably know:
- Everything here
- How to write basic scripts in ZOSE
- A bit of assembly knowledge
Modifying assembly code
The recommended method is to use the BGB emulator with a symbol file. This will allow you to use the Ctrl-G hotkey to jump to any known label, without needing to know its address. For instance, typing "interactionCode94" in that window would take you directly to Patch's code.
The code itself can be modified in the debugger by right-clicking and selecting "modify code/data", then typing the opcodes (separated by semicolons).
Start by creating a basic script in ZOSE. It can be expanded later. Something like the following will do:
WriteLocation X SetInteraction72 Y InitCollisions WriteLocation X+1 // Just for clarity CheckAButton ShowText <textindex> Jump2byte X+1
This is the most basic kind of NPC; it will show text when you press A in front of it, and loop forever. (Note: the lack of labels in ZOSE requires you to calculate the address for the loop by hand. In this case, the "InitCollisions" opcode only takes up one byte.)
The "SetInteraction72" line is not necessary, since you will not be using the script with interaction 72 (we're using patch, interaction 94, instead). Still, you can use interaction 72 to test the script before replacing Patch. (It will behave like an invisible NPC.)
Modifying the NPC's assembly code
The vast majority of NPCs have assembly code that you won't want. Patch, in particular, has a great deal of logic referring to whether you've obtained the tuni nut, etc. We'll want to get rid of all of that.
We will use the disassembly for reference. Open main.s and search for
interactionCode94. This will take you to the code that runs for the interaction on each frame. You will see something like this:
interactionCode94: ld e,$42 ; $787e ld a,(de) ; $7880 ld e,$44 ; $7881 rst_jumpTable ; $7883 .dw $7894 .dw $793c .dw $7a98 .dw $7b4c .dw $7bf0 .dw $7bf0 .dw $7c40 .dw $7c40
In the context of an object's code, the 'd' register represents the high byte of the object's RAM block. Brush up on the memory structure for interactions. In doing so, you'll see that the first 2 lines:
ld e,$42 ld a,(de)
get the interaction's "subid" byte. Our interaction's full ID is
$9400; so the "id" byte is $94, and the "subid" byte is $00. It then uses this byte in a jump table, meaning it will jump to the first entry in the jump table, address $7894. You can ignore all of the other entries since they pertain to different subids.
At that address, you'll then come across another jump table:
ld e,$44 ; $7894 ld a,(de) ; $7896 rst_jumpTable ; $7897 .dw $789e .dw $7913 .dw $7928
$44 is the object's "state" byte. Patch has 3 states, but we will only need 2: state 0 for "uninitialized", and state 1 for "initialized".
Patch's state 0 is quite large, but we only need a few function calls. Replace the code for state 0 (starting at
0a:789e) with the following:
call interactionInitGraphics call interactionIncState ld hl, <scriptAddress> jp interactionSetScript
"<scriptAddress>" must be in bank C, which means you can't point it directly to your actual script. Look through the npc's code to find an unused script. Patch has a few; we'll use
script787e in this example.
We'll use this as a bootstrap for the actual script. Add the following lines to the top of your script in ZOSE:
WriteLocation 3387e // 0c:787e converted to an absolute address LoadScript X // Where X is the address of your script, as above
Patch's state 1, at
0a:7913, is quite close to what we need compared to state 0. The end result should look like this:
ld c,$20 call objectUpdateSpeedZ_paramC call interactionRunScript jp npcAnimate_staticDirection
objectUpdateSpeedZ_paramC will allow the
setZSpeed script command to work properly.
npcAnimate_staticDirection, as you probably suspected, animates the npc without modifying its direction.
Note that the the main difference to Patch's state 1 is the last line, which was originally
jp nc,npcAnimate_followLink. Not only was it a conditional jump, but it called a different variant of
npcAnimate, which constantly updates the object's direction to face Link when he's close enough. This is problematic when the
MoveNPCUp/Down/Left/Right opcodes are used, so the static variant is used instead.
The final result
// The script's "bootstrap" (somewhere in bank C) WriteLocation 3387e // 0c:787e converted to an absolute address LoadScript X // Where X is the address of the script // The script itself WriteLocation X InitCollisions WriteLocation X+1 // Just for clarity CheckAButton ShowText <textindex> Jump2byte X+1
The following is what the NPC's code should look like on a general level (with labels being used everywhere, unlike in the example with patch).
interactionCodeXX: ld e,Interaction.subid ld a,(de) rst_jumpTable .dw @subid0 .dw ... ... @subid0: ld e,Interaction.state ld a,(de) rst_jumpTable .dw @state0 .dw @state1 @state0: call interactionInitGraphics call interactionIncState ld hl, <scriptAddress> jp interactionSetScript @state1: ld c,$20 call objectUpdateSpeedZ_paramC call interactionRunScript jp npcAnimate_staticDirection
Jump opcodes before ZOSE v0.7
As of ZOSE v0.7.00, jump opcodes can be used in any context. Before, however, 3-byte jumps only worked with interaction 72, and 2-byte jumps only worked with everything but interaction 72. If you used to use an older version of ZOSE, you may need to click "Re-apply ASM patches" to fix this.
The built-in jumping opcodes (jump2byte, jumpifmemoryeq, etc) have the following limitations:
- The destination must be in bank $0C, OR
- The destination must be within 256 bytes of the start of the script. It cannot jump anywhere before the start of the script.
- The "start of the script" is the point at which the last "LoadScript" or "Jump3Byte" opcode was invoked.