Playable character Calibrator

From PGE Wiki
Jump to navigation Jump to search

Playable character Calibrator

Calibrator icon 48.png

PGE Calibrator 2.0 mainwindow.png

Platforms: Windows, Linux, Mac OS X
Latest version: 2.1.1
Coded in: C++
Source code:
Official site:

The Playable Character Calibrator is a PGE development tool intended for game creators. It allows defining a collision box 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

Collision box editing

Collision box 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.

Frame calibration

Frame calibration allows correcting incorrect frame positions in a selected source image.

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

PGE Calibrator 2.0 mainwindow.png
  • 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 which 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.

How to use calibration configs with LunaLua

The character calibrator posseses 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!

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")
    -- ....

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. Since LunaLua 0.7.2 GFX Offsets should also work in the SMBX engine.

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

Calibrator image calibrating.png
  • 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 PGE Engine and does not affect LunaLua-SMBX results after the edited character configuration is applied.

PGE Calibrator 2.0 animator.png