es/Hitman Tool sprite guide
| English | Português | Español | 日本語 |
En esta guía vas a crear hitboxes para un sprite y usarlas para detectar choques con Mario, con proyectiles y con otros sprites.
Qué necesitas
Si es la primera vez que instalas Hitman Tool, sigue el Quick Start para preparar las rutas y saber en qué ROM insertar el sprite.
Crear hitboxes para un Normal sprite
Define las cajas y enlaza los archivos
Para empezar, vamos a usar un sprite con dos poses. La pose 0 ocupa un cuadrado de 16 × 16 píxeles. La pose 1 conserva el ancho, pero su caja se desplaza 8 píxeles hacia abajo y solo mide 8 píxeles de alto.
Guarda este archivo como MiSprite.hitboxinfo junto al ASM principal.
HitboxesPerPose:
.Pose0 0
.Pose1 1
Hitbox0:
.Width $10
.Height $10
Hitbox1:
.YOffset $08
.Width $10
.Height $08
Crea MiSprite.hitman.json en la misma carpeta. Con HitboxSystem en 03, Hitman usa las cajas de la pose actual cuando otro sprite comprueba si choca con el tuyo.
{
"Name": "MiSprite",
"IsCustom": true,
"Properties": [
{ "PropertyName": "HitboxSystem", "Value": "03" }
]
}
Añade estas líneas al ASM principal del sprite.
;#inchbi "MiSprite.hitboxinfo" ;#inchmprop "MiSprite.hitman.json"
Si quieres consultar otros modos de hitbox o reutilizar cajas entre poses, consulta HitboxInfo y Publicar la hitbox de un Normal sprite.
Indica qué pose está usando el sprite
Para que las hitboxes sigan la animación, usa el mismo índice de pose que al dibujar. Guarda el contexto base más ese índice en INIT y actualízalo cada vez que cambie la pose. En el ejemplo, el sprite empieza en la pose 0 y sin volteo.
; A e índices de 8 bits. X = slot del Normal sprite. LDA.b #!MiSpriteHitboxContext STA !HitmanNormalContextIDLow,x LDA.b #!MiSpriteHitboxContext>>8 STA !HitmanNormalContextIDHigh,x LDA #$00 STA !HitmanNormalFlip,x
Para la pose 1, usa !MiSpriteHitboxContext+1 antes de separar los dos bytes. Al voltear el sprite, actualiza !HitmanNormalFlip,x. Los valores 0, 1, 2 y 3 indican sin volteo, horizontal, vertical y ambos, respectivamente. Si quieres que un desplazamiento se refleje con el volteo, define un pivote para ese eje en el archivo de hitboxes.
Detectar un choque con Mario
Pasa a Hitman el contexto base más la pose actual. !PoseIndex guarda el índice de la pose actual del sprite. Puedes definir tu propia tabla de un byte por slot y actualizarla al cambiar de pose. Si usas Dynamic Xtreme, puedes leer !LastPoseIndex,x en su lugar cuando tenga una pose válida y uses los mismos índices en el archivo de hitboxes. En este ejemplo, el sprite salta hacia arriba cuando choca con Mario.
; A e índices de 8 bits. X = slot del Normal sprite. 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
Con WithoutCallback, Carry queda en 1 si el sprite choca con Mario. Si quieres ejecutar una acción distinta según la caja, asigna .OnPlayerCollision o .OnPlayerNonCollision y llama a !Hitman_Base_PlayerNormalSpriteInteraction. En esa variante, Carry indica si el callback dejó un resultado en !HitmanDefault. Consulta PlayerSpriteInteraction y Crear un callback.
Usar una sola hitbox en un Normal sprite
Si tu sprite usa una sola caja, puedes darle un tamaño y una posición desde el ASM. Guarda el desplazamiento horizontal, el vertical, el ancho y el alto en las tablas del sprite. Luego llama a PlayerNormalSpriteOneHitboxInteraction para comprobar si choca con Mario.
; A e índices de 8 bits. X = slot del Normal sprite. 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 ; Aquí va la respuesta al choque con Mario. .SinChoque
La caja mide 12 × 16 píxeles y empieza 2 píxeles a la derecha y 4 por encima del origen del sprite. Si la caja es fija, guarda los cuatro valores en INIT y deja la llamada en MAIN. Si además quieres que otros sprites usen esa misma caja al consultar la geometría del tuyo, configura HitboxSystem en 02.
Usar una hitbox de 16 bits
Si necesitas una caja más grande o más alejada del origen, usa PlayerNormalSpriteOneLongHitboxInteraction. Guarda los bytes bajo y alto de cada valor. Por ejemplo, esta caja mide 288 × 32 píxeles y empieza 144 píxeles a la izquierda y 4 por encima del origen del sprite.
; A e índices de 8 bits. X = slot del Normal sprite. ; 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 ; Ancho = $0120 (288), alto = $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 ; Aquí va la respuesta al choque con Mario. .SinChoque
Si la caja es fija, guarda los valores en INIT y deja la llamada en MAIN. Para que otros sprites consulten esa misma caja, configura HitboxSystem en 04.
Reaccionar a una interacción vanilla
Supongamos que quieres que una bola de fuego haga saltar al sprite en vez de activar la respuesta del juego. Puedes desactivar esa respuesta y seguir recibiendo el aviso del impacto.
Por ejemplo, añade estas propiedades al JSON del sprite para recibir el evento de bola de fuego de Mario y omitir su respuesta vanilla. Conserva HitboxSystem en la misma lista si ya lo configuraste.
{ "PropertyName": "VanillaEventMask", "Value": "08" },
{ "PropertyName": "VanillaResponseMask", "Value": "77" }
Luego añade "VanillaCallbacks": { "Fireball": "MiSpriteAlRecibirFuego" } como campo del JSON. Guarda MiSpriteAlRecibirFuego.asm en Routines/ dentro de Hitman Tool.
MiSpriteAlRecibirFuego:
; A = evento, X = receptor, Y = slot del Extended sprite.
LDA #$E0
STA !SpriteYSpeed,x
RTL
Si prefieres responder en MAIN, habilita el evento y consulta su bit en !Hitman_Prop_ActionFlag,x. Limpia ese bit cuando termines de procesarlo. Puedes consultar los demás eventos y sus máscaras en Flags y callbacks de eventos.
Adaptar los ejemplos a Cluster sprites y Extended sprites
El mismo MiSprite.hitboxinfo sirve para las tres familias. Usa ;#inchbi en el ASM principal y conserva el cálculo de contexto base más pose. El JSON con HitboxSystem y la directiva ;#inchmprop del ejemplo se usan para Normal sprites.
| En el ejemplo original | Para un Cluster sprite | Para un Extended sprite |
|---|---|---|
| X contiene el slot del Normal sprite. | Pon en X el slot del Cluster sprite. | Pon en X el slot del Extended sprite. |
Guarda la pose en !HitmanNormalContextIDLow,x y !HitmanNormalContextIDHigh,x. |
Usa !HitmanClusterContextIDLow,x y !HitmanClusterContextIDHigh,x. |
Usa !HitmanExtendedContextIDLow,x y !HitmanExtendedContextIDHigh,x.
|
Lee o guarda el volteo en !HitmanNormalFlip,x. |
Usa !HitmanClusterFlip,x. |
Usa !HitmanExtendedFlip,x.
|
Llama a !Hitman_Base_PlayerNormalSpriteInteractionWithoutCallback. |
Llama a !Hitman_Base_PlayerClusterSpriteInteractionWithoutCallback. |
Llama a !Hitman_Base_PlayerExtendedSpriteInteractionWithoutCallback.
|
Deja BCC .SinContacto para saltarte la respuesta cuando no haya choque. Si quieres que el sprite salte como en el ejemplo, usa la tabla de velocidad de su familia. !SpriteYSpeed,x corresponde a los Normal sprites. Si quieres usar callbacks de caja, quita WithoutCallback del nombre de la rutina y lee el resultado en !HitmanDefault.
Si un Extended sprite también debe participar en las comprobaciones de proyectiles contra Normal sprites, configura el modo por número de Extended sprite en ASM/ExtendedSpriteTablesConfig.asm. Para usar sus cajas por pose en ese recorrido, elige el modo $03. Consulta Configurar Extended sprites.
Detectar choques entre sprites desde ASM
Si ya tienes los dos slots, las rutinas de esta tabla te dicen si los sprites chocan. Si chocan, Carry queda en 1 y tu código decide cómo responder.
| Pareja | Llamada y entradas |
|---|---|
| Normal sprite con Normal sprite | JSL !Hitman_Base_CheckNormalPair. Pon un slot normal en X y el otro en Y.
|
| Extended sprite con Normal sprite | JSL !Hitman_Base_CheckExtendedNormalPair. Pon el slot del Normal sprite en X y el del Extended sprite en Y. Configura el modo del Extended sprite antes de probarlo.
|
Comparar cajas de otras familias
AnyNormalSpriteInteractionOneHitbox consulta Normal sprites. Si el receptor es un Cluster sprite o un Extended sprite, usa el formato de caja que ese sprite haya configurado. Las rutinas de esta tabla sirven cuando sabes que los dos sprites usan una caja en RAM. Cada llamada recibe en X el slot de su propia familia.
| Familia | Para llenar HB1 | Para llenar HB2 |
|---|---|---|
| Normal sprite | NormalSpriteOneHitbox1 |
NormalSpriteOneHitbox2
|
| Cluster sprite | ClusterSpriteOneHitbox1 |
ClusterSpriteOneHitbox2
|
| Extended sprite | ExtendedSpriteOneHitbox1 |
ExtendedSpriteOneHitbox2
|
Con las dos cajas listas, llama a JSL !Hitman_Base_CheckContact y lee Carry. Si una caja usa campos de 16 bits, usa la variante LongOneHitbox para cargarla. Si el receptor usa cajas por pose, recórrelas con GetHitbox2 y comprueba cada HB2 contra HB1. Consulta Preparar y comparar cajas.
Bloquear choques entre Normal sprites
Si un sprite lleva a otro, puedes bloquear el choque entre los dos mientras estén juntos. Pon el slot del que carga en X y el del pasajero en Y. Llama a SetSpritePairCollision con A en $00 para bloquear la pareja. Al soltar al pasajero, vuelve a permitir el choque con A en $01.
; A e índices de 8 bits. X = sprite que carga, Y = pasajero. LDA #$00 JSL !Hitman_Base_SetSpritePairCollision ; Al soltarlo, después de confirmar que Y sigue siendo el pasajero. LDA #$01 JSL !Hitman_Base_SetSpritePairCollision
El cambio se aplica en ambos sentidos. Si guardas el slot del pasajero durante varios frames, comprueba que siga ocupado por el mismo sprite antes de volver a usarlo. Hitman restablece las parejas de un slot cuando lo inicializa.
Si quieres bloquear todas las parejas del Normal sprite en X, usa !Hitman_Base_SetSpriteSlotCollision con los mismos valores en A. La máscara afecta al choque vanilla entre Normal sprites. Las consultas manuales como CheckNormalPair siguen detectando si las cajas se cruzan. Consulta SetSpritePairCollision y SetSpriteSlotCollision.
Configurar las tablas de Extended sprites
Edita ASM/ExtendedSpriteTablesConfig.asm en la carpeta de Hitman Tool. Las tablas se generan al instalar el parche. Configuran el choque de un Extended sprite contra Normal sprites. En las macros, el primer argumento es el número de Extended sprite que usa tu recurso. Durante el juego, las rutinas reciben el slot del proyectil.
Elegir la hitbox
Usa %SetExtendedHitboxSystem(numero, modo) para elegir de dónde salen sus cajas.
| Modo | Qué usa Hitman |
|---|---|
$00 |
El Extended sprite queda fuera de este recorrido. |
$01 |
Una caja fija. Define su offset X, offset Y, ancho y alto con %SetExtendedHitbox.
|
$02 |
Una caja en RAM. Guarda offsets con signo y dimensiones en los bytes Low de !HitmanExtendedXOff, !HitmanExtendedYOff, !HitmanExtendedWidth y !HitmanExtendedHeight.
|
$03 |
Las cajas de la pose actual. Guarda el contexto más pose y el volteo como en la tabla de adaptación de esta guía. |
$04 |
Una caja en RAM de 16 bits. Guarda tanto los bytes Low como los High de cada offset y dimensión.
|
Para los modos de RAM, usa el slot del Extended sprite para escribir en las tablas. Si cambias de modo, vuelve a guardar los datos que necesita el nuevo modo, porque parte de la RAM de la pose y la de los offsets se comparte.
Elegir qué pasa al chocar
La geometría y la respuesta se configuran por separado. Con %SetExtendedFireballEvent, puedes elegir !HitmanEventFireball para la respuesta de la bola de fuego de Mario, !HitmanEventYoshiFireball para la de Yoshi o $00 para decidir la respuesta desde tu propio código.
Por ejemplo, si tu proyectil usa el número $20, puedes darle una caja fija de 12 × 16 píxeles y hacer que se comporte como una bola de fuego de Mario.
%SetExtendedHitboxSystem($20, $01) %SetExtendedHitbox($20, $0002, $FFFC, $000C, $0010) %SetExtendedFireballEvent($20, !HitmanEventFireball)
La caja empieza 2 píxeles a la derecha y 4 por encima del origen. En el ASM del proyectil, pon su slot en X y llama a JSL !Hitman_Base_RunVanillaFireballInteraction con A e índices de 8 bits para ejecutar ese recorrido. Si prefieres responder por tu cuenta, usa evento $00 y llama a CheckExtendedNormalPair con el Normal sprite en X y el proyectil en Y.
Las bolas de fuego de Mario ($05) y Yoshi ($11) ya traen su modo y evento configurados. Los demás números empiezan en modo y evento $00. Después de editar la configuración, vuelve a instalar Hitman Tool y los recursos que usan sus defines. Consulta Configurar Extended sprites para ver las tablas RAM y el contrato de cada llamada.
Instalar el sprite
- Añade el sprite a la lista de PIXI.
- Ejecuta Hitman Tool con esa lista.
- Ejecuta PIXI sobre la ROM de salida con la misma lista.
- Si usas Hitman Tool con UberASMTool, vuelve a ejecutar UberASMTool sobre esa misma ROM.