Examples and troubleshooting
Example: full server.cfg block
Section titled “Example: full server.cfg block”# 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 itensure kivo-appearanceensure your-multicharacterensure your-identity-creatorensure your-clothing-shopExample: switch the menu to French
Section titled “Example: switch the menu to French”setr fivem-appearance:locale "fr"Run restart kivo-appearance. The value fr points to locales/fr.json.
Example: add an Italian language file
Section titled “Example: add an Italian language file”-
Copy
locales/en.jsontolocales/it.json.Terminal window cp locales/en.json locales/it.jsonOn Windows, copy and rename the file in Explorer.
-
Translate the values in
it.json. Leave the keys alone. For example:"modal": {"save": {"title": "Salva personalizzazione","description": "Vuoi salvare le modifiche?"}} -
Set the language and restart:
setr fivem-appearance:locale "it"restart kivo-appearance
Example: freemode models only
Section titled “Example: freemode models only”If players should only choose between the male and female freemode models, make peds.json this:
[ "mp_m_freemode_01", "mp_f_freemode_01"]Example: add an addon ped
Section titled “Example: add an addon ped”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.
Example: remove a whole tattoo collection
Section titled “Example: remove a whole tattoo collection”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).
jq 'map_values(map(select((.collection | ascii_downcase) != "mpbeach_overlays")))' tattoos.json > tattoos.new.jsonCheck 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.
Check that a JSON file is valid
Section titled “Check that a JSON file is valid”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
jqinstalled, this prints nothing if the file is valid and prints an error if it is not:Terminal window jq empty peds.json
Common mistakes
Section titled “Common mistakes”| 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. |
Troubleshooting
Section titled “Troubleshooting”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:
- The value of
fivem-appearance:localematches a file name inlocales/(without.json), including capitals. - The file is valid JSON.
- All keys from
en.jsonare present in the file. - You wrote the setting with
setr.
The language did not change
Section titled “The language did not change”- Check that you used
setrand notset. - Check that the file
locales/<value>.jsonexists. - Run
restart kivo-appearance. If a player still sees the old language, ask them to reconnect.
My ped is not in the Model list
Section titled “My ped is not in the Model list”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,hashMaleandhashFemale. 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.
Framework notes
Section titled “Framework notes”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.
Compatibility notes
Section titled “Compatibility notes”- Inheritance (Father, Mother and Mix) is applied only to
mp_m_freemode_01andmp_f_freemode_01. - Tattoo overlays are meant for the two freemode models.
- The default
peds.jsoncontains 831 entries. Remove the ones you do not want players to choose, for example the animal models whose names start witha_c_.
