• Introduction
• Common box types
• Usage
• MAME-rr vs. FBA-rr
• Background removal
• Color customization
• Supported games
• sf2-hitboxes.lua
• marvel-hitboxes.lua
• cps2-hitboxes.lua
• beatemup-hitboxes.lua
• kof-hitboxes.lua
• garou-hitboxes.lua
• cps3-hitboxes.lua

Introduction

Although the sprites on screen seem to interact directly with one another, 2D fighting games and other action games usually use unseen hitboxes to determine whether attacks connect or miss. These boxes can be made visible in MAME-rr and FBA-rr through the use of Lua scripting. This information can help players improve their game and help people who don't play the games to appreciate how they work.

Also see combovid for in-depth discussions.

Common box types

Some game engines have specialized kinds of boxes, but here are the types that are found in most games.

Vulnerability and Attack

The attack box must touch the opponent's vulnerability for the attack to connect. Characters may have one or several vulnerability boxes for different areas of the sprite, but most fighting games only allow attacks to have one attack box at a time.

Projectile Vulnerability and Attack

If an opposing projectile's attack touches a projectile vulnerability box, the projectiles negate one another. In some games, projectiles don't have designated vulnerability areas and negate by touching attack boxes.

Push

A pushbox cannot occupy the same space as another pushbox. Attempting to press them together will cause characters to push one another. Jumping attacks that extend below and behind the pushbox allow for easier crossup attacks. Some moves cause pushboxes to disappear, allowing the character to pass through the opponent. In primitive games like Fatal Fury 1 & 2, vulnerability boxes also perform the function of pushboxes.

Throw and Throwable

A throwbox must touch the opponent's throwable box for the throw attempt to succeed. Throws are generally active for only one frame. Some games don't have designated throwable boxes and reuse the pushbox for this purpose.

Usage

These scripts work with either parent and clone ROMs. Download the script file, load the appropriate ROM, launch a Lua window (ctrl-L by default), then browse for and run the .lua file. The ROM must be up to date for MAME-rr or FBA-rr, and may be out of date with respect to mainline MAME.

The current versions can be downloaded from the SVN repository. Changes are trackable on the update page or by subscribing to the update feed.

The behavior can be modified by pressing Lua hotkeys. (The key bindings are assigned in the emulator settings.)

1. Hide or reveal all the graphics on the screen to show only the boxes. Default off.
2. Hide or reveal axis markers for characters and other objects. Default on.
3. Hide or reveal the centers of individual boxes. Default off.
4. Hide or reveal pushboxes. Default on.
5. Hide or reveal throwability boxes. Default off.

The best way to get images is with the emulator's screenshot function (F12 by default).

MAME-rr vs. FBA-rr

Both emulators can show boxes, but they differ in usability and accuracy.

MAME-rr advantages:

• doesn't crash so much on loading savestates or loading new ROMs
• doesn't demand so much CPU when displaying partially transparent boxes
• more powerful cheat engine means a more reliable background removal procedure
• no frame sync problems for CPS2 games
• can use debugger breakpoints for games on any system, but this requires extra effort in coding and usage

FBA-rr advantages:

• much better performance for CPS3 games
• built-in Lua breakpoints for NeoGeo, CPS1 and CPS2 systems
• This means only FBA can properly show throwboxes for the sf2 and cps2 scripts, and is required for the garou script.

Background removal

The game backgrounds can make the boxes harder to see. This can be offset by increasing the fill opacity of the boxes, but this in turn makes the character sprites harder to see. The ideal solution is to remove the backgrounds entirely. One way to do this is with "cheat" codes that prevent the background and HUD from being displayed by the game.

Here is how to get the codes working in MAME:

1. Download the latest official cheat pack.
2. Extract cheat.zip from the downloaded archive to the base MAME folder.
3. Run the ROM in MAME, find Cheats from the main menu, and set the code to On.

Other information:

• The codes for some games need to be activated before the start of the match to remove the HUD.
• The codes are designed to only affect the game while a match is in progress.
• The effects of some codes are not fully reversible.
• Most of the codes patch ROM data and will only work with parent sets, not clones.
• The background color for NeoGeo games can be adjusted by editing the color value in the codes.
• It possible to convert codes for some, not all, games to work in FBA.

Screenshots or videos captured with the backgrounds removed can easily be processed to make the background color transparent. In order for this to work with hitboxes, the fill opacity must be set to zero and the border opacity should be maximum. A shortcut to do this is to set no_alpha in the globals at the top of the script to true.

