The wiki has been upgraded to MediaWiki 1.43. The wiki's theme is still being adapted to work with the new version, and may appear broken for the time being. --RanAS

Hitman Tool sprite guide

From SnesLab
Jump to: navigation, search
English Português Español 日本語

This guide shows how to create sprite hitboxes and use them to check for collisions with Mario, projectiles, and other sprites.

What you need

If this is your first time installing Hitman Tool, follow the Quick Start to set up your paths and find out which ROM to use with PIXI.

Create hitboxes for a Normal sprite

Define and link the boxes

Start with a sprite that has two poses. Pose 0 uses a 16 × 16 pixel box. Pose 1 keeps the same width, but the box starts 8 pixels lower and is only 8 pixels tall.

Save this as MiSprite.hitboxinfo next to the sprite's main ASM file.

HitboxesPerPose:
    .Pose0 0
    .Pose1 1

Hitbox0:
    .Width $10
    .Height $10

Hitbox1:
    .YOffset $08
    .Width $10
    .Height $08

In the same folder, create MiSprite.hitman.json. Setting HitboxSystem to 03 tells Hitman to use the current pose when another sprite checks for a collision with yours.

{
  "Name": "MiSprite",
  "IsCustom": true,
  "Properties": [
    { "PropertyName": "HitboxSystem", "Value": "03" }
  ]
}

Add these lines to the sprite's main ASM file.

;#inchbi "MiSprite.hitboxinfo"
;#inchmprop "MiSprite.hitman.json"

See HitboxInfo and Publish a Normal sprite's hitbox for other ways to set up boxes.

Tell Hitman which pose the sprite is using

To keep the boxes in sync with the animation, use the same pose index you use to draw the sprite. Store the base context plus the pose index in INIT and update it whenever the pose changes. This example starts at pose 0 without flipping.

; A and indices are 8-bit. X = Normal sprite slot.
LDA.b #!MiSpriteHitboxContext
STA !HitmanNormalContextIDLow,x
LDA.b #!MiSpriteHitboxContext>>8
STA !HitmanNormalContextIDHigh,x
LDA #$00
STA !HitmanNormalFlip,x

For pose 1, add 1 to !MiSpriteHitboxContext before splitting it into two bytes. Update !HitmanNormalFlip,x when the sprite flips. The values 0, 1, 2, and 3 mean no flip, horizontal, vertical, and both. Set a pivot in the hitbox file if you want an offset to mirror along that axis.

Detect a collision with Mario

Pass the base context plus the current pose to Hitman. !PoseIndex holds the current pose index. You can define a table with one byte per slot and update it when the pose changes. With Dynamic Xtreme, you can use !LastPoseIndex,x if it contains a valid pose and the hitbox file uses the same indices. In this example, the sprite jumps when it collides with Mario.

; A and indices are 8-bit. X = Normal sprite slot.
LDA !HitmanNormalFlip,x
STA !HitmanSprite1Flip
LDA !PoseIndex,x
REP #$21
AND.w #$00FF
ADC.w #!MiSpriteHitboxContext
JSL !Hitman_Base_PlayerNormalSpriteInteractionWithoutCallback
BCC .SinContacto
LDA #$E0
STA !SpriteYSpeed,x
.SinContacto

With WithoutCallback, Carry is set if the sprite collides with Mario. To run a different action for each box, assign .OnPlayerCollision or .OnPlayerNonCollision and use !Hitman_Base_PlayerNormalSpriteInteraction. In that version, Carry indicates whether the callbacks left a result in !HitmanDefault. See PlayerSpriteInteraction and Create a callback.

Use a single hitbox on a Normal sprite

To set the size and position from ASM, store the X and Y offsets, width, and height in the sprite's tables. Call PlayerNormalSpriteOneHitboxInteraction to see if it collides with Mario.

; A and indices are 8-bit. X = Normal sprite slot.
LDA #$02
STA !HitmanNormalXOffLow,x
LDA #$FC
STA !HitmanNormalYOffLow,x
LDA #$0C
STA !HitmanNormalWidthLow,x
LDA #$10
STA !HitmanNormalHeightLow,x

JSL !Hitman_Base_PlayerNormalSpriteOneHitboxInteraction
BCC .SinChoque
; Handle the collision with Mario here.
.SinChoque

