3. Player Cosmetics

Cosmetic Mods

Cosmetics in the game are made from multiple interlocking parts. However, MOMI simplifies the process of creating cosmetic mods using a system that involves creating a .toml file under a /momi/cosmetics/ folder in your mod directory.

Here are a few things you should know before starting your own cosmetic mod. You will need:

• At least a basic understanding of how lut files work, and maybe extensive knowledge depending on what your mod will do
• a basic understanding of TOML files, and software to modify them in (Notepad++, Sublime, or Visual Studio Code work just fine). For more information, see the Getting Started page.

With those prerequisites out of the way, this page will show you how to create a new player cosmetic item.

Basic cosmetic knowledge

When creating new cosmetics you'll need to define your them in a TOML file (or multiple TOML files) inside the momi/cosmetics folder of your mod. The TOML file should be composed of something along these lines:

[lryn_celine_summer_skirt]
name = "Celine's summer skirt"
ui_slot = "bottom"
ui_sub_category = "skirt"

lut = "images/lryn_celine_summer_skirt_lut.png"

cosmetic_sprites = { waist = "images/lryn_celine_summer_skirt_waist.png" }
ui_sprites = {
	ui = "images/lryn_celine_summer_skirt_ui.png",
	outline = "images/lryn_celine_summer_skirt_outline.png"
}

Each cosmetic (represented by one TOML table) is made up of:

• name: The name that the cosmetic displays with in customization and in stores.
• ui_slot: The cosmetic slot that is used, e.g. hair, top, face_gear, etc. (see below)
• ui_sub_category: The header under which your cosmetic is displayed in character creation, e.g. dress, short_sleeve, etc. (see below)
• lut: This is the file that defines the possible colors of your cosmetic in-game, aka the palettes. More information can be found here.
• cosmetic_sprites: This is a list of all the animations that make up the cosmetic. (see below)
• ui_sprites: These are the pieces that make up the icons that appear in the player's inventory and in the character customization screen.

Additional options

[lryn_celine_summer_skirt]
name = "Celine's summer skirt"
# ...
lut_sprite = "spr_vanilla_item_lut"
# ...
default_unlocked = true
price_override = 100

• lut_sprite: If your item uses an LUT from the vanilla files, like for example the LUT that is shared for most hair, spr_player_hair_lut, you can specify that here.
• default_unlocked: Whether this item is unlocked by default when a player starts a new game. This will not make new items automatically be available to players when they load their game after installing a mod, only when starting a new game.
• price_override: The default price of cosmetic items in FoM is 500. If you would like a different price, you can specify that here.

UI Slot and Subcategory

All player cosmetic items can be organized by which UI Slot they use and the subcategories inside that category. The list of slots and their subcategories are as follows:

UI Slot	Subcategories
back	backpacks, capes, back_gear_misc
facial_hair	facial_hair
top	sleeveless, short_sleeve, long_sleeve, jackets, dress, robe, suit, wedding_dress, wedding_suit, top_misc
eyes	eyes
face_gear	face_accessory, ear_accessory, glasses
hair	medium_hair, short_hair, long_hair
head_gear	crown, hair_accessory, hat, helmet, head_gear_wedding, head_gear_misc
bottom	pants, shorts, skirt, bottom_misc
feet	boots, sandals, shoes, shoes_wedding, feet_misc

Animation Files (cosmetic_sprite files)

Each cosmetic must have at least one of the following animation files, which is the sheet of frames that MOMI will import into Fields of Mistria and will be used in the game. A cosmetic can define multiple categories of animation files, but the only categories of animation files that can be defined are:

• torso
• waist
• hair_mid
• hair_back
• sleeve_left
• sleeve_right
• legs
• back_gear
• facial_hair
• eyes
• face_gear
• head_gear
• head_gear_back
• hair_front (this technically exists, but is currently unused)

These pieces are layered with each other to create full cosmetic pieces. So for example, most pants' cosmetic sprites are made up of a waist file and a legs file.

UI Sprites

In most cases, cosmetics need two components, ui and outline. The ui image is what is displayed in the player's inventory when they are about to unlock the cosmetic, and the outline file is a white outline of the cosmetic. Here's an example:

Here is the UI item icon:

And here's its outline:

Special Cases: Face Cosmetics

There are a few extra steps to consider when creating any cosmetic that displays previews with the player's current skin tone. This mostly applies to facial cosmetics, meaning all hair, eyes, facial hair, "face gear" like glasses, and in a couple cases, masks, which use the head_gear slot. This is particularly useful for cases where contrast and visibility against player skin tone are important, like the blush cosmetic.

Note

These steps are not exclusive to these cosmetic slots, they're just where they tend to show up in the vanilla game. If you, for example, want to use these methods to have the player's head for reference underneath a hat, or their body underneath a dress, it should be possible with this.

To allow the skin tone to display behind the preview of your cosmetic, we'll need to provide a few additional files: asset and body. In these cases, the ui and outline files are replaced by merged and merged_outline.

You might have noticed that while hair sold by Vera displays on a grey-toned mannequin-like head in her shop and in your inventory, once it's "learned" and in character customization it displays with your skin tone. This is because they, like our special case cosmetics, use asset and body files. When the game needs to display the cosmetic with skin tone preview, it layers the asset sprite (using the item's LUT) on top of the body sprite (using the skin tone LUT).

In this example, I'm adding a new pair of glasses to the game. My TOML file inside of momi/cosmetics/ looks like this:

[round_glasses]
name = "Round Glasses"
ui_slot = "face_gear"
ui_sub_category = "glasses"

lut = "images/luts/spr_player_face_gear_round_glasses_lut.png"

cosmetic_sprites = { face_gear = "images/spr_player_face_gear_round_glasses.png" }
ui_sprites = {
    asset = "images/ui_icons/spr_ui_item_wearable_face_gear_round_glasses_asset.png",
    body = "images/ui_icons/spr_ui_item_wearable_face_gear_round_glasses_body.png",
    merged = "images/ui_icons/spr_ui_item_wearable_face_gear_round_glasses_merged.png",
    merged_outline = "images/ui_icons/spr_ui_item_wearable_face_gear_round_glasses_merged_outline.png"
}

default_unlocked = true

My merged file looks like this:

My merged_outline file looks like this:

My asset file looks like this (may be difficult to see on dark mode):

And my body file looks like this: Most body files currently in the game are the same. That bright pink color is what the skin tone LUT will replace with the player's current skin tone.