local globals = {
	axis_color           = 0xFFFFFFFF,
	blank_color          = 0xFFFFFFFF,
	axis_size            = 12,
	mini_axis_size       = 2,
	blank_screen         = false,
	draw_axis            = true,
	draw_mini_axis       = false,
	draw_pushboxes       = true,
	draw_throwable_boxes = false,
	no_alpha             = true, --fill = 0x00, outline = 0xFF for all box types
}

Color customization

Colors can be changed by editing the box values at the top of the script.

	      ["vulnerability"] = {color = 0x7777FF, fill = 0x40, outline = 0xFF},
	             ["attack"] = {color = 0xFF0000, fill = 0x40, outline = 0xFF},
	["proj. vulnerability"] = {color = 0x00FFFF, fill = 0x40, outline = 0xFF},
	       ["proj. attack"] = {color = 0xFF66FF, fill = 0x40, outline = 0xFF},
	               ["push"] = {color = 0x00FF00, fill = 0x20, outline = 0xFF},
	              ["throw"] = {color = 0xFFFF00, fill = 0x40, outline = 0xFF},
	          ["throwable"] = {color = 0xF0F0F0, fill = 0x20, outline = 0xFF},

The color numbers are RGB values, and the fill and outline determine the opacity of the inside and outside of the box. 0xFF is fully opaque and 0x00 is invisible.

The default colors are subject to change in future versions.

Supported games

sf2-hitboxes.lua

All of the Street Fighter II games.

Notes

weak box

Attacks that hit a weakbox deal double damage. Weak boxes only appear in Street Fighter II: World Warrior and in WW mode of Hyper Street Fighter 2. They are colored the same as throwboxes by default.

air throwable box

This box is susceptible to air throws but not ground throws. The opposite is true for the normal throwable box.

marvel-hitboxes.lua

All of the Marvel/Versus games on the CPS-2 system.

Notes

FBA is needed to show the exact frames when throws are active and when pushboxes are inactive. In MAME, only the potential throw range is viewable, and pushboxes tend to flicker or not disappear when inactive. However, boxes sometimes update a frame early or late in FBA.

potential throw box

It's possible to show where the box would appear if a throw were attempted. This box type is fully transparent (invisible) by default and can be shown by increasing its opacity value. This is unnecessary since FBA can show the real throw attempts.

cps2-hitboxes.lua

All of the remaining CPS-2 fighting games, including the Street Fighter Alpha and Darkstalkers series.

Notes

FBA is required to show all throws in: sfa, sfa2, sfz2al, vsav, vhunt2, vsav2, cybots, and sgemf. It is also needed in dstlk and nwarr to show air throws and to make ground throws be attempted at long range. However, boxes sometimes update a frame early or late in FBA.

axis throw box

Air throws in sfa, sfa2 & sfz2al, and special ranged throws in nwarr grab at the opponent's axis instead of a box.

beatemup-hitboxes.lua

Selected beat-em-up games on the CPS-2 system.

Notes

Non-character objects are colored as projectiles. Pushboxes are not used.

kof-hitboxes.lua

Most of the King of Fighters games on the NeoGeo MVS system.

Notes

All throwboxes in NeoGeo games show up one frame late. Not enough frames pass between the box computations and the graphics update to correct this.

FBA is needed to show throwboxes in kof94 and kof95. The the only axis throw boxes for this script are the special throws in those two games.

guard box

Attacks that hit a guardbox will be blocked, either by manually blocking, by an autoguard move, or by a special counter move.

garou-hitboxes.lua

The Garou Densetsu/Fatal Fury NeoGeo series.

Notes

This script mostly doesn't work MAME due to extensive use of breakpoints. FBA is required.

The backgrounds can be removed using the script itself by setting no_background in the globals section to true. This must be done before the match start to work.

There are no throwability or projectile vulnerability boxes.

cps3-hitboxes.lua

The CPS3 games, excluding the Jojo titles.

Notes

This script was originally translated to Lua from the mameserver project. The 3rd Strike code was also helped by the work of crystal cube

For now, the only way to show normal throwboxes in redearth/warzard is with the MAME-rr debugger. Run MAME from the command line with the -debug switch:

> mame redearth -debug -lua cps3-hitboxes.lua

Or to avoid using the command line, edit mame-rr.ini so that debug is 1:

#
# CORE DEBUGGING OPTIONS
#
log                       0
verbose                   0
update_in_pause           0
debug                     1
debugscript               

The debugger starts by halting execution of the game and the UI. Press F5 to release control. The script will print the BPs to the Lua console:

Copy and paste the line over to the debugger console and hit enter. Now all supported box types will appear correctly.

The game may glitch up when the command is entered but this only happens once. Before quitting or unloading the ROM, enter bpc into the debugger console to clear any installed breaks, or else MAME will crash.

Errors or inconsistencies can be reported by leaving a comment to this page.