The box is 12 × 16 pixels, starting 2 pixels right and 4 pixels above the sprite's origin. For a fixed box, write the four values in INIT and leave the call in MAIN. Set HitboxSystem to 02 if other sprites should use the same box when checking collisions.

Use a 16-bit hitbox

Use PlayerNormalSpriteOneLongHitboxInteraction when the box needs larger dimensions or offsets. Write both bytes of each value. This box is 288 × 32 pixels and starts 144 pixels left and 4 pixels above the sprite's origin.

; A and indices are 8-bit. X = Normal sprite slot.
; X offset = $FF70 (-144), Y offset = $FFFC (-4).
LDA #$70
STA !HitmanNormalXOffLow,x
LDA #$FC
STA !HitmanNormalYOffLow,x
LDA #$FF
STA !HitmanNormalXOffHigh,x
STA !HitmanNormalYOffHigh,x

; Width = $0120 (288), height = $0020 (32).
LDA #$20
STA !HitmanNormalWidthLow,x
STA !HitmanNormalHeightLow,x
LDA #$01
STA !HitmanNormalWidthHigh,x
LDA #$00
STA !HitmanNormalHeightHigh,x

JSL !Hitman_Base_PlayerNormalSpriteOneLongHitboxInteraction
BCC .SinChoque
; Handle the collision with Mario here.
.SinChoque

For a fixed box, write the values in INIT and call the routine from MAIN. Set HitboxSystem to 04 so other sprites can check this box.

Respond to a vanilla interaction

Suppose you want a fireball to make the sprite jump. Disable the game's usual response to the hit and leave the notification enabled.

Add these two properties to the sprite's JSON. Keep HitboxSystem in the same list if you already set it.

{ "PropertyName": "VanillaEventMask", "Value": "08" },
{ "PropertyName": "VanillaResponseMask", "Value": "77" }

Add "VanillaCallbacks": { "Fireball": "MiSpriteAlRecibirFuego" } to the JSON. Save the routine as Routines/MiSpriteAlRecibirFuego.asm inside Hitman Tool.

MiSpriteAlRecibirFuego:
    ; A = event, X = target, Y = Extended sprite slot.
    LDA #$E0
    STA !SpriteYSpeed,x
    RTL

To respond in MAIN instead, enable the event and check its bit in !Hitman_Prop_ActionFlag,x. Clear that bit once you have handled it. See Event flags and callbacks for the other events.

Adapt the examples to Cluster sprites and Extended sprites

All three families can use the same MiSprite.hitboxinfo. Link it with ;#inchbi and keep the base-context-plus-pose calculation. The example's HitboxSystem JSON and ;#inchmprop directive apply to Normal sprites.

Original example Cluster sprite Extended sprite
Put the Normal sprite slot in X. Put the Cluster sprite slot in X. Put the Extended sprite slot in X.
Write !HitmanNormalContextIDLow,x and !HitmanNormalContextIDHigh,x. Use !HitmanClusterContextIDLow,x and !HitmanClusterContextIDHigh,x. Use !HitmanExtendedContextIDLow,x and !HitmanExtendedContextIDHigh,x.
Use !HitmanNormalFlip,x. Use !HitmanClusterFlip,x. Use !HitmanExtendedFlip,x.
Call !Hitman_Base_PlayerNormalSpriteInteractionWithoutCallback. Call !Hitman_Base_PlayerClusterSpriteInteractionWithoutCallback. Call !Hitman_Base_PlayerExtendedSpriteInteractionWithoutCallback.

Keep BCC .SinContacto to skip the response when there is no collision. If you want the sprite to jump, write to its family's velocity table. !SpriteYSpeed,x is for Normal sprites. To use callbacks, remove WithoutCallback from the routine name and read !HitmanDefault.

If the Extended sprite should also collide with Normal sprites as a projectile, configure it by number in ASM/ExtendedSpriteTablesConfig.asm. Choose $03 to use its pose hitboxes in that check. See Configure Extended sprites.

Detect collisions between sprites from ASM

If you already have both slots, these routines set Carry when the sprites collide.

Pair Call
Two Normal sprites JSL !Hitman_Base_CheckNormalPair. Put one Normal sprite slot in X and the other in Y.
Extended sprite and Normal sprite JSL !Hitman_Base_CheckExtendedNormalPair. Put the Normal sprite slot in X and the Extended sprite slot in Y. Configure the Extended sprite's hitbox mode first.

