LooksMenu Tint API

These are instructions for advanced modders, it's not a mod you can install and use!

LooksMenu by Expired comes with a feature for injecting tints into the character creation, such as makeup, dirt, scars or tattoos.
This means you don't have to edit the race record any longer to add new tints, which causes conflicts with any other mod that does so (the reason LooksMenu Customization Compendium was created).

Tints are for the head only - body overlays have their own system and make use of a different API.
Here on this page you will find information and samples for making use of the LooksMenu Tint API yourself.

The API uses JSON formatted files with lots of properties, so it's definitely for advanced modders or people that are used to JSON.
The texture formats AND texture sizes are very important, make sure to read those sections as well!

How to add tints?

In the files section here, you can find a little sample mod to look at for reference.
If you need further reference for how to design your textures to work well as tints, see how LooksMenu Customization Compendium does it for their mod.

To use the LooksMenu Tint API, all you need is a dummy ESP plugin (without any forms), the categories.json and templates.json files that define your tints and the actual DDS texture files for it.

Said categories.json and templates.json file have to be in the following folder, depending on the name of your ESP plugin file:

• Fallout 4\Data\F4SE\Plugins\F4EE\Tints\YOUR_DUMMY_PLUGIN.esp\categories.json
• Fallout 4\Data\F4SE\Plugins\F4EE\Tints\YOUR_DUMMY_PLUGIN.esp\templates.json
  

IMPORTANT:
Tints have a global index that NEEDS TO BE UNIQUE across the entire save game.
So, not just does each tint in your mod have to have its own unique "Id" (see JSON format below), but also this ID has to be unique across all mods on the Nexus.

The vanilla game's tint indices go from 0 to 1959. The maximum index possible is 65535.
With a regular plugin mod installed, such as LooksMenu Customization Compendium, your game will use up roughly 1000 more indices.

So, it's best to make your mod use a specific range that's further along and not used by any other mod or tint injecting mod yet.

Some good range examples, you get the drill:

• 8000-9000
• 25000-26000
• 42000-43000
  

How to set up the JSON files?

These have a lot of properties for you to change, so looking at all the options may be a little intimidating at first.
It's best you open the JSON files that come with the sample mod in a text editor while looking at the description here.

categories.json

Entries
-- Name
----- Name of the category as it appears in-game. Can be translated with a translation text file.
-- Type
----- Default is "Category".
-- Id
----- Numeric index of the category. For a custom category, this has to be unique for all mods (between 8 and 255)!
-- Gender
----- The gender the category should be for.
----- 0 = Male
----- 1 = Female
----- 2 = Both
Race
-- The race the entries specified in the entry list are for. Default should be "HumanRace".
-- You can have multiple "Entries" lists in one file, each for a different race.


templates.json

