Skin Pack Guide

JUE13

Skins in Thunder Engine games

Welcome to a guide about creating your own player skin and using it in Mario Forever Community Edition (MFCE).
This guide will describe all the nuances about creating your own character for this game (and for Thunder Engine in general).

Important

Before moving on, please note the following:

A player skin is a customized audio-visual appearance of a character you're playing (Mario or Luigi), which means custom textures (sprites), custom voice lines, and custom sound effects can be applied to a player skin.
This means that you can play as either Mario or Luigi regardless of what skin you currently have.
A player skin cannot have modified physics or alter the game in any way other than the character you're playing. (Some global sound effects are an exception.)
All images should be in PNG format, and all audio files should be in OGG Vorbis format (.ogg).
Sprites are positioned centered on the player, which means that increasing the image height past the normal 64 pixels would grow the skin in all 4 directions. You can avoid that by balancing out the increased height, adding some empty space below your textures.
You can use the Skin Editor to have a better visual representation of the skin you're editing, but it is just a GUI helper tool and is not required.
In v2.0, a new menu in Tweaks has been added: the Skin Setup. It can greatly help with testing the skin functionalities.
- Alternatively, to test the skin quickly, enable the Console tweak (available after beating the game or using the Konami code in tweaks menu), go to Save Room, enter reloadskins to the console, and update your power-up.
- - Note that reloadskins does NOT immediately apply the player suit changes to your character if used mid-game, and a manual power state update is required (can also be done with the power command, e.g. power super).

If you have trouble loading an old skin in a newer version of the game and need to update it, refer to section "Updating the Skin for MFCE v2.0" of this post.

Installing a Skin

Go to the directory where the game is installed, and open a folder named skins. If you've downloaded a custom skin, extract the contents of the archive inside that folder. (Note that every skin must be in its own folder.)

The folder name inside the skins folder becomes a name of the skin in the skin selector.
This folder will be referenced in this guide as a skin root folder.

The game should now detect the skin and add a selection to the "SKIN PACK" option in the Tweaks menu.
It does a check for the skin folder once on game launch and every time you go back from the tweaks menu (but can be triggered mid-play using the reloadskins console command).

If upon selecting the skin and exiting the tweaks menu you did not receive any errors, you have installed the skin correctly and, if you do not intend to edit the skin further, you can close the guide now.

Setting Up a Custom Name

To change the name in Heads-Up Display (HUD) and cutscenes, open your skin in the Skin Editor and click "Options".

The name can not be longer than 15 characters. Non-latin characters are not supported and might be displayed as garbage, although numbers and some special characters are allowed.

Additionally, you can customize the story mode text when referring to the character you're playing.

Custom Player Suit Animations

The main purpose of a player skin is to be able to change animations of the player suits.
A player suit is what you transform to after obtaining/losing a power-up.

For starters, each folder inside the skin root folder is regarded as a player suit. Hence, such folders will be referenced in this guide as player suit folders.

There are 8 suits in total currently available in Thunder Engine, each of them can be modified using a player skin:

small,
super,
fireball,
beetroot,
green_lui (for both Green Lui & Red Mar),
boomerang,
iceball,
frog.

Each folder requires a skin_settings.tres file to be present, which contains SpriteFrames settings for the animation of the suit.

Omitting a texture, a player suit folder or a skin_settings.tres file, will cause the game to load a default character texture/animation set (Mario or Luigi).
To make sure that there are no problems with your skin, use the Check for Errors option in the Skin Setup, located in the tweaks menu.

Please note that if you omit a lot of the textures (or all of them), there might be problems with loading default animations if you were/are playing as Luigi (some suits may display as Mario, others as Luigi).

Animation List

Creating custom player suit animations requires you to be familiar with how each animation is used in the game, so here's a list of them and a brief explanation of where it is used:

