Skip to content

Examples and troubleshooting

# Kivo Appearance settings (setr, so players receive them)
setr fivem-appearance:locale "en"
setr fivem-appearance:automaticFade "1"
# Start the menu first, then the scripts that open it
ensure kivo-appearance
ensure your-multicharacter
ensure your-identity-creator
ensure your-clothing-shop
setr fivem-appearance:locale "fr"

Run restart kivo-appearance. The value fr points to locales/fr.json.

  1. Copy locales/en.json to locales/it.json.

    Terminal window
    cp locales/en.json locales/it.json

    On Windows, copy and rename the file in Explorer.

  2. Translate the values in it.json. Leave the keys alone. For example:

    "modal": {
    "save": {
    "title": "Salva personalizzazione",
    "description": "Vuoi salvare le modifiche?"
    }
    }
  3. Set the language and restart:

    setr fivem-appearance:locale "it"
    restart kivo-appearance

If players should only choose between the male and female freemode models, make peds.json this:

[
"mp_m_freemode_01",
"mp_f_freemode_01"
]

Start the resource that streams the ped, then add its model name to peds.json:

[
"mp_m_freemode_01",
"mp_f_freemode_01",
"my_addon_ped_01"
]

Use the exact spawn name of the model. Without the entry, the menu cannot list the ped and treats a player who uses it as mp_m_freemode_01.

Open tattoos.json and delete every entry whose collection is the one you want to remove. The default file has many entries, so an editor search for the collection name helps.

If you have jq installed, this command writes a copy without any mpbeach_overlays entries. The comparison ignores letter case, because the default file spells some collections with different capitals (mpBeach_overlays and mpbeach_overlays).

Terminal window
jq 'map_values(map(select((.collection | ascii_downcase) != "mpbeach_overlays")))' tattoos.json > tattoos.new.json

Check tattoos.new.json, keep a backup of the original, then replace tattoos.json with it. Each of the six body zones must keep at least one entry.

Example: turn on the manual hair fade input

Section titled “Example: turn on the manual hair fade input”
setr fivem-appearance:automaticFade "0"

The Hair section now shows a Fade input. Its choices come from ZONE_HAIR in tattoos.json, so do not remove that block. The label of the input is headOverlays.hair.fade in the language file.

After you edit peds.json, tattoos.json or a language file, check it before restarting the resource.

  • In a code editor such as Visual Studio Code, errors in a JSON file are underlined.

  • With jq installed, this prints nothing if the file is valid and prints an error if it is not:

    Terminal window
    jq empty peds.json
Mistake Result Fix
Using set instead of setr The language and fade settings are ignored and the defaults apply. Use setr and restart the resource.
A comma after the last entry in a JSON list The file is invalid and the menu cannot load. Remove the extra comma.
Changing or deleting keys in a language file Parts of the menu can stop displaying. Restore the keys from en.json. Change only the values.
Writing pt-br for the file pt-BR.json The language file is not found on a Linux server. Match the file name exactly, including capitals.
Leaving a tattoo zone with an empty list The Tattoos section can break. Keep at least one entry in each of the six body zones.
Reusing a name in tattoos.json Entries with the same name are not told apart. Give every entry a unique name.
Removing mp_m_freemode_01 or mp_f_freemode_01 from peds.json Players cannot select the freemode models, which are the only ones that support inheritance. Put them back.
Adding a ped that no resource streams Selecting it has no effect. Start the resource that streams the model.
Editing files but not restarting Changes do not appear. Run restart kivo-appearance.

Nothing happens after installing the resource

Section titled “Nothing happens after installing the resource”

Kivo Appearance has no command and no key bind. Another script has to open it. Test it with the script on your server that opens an appearance menu. See Integration.

The menu opens but the text or sections are missing

Section titled “The menu opens but the text or sections are missing”

The language file could not be loaded. Check these points in order:

  1. The value of fivem-appearance:locale matches a file name in locales/ (without .json), including capitals.
  2. The file is valid JSON.
  3. All keys from en.json are present in the file.
  4. You wrote the setting with setr.
  • Check that you used setr and not set.
  • Check that the file locales/<value>.json exists.
  • Run restart kivo-appearance. If a player still sees the old language, ask them to reconnect.

Add the model name to peds.json, save and restart the resource. If the ped is listed but selecting it does nothing, the game does not have that model. Start the resource that streams it.

The player’s model switches to the male freemode model

Section titled “The player’s model switches to the male freemode model”

The model they use is not in peds.json. When the menu opens, an unlisted model is treated as mp_m_freemode_01. Add the model to the list.

A tattoo appears in the menu but not on the character

Section titled “A tattoo appears in the menu but not on the character”
  • Check collection, hashMale and hashFemale. They must match the names from the tattoo pack.
  • An empty hash means the tattoo has no version for that sex.
  • Check that the resource that provides an addon tattoo is running.

The Tattoos section is broken or the menu will not open after editing tattoos.json

Section titled “The Tattoos section is broken or the menu will not open after editing tattoos.json”
  • Look for a missing or extra comma, bracket or brace.
  • Check that each of the six body zones still has at least one entry.
  • Restore the file from your backup and repeat the edit in small steps.

There is no Fade input in the Hair section

Section titled “There is no Fade input in the Hair section”

The Fade input only shows when fivem-appearance:automaticFade is 0. With the default value 1 the fade is applied automatically.

The console reports a missing file at start

Section titled “The console reports a missing file at start”

The manifest points to game/dist/index.js and web/dist/index.html. If these are missing, you are using a source copy. Use the release package.

Kivo Appearance does not detect or use a framework. It works the same on ESX, QBCore, QBX and standalone servers. Saving and restoring a character’s appearance is handled by the scripts that open the menu and by your framework, not by this resource.

  • Inheritance (Father, Mother and Mix) is applied only to mp_m_freemode_01 and mp_f_freemode_01.
  • Tattoo overlays are meant for the two freemode models.
  • The default peds.json contains 831 entries. Remove the ones you do not want players to choose, for example the animal models whose names start with a_c_.