Compare boxes from other sprite families

AnyNormalSpriteInteractionOneHitbox looks up a Normal sprite's box configuration. For a Cluster or Extended sprite on the receiving side, use the box format it was set up to use. If both sprites use one RAM box, use these calls. Each takes the slot for its family in X.

Family Load HB1 Load HB2
Normal sprite NormalSpriteOneHitbox1 NormalSpriteOneHitbox2
Cluster sprite ClusterSpriteOneHitbox1 ClusterSpriteOneHitbox2
Extended sprite ExtendedSpriteOneHitbox1 ExtendedSpriteOneHitbox2

Call JSL !Hitman_Base_CheckContact once both boxes are ready and read Carry. Use the LongOneHitbox variant to load a box with 16-bit fields. If the other sprite uses a pose with several boxes, use GetHitbox2 to load each box and compare it with HB1. See Prepare and compare boxes.

Disable collisions between Normal sprites

If one sprite carries another, you can stop them from colliding while they are together. Put the carrier's slot in X and the passenger's slot in Y. Call SetSpritePairCollision with A set to $00 to block the pair. When the carrier releases the passenger, set A to $01 to allow collisions again.

; A and indices are 8-bit. X = carrier, Y = passenger.
LDA #$00
JSL !Hitman_Base_SetSpritePairCollision

; On release, after checking that Y still identifies the passenger.
LDA #$01
JSL !Hitman_Base_SetSpritePairCollision

This applies in both directions. If you store the passenger's slot for several frames, check that it still belongs to the same sprite before using it again. Hitman resets the pairs when it initializes a slot.

To change every pair for the Normal sprite in X, use !Hitman_Base_SetSpriteSlotCollision with the same values in A. The mask applies to vanilla Normal sprite collisions. Manual checks like CheckNormalPair still report whether the boxes overlap. See SetSpritePairCollision and SetSpriteSlotCollision.

Configure the Extended sprite tables

Edit ASM/ExtendedSpriteTablesConfig.asm inside Hitman Tool. The patch builds these tables when installed. They control how Extended sprites collide with Normal sprites. The macros take an Extended sprite number. During the game, the collision routines take the slot of a particular projectile.

Choose the hitbox

Use %SetExtendedHitboxSystem(number, mode) to choose where Hitman gets the boxes.

Mode What Hitman uses
$00 The Extended sprite is skipped.
$01 A fixed box. Set its X offset, Y offset, width, and height with %SetExtendedHitbox.
$02 One RAM box. Store signed offsets and dimensions in the Low bytes of !HitmanExtendedXOff, !HitmanExtendedYOff, !HitmanExtendedWidth, and !HitmanExtendedHeight.
$03 The current pose's boxes. Store the base context plus pose and the flip as shown above.
$04 One 16-bit RAM box. Write both the Low and High bytes of each offset and dimension.

Use the Extended sprite's slot when writing its RAM tables. If you change modes, write the new mode's data again because the pose and offsets share some bytes.

Choose what happens on impact

%SetExtendedFireballEvent sets the response separately from the shape. Choose !HitmanEventFireball for Mario's fireball response, !HitmanEventYoshiFireball for Yoshi's, or $00 to handle the impact yourself.

This gives projectile $20 a fixed 12 × 16 pixel box and Mario's fireball response.

%SetExtendedHitboxSystem($20, $01)
%SetExtendedHitbox($20, $0002, $FFFC, $000C, $0010)
%SetExtendedFireballEvent($20, !HitmanEventFireball)

The box starts 2 pixels right and 4 pixels above the origin. In the projectile's code, put its slot in X and call JSL !Hitman_Base_RunVanillaFireballInteraction with A and the index registers in 8-bit mode. To handle the impact yourself, use event $00 and call CheckExtendedNormalPair with the Normal sprite in X and the projectile in Y.

Mario's ($05) and Yoshi's ($11) fireballs are already configured. Other numbers start with mode and event $00. Reinstall Hitman Tool and reinsert the resources that use its defines after changing these settings. See Configure Extended sprites for the RAM tables and calling conventions.

Install the sprite

  1. Add the sprite to the PIXI list.
  2. Run Hitman Tool with that list.
  3. Run PIXI on the output ROM with the same list.
  4. If you use Hitman with UberASMTool, run UberASMTool again on that ROM.