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.
Server settings
Section titled “Server settings”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.
Languages (locales)
Section titled “Languages (locales)”Files included
Section titled “Files included”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.
Choose a language
Section titled “Choose a language”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.
Add a language
Section titled “Add a language”-
Copy
locales/en.jsonto a new file in the same folder, for examplelocales/it.json. -
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.
-
Save the file as UTF-8.
-
Set the language in
server.cfg:setr fivem-appearance:locale "it" -
Run
restart kivo-appearance.
You do not need to edit fxmanifest.lua. The manifest already serves every file that matches locales/*.json.
Rules for language files
Section titled “Rules for language files”- 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 intattoos.json. - You can change any value, including the default English wording. For example, the English text for
modal.save.descriptionis “You will remain ugly”. The English valuesheadOverlays.blush(“Bblush”) andcomponents.scarfAndChains(“Scarf and chais”) contain typos that you can correct in the file. headOverlays.hair.fadeis only shown in the menu whenfivem-appearance:automaticFadeis0.
Locale key reference
Section titled “Locale key reference”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 |
headBlend
Section titled “headBlend”| 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 |
faceFeatures
Section titled “faceFeatures”| 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 |
headOverlays
Section titled “headOverlays”| 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 |
components
Section titled “components”| 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 |
tattoos
Section titled “tattoos”| 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
Section titled “peds.json”peds.json is the list of ped models that appear in the Model dropdown of the menu.
Structure
Section titled “Structure”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.
Add a ped
Section titled “Add a ped”- Open
peds.json. - 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.
- 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.
Remove a ped
Section titled “Remove a ped”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_01andmp_f_freemode_01in 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_01appears 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
Section titled “tattoos.json”tattoos.json is the list of tattoos the menu offers.
Structure
Section titled “Structure”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.
Add a tattoo
Section titled “Add a tattoo”- Open
tattoos.jsonand find the zone array that matches the body area. - Add a new entry at the end of that array, or copy an existing entry and change it.
- Set a
namethat is not used anywhere else in the file. - Set
labelto the text you want players to see. - Set
hashMale,hashFemaleandcollectionto the overlay names provided by your tattoo pack. Leave a hash as""if the tattoo exists for one sex only. - Set
zoneto the same value as the zone key. - 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"}Remove a tattoo
Section titled “Remove a tattoo”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_HAIRholds the hair fade choices. It does not appear in the Tattoos section. It is the list behind the Fade input that shows whenfivem-appearance:automaticFadeis0. Leave it unchanged.- Some default entries have an empty
hashMaleorhashFemale. 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.