appear: Animation that plays for 1 second when the player transforms into the current suit.
attack: Attacking while on the ground (e.g. launching a fireball). If the suit provides no way to attack, it goes unused for that suit.
attack_air: Attacking while mid-air. Can be enabled using a skin tweak. Same principle as attack.
back: Unused in MFCE (yet). Supposed to be for warping between doors.
climb: Climbing a vine like in Super Mario Bros. 3. Note that Version 2.0.0+ makes it a proper animation, instead of flipping sprites on a hard-coded timer, like it was before.
crouch: Crouching down. For the frog suit, this is not used. For small, it can only be seen briefly with the Crouch Jumping tweak enabled.
default: Standing still.
fall: Being in mid-air while moving down to the ground, or falling. Can be replaced by jump with a skin tweak.
grab: Grabbing something underneath.
hold_crouch: Crouching while holding an item.
hold_default: Standing still while holding an item.
hold_fall: Falling while holding an item. Can be replaced by hold_jump with a skin tweak.
hold_jump: Jumping while holding an item.
hold_walk: Walking on the ground while holding an item.
hold_swim: Swimming while holding an item.
jump: Being in mid-air while moving away from the ground, or jumping.
kick: Throwing a held item. Also used for kicking shells if "Kick Ground Animation" skin tweak is enabled.
skid: Turning around, or skidding. Can be enabled using a tweak.
slide: Sliding down a slope.
swim: Swimming underwater.
swim_down: Frog suit only: Swimming downwards.
swim_up: Frog suit only: Swimming upwards.
walk: Moving on the ground.
warp: Warping between pipes. Can be disabled using a skin tweak.
win: Win pose, used in the ending cutscene.

Skin Tweak Animation List

Additionally, if the respective skin tweaks are enabled, the following animations become available (These have to be added into skin_settings.tres, too):

"Separate Run Animation":

p_run: Running at max speed.
p_jump: Jumping while running at max speed.
p_fall: Falling after jumping while running at max speed. If Fall Animation is disabled, replaced with p_jump.
hold_p_run: Same as p_run, but while holding an item.
hold_p_jump: Same as p_jump, but while holding an item.
hold_p_fall: Same as p_fall, but while holding an item.

"Look Up Animation":

look_up: Standing still and pressing up.
hold_look_up: Same as look_up, but while holding an item. Note that while looking up does sometimes make the item go straight up when kicked, it has nothing to do with the animation itself.

"Idle Animation":

idle: Standing still for Idle Animation After Sec amount of time, which is 10 by default. Interrupted by doing literally anything.

Custom Animation Images

Each animation for the player suit should have its own image in a PNG format, with animation name in the "Animation List" section as its file name (e.g. default.png). If you need multiple frames in the animation, make a spritesheet in that image.

It is highly recommended to not provide huge images (over 2048 pixels), as that may negatively impact the resource usage of the game, and some graphics cards may not support such dimensions.

Now, let's set up our animation in the next section.

Skin Settings

As previously stated, each animation should contain its own skin_settings.tres. This file can be used to modify playing speed, set up sprite regions, and choose whether it should be looped.

It is best to modify the animations using the Skin Editor provided with the game. It is basically a GUI tool for editing such files. But if you don't feel comfortable using it, you can keep reading.

If you are creating a new skin, you can copy a skin_settings.tres file from the bundled "revamped mario" skin, or use the Skin Editor to create one. Now, let's examine what it contains.

Open up skin_settings.tres with a Notepad or any other text editing program. Inside, at the beginning of the file, you may see some header text. It is not important. (Be aware that in versions v1.1 and below, the header is required for the skin to work properly, which may cause security issues if downloaded from an untrusted source.)

Setting Up the Animations

Now the important part. There are three lists (called Dictionaries), going one after another, which contains settings data for all animations for the player suit. Make sure to follow the JSON format inside of these lists! Commas are important!

animation_speeds list is used to set speed for the animations, where FPS is used as a unit, e.g. setting it to 60 will play the animation in 60 FPS with game speed set to 1X. It can be in a float format (e.g. 1.25) and must be in a range between 0 and 120.
animation_regions list is the most important one. This is where you set coordinates and dimensions for each frame in the animation. Each value is represented as an array of Rect2 in format Rect2(x, y, w, h), where x and y are an offset/position of the frame in the image starting from top-left corner and going rightwards and downwards accordingly, and w and h are dimensions of the frame in pixels.
- For example, if we assume that the image has a resolution of 96x64, "default": [Rect2(0, 0, 48, 64), Rect2(48, 0, 48, 64)] will make a 2-frame animation for a default (standing still) animation, where the first frame is a region going from the top-left corner down to coordinate (48, 64), and the second frame is a region going right after the first one to the right, going down to coordinate (96, 64), since it has the same dimensions.
animation_loops list is used to tell if the animation is looped or not, which is self-explanatory. For some animations, this does not matter, and can be either true or false.
animation_durations list is used to make the frame last longer/shorter. 1.0 is the default speed.