Entries
-- Name
----- Name of the tint as it appears in-game. Can be translated with a translation text file.
-- Type
----- Choose one of the following types. Default is "TextureSet".
----- Mask: Has "Texture" and "BlendOp" settings. No diffuse/normal/specular maps.
----- Palette: Has "Texture" and "Colors" settings. No normal/specular maps.
----- TextureSet: Allows for "Diffuse", "Normal", "Specular", "BlendOp" and "Default" settings.
-- Category
----- Assigns your tint to a vanilla category number. If you want to assign a custom category, use only "FixedCategory" instead!
----- If you want to use a vanilla category, choose one of the following numbers:
-------- 1: Brows for male, Makeup for female
-------- 2: Markings
-------- 3: Blemishes
-------- 4: Damage
-------- 5: Grime
-------- 6: Face Tattoos
-------- 7: Face Paint
-- FixedCategory
----- Assigns your tint to one of your custom categories. If you want to assign a vanilla category, use only "Category" instead!
----- Enter the name of your custom category as defined in your categories.json file.
-- Slot
----- You can choose one of the following slots for a tint. Default is "FaceDetail".
----- ForeheadMask, EyesMask, NoseMask, EarsMask, CheeksMask, MouthMask, NeckMask
----- LipColor, CheekColor, Eyeliner, EyeSocketUpper, EyeSocketLower, SkinTone, Paint, LaughLines
----- CheekColorLower, Nose, Chin, Neck, Forehead, Dirt, Scar, FaceDetail, Brows
-- Gender
----- The gender the tint be appear for.
----- 0 = Male
----- 1 = Female
----- 2 = Both
-- Id
----- Numeric index of the tint. Used for save game files. The maximum index is 65535.
----- This has to be unique GLOBALLY (for all mods), not just within your mod!
----- This means you can't use any IDs that other tint mods or the vanilla game already use.
----- It's best to start out at a higher number such as 20000, just make sure not to collide with another mod.
-- Flags
----- ChargenDetail: Default for tints that can be blended.
----- OnOff: The tint can only be toggled completely on or off.
----- TakesSkinTone: The tint adjusts to the used skin color. Often used for scars or burns.
-- BlendOp
----- Defines how to blend the tint to the face. These work the same as the blend modes in Photoshop.
----- Only works for the "TextureSet" and "Mask" tint types (or the color list for "Palette").
----- Choose one of the following:
-------- Default
-------- Multiply
-------- Overlay
-------- SoftLight
-------- HardLight
-- Texture
----- The path to the texture file.
----- Only works for the "Palette" and "Mask" tint types. Use diffuse, normal and specular for the "TextureSet" type instead.
-- Diffuse
----- The path to the diffuse map of the tint.
----- Only works for the "TextureSet" tint type.
----- Example: actors\\character\\Character Assets\\FaceDetails\\Sample_1_d.dds
-- Normal
----- The path to the normal map of the tint.
----- Only works for the "TextureSet" tint type.
----- Example: actors\\character\\Character Assets\\FaceDetails\\Sample_1_n.dds
-- Specular
----- The path to the specular map of the tint.
----- Only works for the "TextureSet" tint type.
----- Example: actors\\character\\Character Assets\\FaceDetails\\Sample_1_s.dds
-- Default (optional)
----- Only works for the "TextureSet" tint type.
----- The amount the tint starts at. Goes from 0.0 to 1.0.
-- Colors
----- Only works for the "Palette" tint type. It is an array of colors that are available for the palette.
----- Id: Numeric index of the color.
----- Form: The form ID of the color (in Fallout4.esm or your own plugin), e.g. "Fallout4.esm|0E6E16".
----- Alpha: Between 0.0 and 1.0 for transparency of the color.
----- BlendOp (optional): Defines how the color should blend in.
Race
-- The race the entries specified in the entry list are for. Default should be "HumanRace".
-- You can have multiple "Entries" lists in one file, each for a different race.

Texture Formats

You can save these with the Intel Photoshop plugin or the FileType Plus plugin for paint.NET.
If you can't save BC1, BC3 or BC5 texture formats, you have to resort to DXT1/DXT5 and ATI2 in older plugins for different software.
These are just different names for the same format.

These have to match up, or the texture files might not work properly or cause issues.

• The main head diffuse texture needs to be in the BC3 (DXT5) format.
• Tint masks need to be in the BC1 (DXT1) format (white for the affected area and otherwise black).
• Face detail textures such as eyebrows or blemishes need to be in the BC3 (DXT5) format.
• Eye diffuse textures need to be in the BC3 (DXT5) format.
• Color palette maps need to be in the BC1 (DXT1) format.
• Normal maps need to be in the BC5 (ATI2) format.
• Specular maps need to be in the BC5 (ATI2) format.
  

Texture Sizes

These are very important for the tints to work. Make sure to read carefully.
Depending on the head texture you might even need to make multiple versions.

The tint's texture size has to match up with that of the head's respective texture (diffuse, normal or specular).
So this changes depending on vanilla textures, HD DLC or 2K face mods.

• All diffuse, normal map or mask textures HAVE TO BE exactly 1024x1024 large for vanilla head texture sizes to work.
• All specular maps HAVE TO BE exactly 512x512 large for vanilla head texture sizes to work.
• If you're using an HD face mod that changes the head's diffuse/normal texture to be 2048x2048 large, then your tints HAVE TO HAVE the same size as well.
• If you're using an HD face mod that changes the head's specular maps to be 1024x1024 large, then your tints HAVE TO HAVE the same size as well.
• If you're using the official HD DLC by Bethesda that changes the head's specular maps to be 1024x1024 large, then your tints HAVE TO HAVE the same size as well.