Hitman Tool files and formats
| 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..2covers 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..XOffsetand.YOffsetmove the box relative to the object's origin..Widthand.Heightmust be positive and are measured in pixels. For a vertical offset of −1 use$FFFF.$FFmeans +255 here.AllHitboxes:can shift all boxes..XPivotand.YPivotset 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..OnPlayerCollisionruns on collision with Mario and.OnPlayerNonCollisionruns 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
HitboxXOffsetFlipandHitboxYOffsetFliptables specify flipped offsets. If omitted, Hitman uses the original offsets. HitboxAction1selects the contact routine andHitboxAction2selects the non-contact routine. Both are byte offsets intoActions:. Use$0000for the first routine,$0002for the second, and so on. If no actions are declared, Hitman usesNothing.
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:.