Additionally, if you need to specify what frame should the animation go to after looping, you can either use the Skin Setup menu in MFCE, or edit the suit_tweaks.json file, under "loop_frame_offsets".
Note that the values are 0-based. Negative values are ignored and will loop from the beginning.

Custom Misc Textures

The following textures are not a part of a player suit, but can be changed using Player Skins as well:

death.png is what is shown upon player death. It cannot have any animations.
selector.png is a selector image in main menus (Mario's/Luigi's head). Unlike the default selector, a selector with skins can only be a static image.
map_icon.png is an image in the corner of a map screen. It is correctly displayed with dimensions 118x88.
particle.png is used when the corresponding property is enabled in the Skin Setup menu (suit_tweaks.json file).

All custom miscellaneous textures should be in PNG format inside the skin root folder.
Any other image in PNG format located in the skin root folder is loaded into memory, but will be completely unused.

It is highly recommended to not provide huge images (over 2 MB), as that may negatively impact the resource usage of the game.

Custom Global Sounds

Using the Player Skin system, some sound effects can be modified independently from the suit.

All custom global sounds should be in OGG Vorbis format (.ogg) inside the folder named _global_sounds.

You can observe and test all the available global sounds in the Sound Test menu, located in Tweaks > Skin Setup (MFCE only). Note that added sounds are not updated immediately and require a re-enter to the tweaks menu, to trigger the skins update.

All sounds can have up to 10 variations played at random. Accepted file name format is either sound.ogg or sound_#.ogg, where sound is the sound name, and # is a number from 0 to 9.

oh_no.ogg voice line is played when the player encounters an enemy on a map or falls into a Lava Run section.
fall.ogg voice line is played when the player falls into a Lava Run section.

More sound effects to customize can be found in Sound Test menu from Skin Setup.

Omitting any of these will load a default global sound for the current character (Mario or Luigi).

Custom Suit Sounds

There is a number of custom sounds that can be changed independently of each suit. These, too, can have up to 10 variations. Here's a list of them:

"jump": Jumping sound.
"swim": Swimming sound.
"hurt": Taking damage and reverting to Super/Small suit.
"powerup": Grabbing a power-up and transforming into a new suit.
"powerup_no_transform": Grabbing a power-up without transforming into a new suit.
"pipe_in": Entering warp pipes.
"pipe_out": Exiting warp pipes.
"look_up": Played when pressing Up movement key while standing.
"attack": Played when throwing projectiles. Only for suits that have this ability.
"skid": Skidding. Can be disabled using a gameplay tweak. Delay between sounds can be customized in the Suit Tweaks.
"grab": Grabbing something.
"kick": Kicking something.
"ice_slide": Sliding on a slippery surface (like ice).
"jump_small": Frog suit only: small jumping sounds when hopping on land.

Suit Sounds should be located in their own sounds folder in the player suit folder, e.g. revamped mario/beetroot/sounds. If needed, duplicate the sounds for each suit.

Like with Custom Global Sounds, Suit Sounds should be in OGG Vorbis format (.ogg).

Notes:

hurt.ogg only applies when the player takes damage, and is independent from the warping sound.
Custom death.ogg is only played in areas where the default SMW death music is played. Other instances of the death sound effect (e.g. The Lost Map, World of Stupidity, etc.) are left intact.
- This can be changed through Global Skin Tweaks.

Updating the Skin for MFCE v2.0

Version 2.0 of Mario Forever: Community Edition changed the way the sounds are loaded, which was required for better organization.

All custom voice lines that were previously available in v1.1 should now be located at directory _global_sounds inside the skin root folder. However, custom sound effects are now suit-dependent, and should be located in their own sounds folder in the player suit folder, e.g. revamped mario/beetroot/sounds.

If you need assistance...

You can ask your question in this thread.