Skip to content

Configuration

Kivo Appearance has no config.lua. You configure it in four places:

Place What it controls
server.cfg settings Menu language and automatic hair fade
locales/*.json Every piece of menu text
peds.json Ped models players can pick
tattoos.json Tattoos players can pick

After you edit any of these files, run restart kivo-appearance. If a player still sees old data, ask them to reconnect.

Set these in server.cfg above the ensure line of the resource. Use setr so the value reaches players.

setr fivem-appearance:locale "en"
setr fivem-appearance:automaticFade "1"
Setting Default Valid values What it does
fivem-appearance:locale en The name of a file in locales/, without .json (for example fr, pt-BR) Chooses the language file used for all menu text.
fivem-appearance:automaticFade 1 1 or 0 1: the matching hair fade is applied automatically when the player picks a hair style, and the Fade input is hidden. 0: the Hair section shows a Fade input and the player chooses the fade by hand.

When fivem-appearance:automaticFade is 0, the Fade input steps through the ZONE_HAIR list in tattoos.json. Keep that list in the file if you turn automatic fade off. See tattoos.json.

cs.json, de.json, en.json, es-ES.json, fa-IR.json, fr.json and pt-BR.json. All seven files contain the same 97 keys.

Set fivem-appearance:locale to the file name without .json:

setr fivem-appearance:locale "fr"

The value is used directly as the file name locales/<value>.json. It is case sensitive on a Linux server, so pt-br does not match pt-BR.json.

  1. Copy locales/en.json to a new file in the same folder, for example locales/it.json.

  2. Open the new file and translate the values (the text on the right of each colon). Do not change the keys (the text on the left) and do not change the nesting.

  3. Save the file as UTF-8.

  4. Set the language in server.cfg:

    setr fivem-appearance:locale "it"
  5. Run restart kivo-appearance.

You do not need to edit fxmanifest.lua. The manifest already serves every file that matches locales/*.json.

  • Keep every key. A missing key can stop a part of the menu from displaying.
  • The file must be valid JSON: straight double quotes, commas between entries, no comma after the last entry in a block.
  • The six tattoos.items.ZONE_* keys must keep their names. They match the zone names in tattoos.json.
  • You can change any value, including the default English wording. For example, the English text for modal.save.description is “You will remain ugly”. The English values headOverlays.blush (“Bblush”) and components.scarfAndChains (“Scarf and chais”) contain typos that you can correct in the file.
  • headOverlays.hair.fade is only shown in the menu when fivem-appearance:automaticFade is 0.

The tables show each key and its English text from en.json.

Confirmation dialogs shown when the player saves or exits.

Key English text
modal.save.title Save customization
modal.save.description You will remain ugly
modal.exit.title Exit customization
modal.exit.description No changes will be saved
modal.accept Yes
modal.decline No
Key English text
ped.title Ped
ped.model Model
Key English text
headBlend.title Inheritance
headBlend.shape.title Face
headBlend.shape.firstOption Father
headBlend.shape.secondOption Mother
headBlend.shape.mix Mix
headBlend.skin.title Skin
headBlend.skin.firstOption Father
headBlend.skin.secondOption Mother
headBlend.skin.mix Mix
Key English text
faceFeatures.title Face Features
faceFeatures.nose.title Nose
faceFeatures.nose.width Width
faceFeatures.nose.height Height
faceFeatures.nose.size Size
faceFeatures.nose.boneHeight Bone height
faceFeatures.nose.boneTwist Bone twist
faceFeatures.nose.peakHeight Peak height
faceFeatures.eyebrows.title Eyebrows
faceFeatures.eyebrows.height Height
faceFeatures.eyebrows.depth Depth
faceFeatures.cheeks.title Cheeks
faceFeatures.cheeks.boneHeight Bone height
faceFeatures.cheeks.boneWidth Bone width
faceFeatures.cheeks.width Width
faceFeatures.eyesAndMouth.title Eyes and Mouth
faceFeatures.eyesAndMouth.eyesOpening Eyes opening
faceFeatures.eyesAndMouth.lipsThickness Lip thickness
faceFeatures.jaw.title Jaw
faceFeatures.jaw.width Width
faceFeatures.jaw.size Size
faceFeatures.chin.title Chin
faceFeatures.chin.lowering Lowering
faceFeatures.chin.length Length
faceFeatures.chin.size Size
faceFeatures.chin.hole Hole size
faceFeatures.neck.title Neck
faceFeatures.neck.thickness Thickness
Key English text
headOverlays.title Appearance
headOverlays.hair.title Hair
headOverlays.hair.style Style
headOverlays.hair.color Color
headOverlays.hair.highlight Highlight
headOverlays.hair.fade Fade
headOverlays.opacity Opacity
headOverlays.style Style
headOverlays.color Color
headOverlays.blemishes Blemishes
headOverlays.beard Beard
headOverlays.eyebrows Eyebrows
headOverlays.ageing Ageing
headOverlays.makeUp Make up
headOverlays.blush Bblush
headOverlays.complexion Complexion
headOverlays.sunDamage Sun damage
headOverlays.lipstick Lipstick
headOverlays.moleAndFreckles Mole and Freckles
headOverlays.chestHair Chest hair
headOverlays.bodyBlemishes Body blemishes
headOverlays.eyeColor Eye color
Key English text
components.title Clothes
components.drawable Drawable
components.texture Texture
components.mask Mask
components.upperBody Hands
components.lowerBody Legs
components.bags Bags and parachute
components.shoes Shoes
components.scarfAndChains Scarf and chais
components.shirt Shirt
components.bodyArmor Body armor
components.decals Decals
components.jackets Jackets
Key English text
props.title Props
props.drawable Drawable
props.texture Texture
props.hats Hats and helmets
props.glasses Glasses
props.ear Ear
props.watches Watches
props.bracelets Bracelets
Key English text
tattoos.title Tattoos
tattoos.items.ZONE_TORSO Torso
tattoos.items.ZONE_HEAD Head
tattoos.items.ZONE_LEFT_ARM Left arm
tattoos.items.ZONE_RIGHT_ARM Right arm
tattoos.items.ZONE_LEFT_LEG Left leg
tattoos.items.ZONE_RIGHT_LEG Right leg
tattoos.apply Apply
tattoos.delete Delete

peds.json is the list of ped models that appear in the Model dropdown of the menu.

The file is a JSON array of strings. Each string is one ped model name. The list shows the models in the same order as the file.

[
"mp_m_freemode_01",
"mp_f_freemode_01",
"player_zero",
"a_m_y_beach_01"
]

The default file has 831 entries. It includes the two freemode models (mp_m_freemode_01 and mp_f_freemode_01), the story characters (player_zero, player_one, player_two), animal models (names starting with a_c_) and many NPC models.

  1. Open peds.json.
  2. Add the model name as a new string. Use the exact spawn name, in lower case. Put a comma after every entry except the last one.
  3. Save and run restart kivo-appearance.

For an addon or custom ped, the resource that streams the model must be running. Selecting a model that the game does not have has no effect.

Delete the line of the model you want to remove. Keep the commas correct: the last entry must not have a comma after it.

  • Keep mp_m_freemode_01 and mp_f_freemode_01 in the list. Inheritance is only applied to these two models.
  • If a player is using a ped that is not in the list when the menu opens, the menu treats the current model as mp_m_freemode_01. Add every ped model your server uses, including addon peds.
  • g_f_importexport_01 appears twice in the default file. Remove one of the two lines if you do not want it listed twice.
  • If the file is not valid JSON, the menu cannot load. Check for a missing comma, an extra comma after the last entry, or a missing quote.

tattoos.json is the list of tattoos the menu offers.

The file is a JSON object. Each key is a body zone. Each value is an array of tattoo entries for that zone.

Zone key Menu title (English) Default entries
ZONE_TORSO Torso 283
ZONE_HEAD Head 59
ZONE_LEFT_ARM Left arm 93
ZONE_RIGHT_ARM Right arm 104
ZONE_LEFT_LEG Left leg 49
ZONE_RIGHT_LEG Right leg 40
ZONE_HAIR Not shown in the Tattoos section 126

Each tattoo entry has six fields:

Field Type What it is
name string A unique identifier, for example TAT_AR_000. It must not be used twice anywhere in the file.
label string The text shown in the tattoo dropdown.
hashMale string The overlay name used when the player’s model is mp_m_freemode_01. An empty string "" means the tattoo has no male version.
hashFemale string The overlay name used when the player’s model is mp_f_freemode_01. An empty string "" means the tattoo has no female version.
zone string The zone of the entry. It must be the same as the zone key it sits under.
collection string The name of the overlay collection that contains the tattoo.

A real entry from the default file:

{
"name": "TAT_AR_000",
"label": "Turbulence",
"hashMale": "MP_Airraces_Tattoo_000_M",
"hashFemale": "MP_Airraces_Tattoo_000_F",
"zone": "ZONE_TORSO",
"collection": "mpairraces_overlays"
}

In the menu, each body zone has a dropdown that lists the label of every entry in file order. Choosing an entry previews it. The button then reads Apply, or Delete if that tattoo is already on the player.

  1. Open tattoos.json and find the zone array that matches the body area.
  2. Add a new entry at the end of that array, or copy an existing entry and change it.
  3. Set a name that is not used anywhere else in the file.
  4. Set label to the text you want players to see.
  5. Set hashMale, hashFemale and collection to the overlay names provided by your tattoo pack. Leave a hash as "" if the tattoo exists for one sex only.
  6. Set zone to the same value as the zone key.
  7. Save and run restart kivo-appearance.

Placeholder example. Replace the names with the ones from your tattoo pack:

{
"name": "MYPACK_TORSO_001",
"label": "My Tattoo",
"hashMale": "MyPack_Tattoo_001_M",
"hashFemale": "MyPack_Tattoo_001_F",
"zone": "ZONE_TORSO",
"collection": "mypack_overlays"
}

Delete the whole entry, from its opening { to its closing }, and the comma that separates it from its neighbour. Removing an entry only removes the option from the menu.

  • Keep at least one entry in each of the six body zones. An empty zone list can break the Tattoos section of the menu.
  • Do not add new zone keys and do not rename the existing ones. The language files only contain titles for the six body zones shown in the table.
  • ZONE_HAIR holds the hair fade choices. It does not appear in the Tattoos section. It is the list behind the Fade input that shows when fivem-appearance:automaticFade is 0. Leave it unchanged.
  • Some default entries have an empty hashMale or hashFemale. These are tattoos that exist for one sex only.
  • Tattoo overlays are meant for the two freemode models. Keep the male and female hash of each entry matched to those two models.
  • If the file is not valid JSON, the menu cannot load.