Playable character Calibrator

The Playable Character Calibrator is a PGE development tool intended for game creators. It allows the user to define a collision box for each respective frame of a playable character, and also allows developers to calibrate any incorrect positions of the frames in a SMBX64 playable character sprite.

Collision box editing
This feature allows developers to define a collision box for a playable character: a rectangle which will collide with other objects such as blocks, NPCs, other playable characters, etc.

Frame calibration
This feature allows correcting any incorrect frame positions in the source image.

Animation editing
This feature allows the user to adjust the animations of a playable character and test its current calibration settings.

Setting up collision boxes
The first thing you'll need to do to is open 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 enable editing the collision boxes, press the "Edit" button. You should 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 you to select the current frame in an interactive mode. Also you can quickly edit "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 a height of collision box when player do duck.
 * Grab offset X / Y is the offset of carried item. The offset calculating when switched side grab type. The position of carried item calculating relative to player's back (if enabled 'Right Direction' flag - relative to left) and middle of height.
 * Grab type defining, where will be shown carried item: on side of player or over it's head. Note: when enabled top grab type, grab offsets will be ignored. To switch side of 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 switching current frame to using of duck height.
 * Right direction switching current frame to using of duck height.
 * Show carried item enabling on this frame a displaying of carried item corner which showing where will be displayed carried item.
 * 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 your settings on other frames!
 * Enable this frame - if this check box is checked, the selected frame will be drawn onto the hitbox map sprite.


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


 * Save hitbox map as image draws a hitboxes on the 1000x1000 blank sprite which you can use as template for drawing or as helper in manula calibration of the sprite in the Paint.NET / GIMP / Photoshop (or any other raster graphics editor with a layers support).
 * Animator - opens the animation player and editor. This is where you can test your sprite in the animation mode.
 * Image frames calibration is a tool which allows moving the 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
Is a partial ability to use generated calibrations via LunaLUA in the SMBX. To get it working, you must to put saved calibration ini file into your level custom directory, after you must to add into onLoad event in your lunadll.lua file the special line to cause loading of custom calibration settings: Note: when you have multiple calibrations, you must put loading functions for every calibration file! Note: All loaded hitboxes will still while level is running, therefore you need call loading of calibrations ini files once.

Limits for LunaLUA before 0.7.2: You will take effect in the SMBX with those 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 take no effect in the SMBX. Use "image calibration" feature to correct position of drawn image on the frame. Since LunaLUA 0.7.2 GFX Offsets are will work in the SMBX.

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 (SMBX Engine doesn't gives 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 like filename_orig.png). You can use this to create masked GIFs for the SMBX64 standard or you can alternatively use it to save 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 work in the PGE Engine only, it doesn't affects on LunaLUA-SMBX result after applying of the character configuration patch.