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 files and formats

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

Hitman Tool reads files that define properties, override them for individual sprite types, or describe a resource's hitboxes.

File types

Type What it does Where it goes
Property definition (JSON) Creates a property and supplies its initial values. CustomProperties/
Per-sprite configuration (JSON) Sets property overrides and vanilla event callbacks for a Normal sprite type. Beside the resource via ;#inchmprop, or in CustomProperties/PerSprite/.
.hitboxinfo Defines hitboxes and assigns them to poses. Beside the resource via ;#inchbi, or in HitboxInfo/.

The CustomProperties/ and HitboxInfo/ directories are inside the Hitman Tool folder.

Linking files from PIXI and UberASMTool

Put the directives in the resource's main ASM file. Paths are relative to that file's folder.

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

A PIXI or UberASMTool ASM file can link several .hitboxinfo files. Each generates a context define from its filename. For example, MiSprite.hitboxinfo generates !MiSpriteHitboxContext in HitmanDefines.asm. A linked file takes precedence over a file of the same name in HitboxInfo/.

Use ;#inchmprop at most once in the main ASM file of a PIXI Normal sprite. See the Quick Start to install the resources and regenerate the defines.

Define properties

Create a JSON file in CustomProperties/. Give the property a name and set the initial value for vanilla and custom Normal sprites. Write each one-byte value as a quoted hexadecimal string.

{
  "Name": "IsLarge",
  "DefaultValueVanilla": "00",
  "DefaultValueCustom": "00"
}

Here all sprites start with 00 (small). Set 01 for a large sprite so other sprites can tell which response to apply.

Override properties for a sprite

This JSON sets IsLarge to 01 on every instance of one custom sprite type. Properties you leave out keep their initial values.

{
  "Name": "MiSprite",
  "IsCustom": true,
  "Properties": [
    { "PropertyName": "IsLarge", "Value": "01" }
  ]
}

For a custom sprite configured in CustomProperties/PerSprite/, set Name to the base name of its PIXI CFG or JSON file. For MiSprite.json, use MiSprite. When using ;#inchmprop, Hitman gets the name from the PIXI entry. For a vanilla sprite in the central folder, set "IsCustom": false and put its hexadecimal number in ID.

You can also add a VanillaCallbacks object. The fields are SpriteSprite, Fireball, YoshiFireball, Quake, and CapeDive. Each value names a routine. Set the matching bit in VanillaEventMask to receive the event. Older configurations can use VanillaInteractionCallback as a fallback and for explosions.

HitboxInfo

Each .hitboxinfo file defines a hitbox context. A pose can contain several boxes, share boxes with other poses, or be empty. Both formats can be used in the same installation. Use one format per file.

Current format

AllHitboxes:
    .XOffset $08
    .XPivot $08

HitboxesPerPose:
    .Pose0 0
    .Pose1..2 0,1
    .Pose[4,6] 1
    .Pose7

AllHitboxCallbacks:
    .OnPlayerNonCollision CheckPlayerIsAbove

Hitbox0:
    .YOffset $FFFF
    .Width $10
    .Height $08
    .OnPlayerCollision CheckBounce

Hitbox1:
    .XOffset $0C
    .Width $08
  • HitboxesPerPose: lists each pose's boxes in the order Hitman checks them. Pose and box numbers are decimal. .Pose1..2 covers poses 1 and 2, while .Pose[4,6] selects only 4 and 6. A pose with no boxes, such as pose 7, is empty. Missing pose numbers are empty as well.
  • HitboxN: defines box N. .XOffset and .YOffset move the box relative to the object's origin. .Width and .Height must be positive and are measured in pixels. For a vertical offset of −1 use $FFFF. $FF means +255 here.
  • AllHitboxes: can shift all boxes. .XPivot and .YPivot set the point each axis is mirrored around. A box can override its pivot, including with $00. Hitman adds the global offset after mirroring.
  • AllHitboxCallbacks: supplies shared callbacks. Each box can override them separately. .OnPlayerCollision runs on collision with Mario and .OnPlayerNonCollision runs when the box does not collide with him. The reader accepts fields for other families, but the current patch only runs these two per-box callbacks from this format.

Older files in this format can use AllHitboxXOffset: and AllHitboxYOffset:, which apply the shift before mirroring. Use either those sections or AllHitboxes: in a file.

Defaults

Field If omitted
.XOffset and .YOffset $00. Any offset defined in AllHitboxes: is added to the box.
.Width and .Height $10 (16 pixels) per axis.
.XPivot and .YPivot The pivot in AllHitboxes:. If there is no pivot there either, flipping leaves the offset for that axis unchanged.
.OnPlayerCollision and .OnPlayerNonCollision The matching callback in AllHitboxCallbacks:, or Nothing if none is set there.

Legacy format

The legacy format uses parallel tables. The first entry in each table belongs to box $00.

PoseHitBoxes:
    db $00,$FF
    db $FF

HitboxXOffset:
    dw $0000
HitboxYOffset:
    dw $FFFF
HitboxWidth:
    dw $0010
HitboxHeight:
    dw $0008
HitboxAction1:
    dw $0000
HitboxAction2:
    dw $0002
Actions:
    dw CheckBounce
    dw CheckPlayerIsAbove
  • Pose 0 uses box $00. Each pose ends in $FF. Pose 1 has only that terminator, so it is empty.
  • Offsets, width, and height have one entry per box. Optional HitboxXOffsetFlip and HitboxYOffsetFlip tables specify flipped offsets. If omitted, Hitman uses the original offsets.
  • HitboxAction1 selects the contact routine and HitboxAction2 selects the non-contact routine. Both are byte offsets into Actions:. Use $0000 for the first routine, $0002 for the second, and so on. If no actions are declared, Hitman uses Nothing.

Include helper routines

Use Dependencies: when a callback needs a helper that Hitman cannot find on its own, for example because the name only appears inside a macro. Write dw followed by the routine name without .asm. Hitman looks for the file in Routines/ and includes it in the patch.

Dependencies:
    dw PlayerFloor

This includes Routines/PlayerFloor.asm. It does not call the routine or assign it to a box. HitboxAction1 and HitboxAction2 still refer to entries in Actions:.