Playable character Calibrator

The Character Calibrator is a Moondust development tool intended for game creators. It allows defining a hitbox for the frames of a playable character and also allows users to calibrate incorrect frame positions in an SMBX64 playable character sprite.

Hitbox editing
Hitbox editing allows users to define a collision box for a playable character: a rectangle that will define a physical body that will collide with other objects such as blocks, NPCs, other playable characters, etc.

Sprite editor
A small built-in utility (previously known as "Image frame calibration") that allows you to adjust position of drawn frames on the image itself without modification of the hitbox properties. Use this if you want to tune your sprite for using with the vanilla engine where is impossible to override hitbox properties, or use this to just be sure all your frames were aligned properly in their cells. Since the version 3.0, this tool allows you to apply small edits on the frame itself as via the graphical editor, and allows you to open the selected frame via external graphical editor for further modifications, and load it back when it gets saved via external graphical editor.

Animation editing
Whether it be to adjust a playable character's animations or test its current calibration settings, either is possible with the character calibrator.

Setting up collision boxes
The first step is opening the playable character sprite. This has to be a 1000x1000 pixel image either in the GIF format- with masks or the transparent PNG format (both formats are supported). When running the program for the very first time, you'll be asked for a sprite image.

When you open a sprite image one of the first things you'll see is the main window. If the sprite has not been previously edited (meaning the configuration bank does not contain a INI file for the sprite's filename), all collision boxes will have a size of 100x100 pixels and zero offsets.

To edit collision boxes, press the "Edit" button. Take note that the sprite is used in SMBX wherever the SMBX64 standard has persistence collision boxes for playable characters.

GUI explanation



 * Wall - Shows an example of surface (wall, floor, ceiling, etc) that should help you to adjust hitbox visually.
 * Reset scroll - Resets the scroll to the center of screen.
 * BG Color - Changes the background colour to any other.
 * Compat: - Allows you to specify the compatibility format of the configuration files. This is important because different applications has different behaviour on the saved data.


 * Select current frame is the selected frame which you're currently editing. When you change those values, you open other frames to configure.
 * Show sprite map... allows the user to select the current frame in an interactive mode. You can also quickly enable or disable the frame by right-clicking every frame on the map.
 * Hitbox setup contains the the hitbox rectangle parameters which defines a physical size for the character, and offset for the the selected frame. The hitbox itself is displayed as a green rectangle over the playable character sprite.
 * Width / Height / Height (duck) is the size (in pixels) of the hitbox. Gets applied globally for the whole sprite. Your character thus has the possibility of being relatively huge or small. Height (duck) - is the height of the hitbox when the player's character ducks.
 * Grab offset X / Y is the offset of a carried item. This offset is different depending on the switched grab type. The position of a carried item is calculated relative to the left edge of a character (If the 'Right Direction' flag is enabled, the opposite direction) and the center of its height.
 * Grab type specifies where a carried item will be shown: on the side of a player or over its head. Note: when top grab type is enabled, grab offsets will be ignored. To switch the side of a grabbed item use the "Right Direction flag".
 * GFX Offsets of frame is the position of the top-left corner of the collision box, relative to left-top corner of currently selected frame.
 * Is Duck frame switches the current frame to use the specified duck height.
 * Right direction switches the current frame to use the specified duck height.
 * Show carried item Enabling this on a frame will show where a displayed carried item corner, which will show where the carried item will be displayed.
 * Mount riding Enabling this on a frame will show the example of the "horse", and will mean that this frame is supposed to be used for a riding on a pet.
 * Copy stores the current collision box values in the clipboard.
 * Paste applies collision box properties from the clipboard.
 * Enable this frame - if this checkbox is ticked, the selected frame will be drawn onto the hitbox map sprite.


 * Save config saves the current sprite settings in the INI file.
 * Open sprite opens a sprite to edit its collision boxes.


 * Save hitbox map as image draws a hitbox on a 1000x1000 blank sprite which can be used as a template for drawing or something else that can be used to assist manual calibration of a sprite with software such as Paint.NET / GIMP / Photoshop (or any other raster graphics editor which supports layers).
 * Animator - opens the animation player and editor. This is where you can preview your sprite in animation mode.
 * Image frames calibration is a tool that allows moving drawn frames in the image. Unlike the main window, over here you'll be correcting the image position to fit them into the collision box.

Using calibrations with TheXTech and SMBX2
TheXTech since version 1.3.3 and SMBX2 has the native support for the calibration files. Simply save them together with your custom sprite at your episode or the level directory. The game will automatically load them when starting the level. At TheXTech it's also possible to override the hitbox settings globally: you should save the calibration file at the graphics// directory together with the game default sprite files.

Using calibrations with SMBX-38A
The SMBX-38A since the 1.4.5 version has the support for the calibration settings at its level files. At the SMBX-38A of 1.4.4 version, there was a hidden easter egg that gives you that allows you to open the interface that allows you to change the player calibration. However, since the 1.4.5 version, this feature has been removed, but the ability to add setup via level files was kept. PGE Calibrator has the ability to import and export calibration settings through SMBX-38A level files. You should load the sprite you want to calibrate, then, open the "Tools" menu and select the "Import data from SMBX-38A level..." to select the level file from which you want to import existing calibration settings. Please do save the calibration in INI format to have the ability of the quick resume of your work and keep all Calibrator-specific features like customized preview animations. Once you want to add your calibration settings into your SMBX-38A level, you should open the "Tools" menu and select the "Export data into SMBX-38A level..." to select the level file you want to patch with your changed calibration settings.

Using calibrations with old LunaLua-SMBX
The character calibrator possesses a (somewhat partial) ability to make use of generated calibrations in SMBX via LunaLua. To get it working, you'll have to place the saved calibration ini file into a level's custom directory. Followed by adding an onLoad event in your lunadll.lua file (the special line being there in order to load custom calibration settings): Note: When you have multiple calibrations, you must specify the loading functions for every calibration file! Note: All loaded hitboxes persist while a level is running, so you'll only need to call the loading of calibrations ini files once.

Limits for LunaLua before 0.7.2: Will take effect in SMBX with these values only:
 * Width
 * Height
 * Duck Height
 * Grab-offset X (Relative offset of carried item)
 * Grab-offset Y (Relative offset of carried item)

Other values like GFX Offset will have no effect in SMBX. Use the "image calibration" feature for adjusting a drawn image's positions in a frame.

Correcting the sprite's frame position
This unique feature allows moving frames in a sprite to fit them into an existing hit box without modification of the gfx-offsets. This is required for the SMBX64 standard where hit boxes are strictly fixed (The SMBX Engine does not possess the ability to modify hitbox preferences without LunaLua).


 * Current frame is the frame which you are currently editing. When you change these values, it will change the current frame that is being configured.
 * Image calibration - is the process of positioning a frame over the image.
 * Offset X/Y adjusts the frame's position in relation to the collision box.
 * Crop width/height- crops the sprite to a rectangular area. You can use this to fix junk pixels at the bottom or right sides.
 * Show sprite map... - allows you to select the current frame in an interactive mode.
 * Save image overwrites the original image (a backup image will be created with an extension such as filename_orig.png). This can be used to create masked GIFs for the SMBX64 standard or alternatively for saving an image in the PNG format.

Animating the character
This is where you'll be able to playback the animations of a playable character while simultaneously being able to edit it.