Playable character Calibrator

Playable character Calibrator
Developer:
Platforms:	Windows, Linux, Mac OS X
Initial release:
Latest version:	2.3
End of life:
Coded in:	C++
Code model:
License:
State:
Download:
Source code:
Official site:

The Playable 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.

Main Features

Matrix frame selecting

Hitbox editing

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

Image frame calibration

The Image frame calibration allows you to align the drawn frame 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.

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

• Current frame is the selected frame which you're currently editing. When you change those values, you open other frames to configure.
  • Select frame on matrix allows the user to select the current frame in an interactive mode. You can also quickly edit with "Enable this frame" on all available frames.
• Hitbox calibration contains the the collision box rectangle parameters which define a collision box rectangle for the sprite. The collision box itself is displayed as a green rectangle over the playable character sprite.
  • Width / Height / Height (duck) is the size (in pixels) of the collision box. Your character thus has the possibility of being relatively huge or small. Height (duck) - is the height of the collision box when the player's character ducks.
  • Grab offset X / Y is the offset of a carried item. This offset is calculated for the switched side 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 this 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.
• Copy stores the current collision box values in the clipboard
• Paste applies collision box properties from the clipboard
• Apply to all copies current frame settings to all 100 frames on your sprite. Be careful as it will overwrite settings on other frames!
• 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 test 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/<character-name>/ directory together with the game default sprite files.

Note: Modified animations will not work at SMBX2 and TheXTech. However, you may use them for internal preview at the Calibrator itself. Also, you can't change the carried item location between top and side.

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

Important note: Inside SMBX2 and The X-Tech (since version 1.3.3), calibration INI files will work automatically with no necessary to manually load them via Lua code. Simply put your calibration INI files in your episode, or level custom data folder.

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):

function onLoad()
    -- ....
    -- Arguments: CharacterID, PowerupID, CalibrationFileName
    Level.loadPlayerHitBoxes(3, 4, "peach-4.ini")
    -- CharacterID: 1-Mario, 2-Luigi, 3-Peach, 4-Toad, 5-Link
    -- PowerupID: 1-Small, 2-Super(normal size), 3-FirePower, 4-RacoonMagic, 5-TanookiSuit, 6-HammerSuit, 7-IcePower
    -- ....
    -- Note, the old LunaLua can handle this action with the "loadHitboxes" function name with the same arguments!
end

Note: When you have multiple calibrations, you must specify the loading functions for every calibration file!

function onLoad()
    -- ....
    Level.loadPlayerHitBoxes(3, 1, "peach-1.ini")
    Level.loadPlayerHitBoxes(3, 2, "peach-2.ini")
    Level.loadPlayerHitBoxes(3, 3, "peach-3.ini")
    Level.loadPlayerHitBoxes(3, 4, "peach-4.ini")
    Level.loadPlayerHitBoxes(3, 5, "peach-5.ini")
    Level.loadPlayerHitBoxes(3, 6, "peach-6.ini")
    Level.loadPlayerHitBoxes(3, 7, "peach-7.ini")
    -- ....
end

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)

Important note: Since LunaLua 0.7.2 GFX Offsets should also work in the SMBX engine.

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.
• Matrix - 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.

Note: Edited animation will only work in the Moondust Engine and does not affect LunaLua-SMBX and TheXTech results after the edited character configuration is applied.