Skip to main content

Troubleshooting

This section covers common problems, synchronization issues, migration problems, and debugging workflows for XDEV Appearance.

The system was designed to remain modular and compatibility-focused, but appearance systems naturally involve many moving parts:

  • peds
  • overlays
  • tattoos
  • clothing
  • synchronization
  • framework integration

Tattoos Not Appearing

Problem​

Tattoos save correctly but do not appear on the ped.

Common Causes​

Typical causes:

non-freemode ped
overlay rebuild failure
appearance cache conflict
external appearance resource conflict

Verify:

model == mp_m_freemode_01
model == mp_f_freemode_01

because GTA tattoos only work properly on freemode peds.

Refresh Workflow​

The resource includes tattoo rebuild workflows internally.

If tattoos disappear after:

menu closing
ped reload
resource restart

verify that the refresh logic is running correctly.

Tattoos Disappear After External Menus

Problem​

External appearance menus remove or overwrite tattoos.

Cause​

Some appearance resources internally cache appearance states and overwrite current overlays after menu closing.

This is especially common during:

appearance rebuilds
cached menu states
legacy synchronization

Recommendation​

Use:

reload workflows
tattoo rebuilds
appearance synchronization

after external menu interactions.

Props Not Loading

Problem​

Hats, glasses, watches, or accessories disappear.

Common Causes​

Typical causes:

invalid drawable
invalid texture
custom ped incompatibility
prop clearing

Debugging​

Verify:

drawable ~= -1

unless intentionally removing props.

Components Not Applying

Problem​

Clothing changes save but do not appear.

Common Causes​

Typical causes:

invalid drawable
invalid texture
custom ped incompatibility
component mismatch

Verify:

drawable exists
texture exists
ped supports component

before applying values.

Custom Ped Problems

Problem​

Addon/custom peds behave incorrectly.

Cause​

Custom peds may not support:

overlays
face blend
props
components
tattoos

like freemode peds do.

Recommendation​

Use:

peddata

for addon/custom ped synchronization workflows.

Overlay Problems

Problem​

Makeup, blush, lipstick, or beard colors appear incorrect.

Cause​

Different GTA overlays internally use different color palettes.

Example:

palette 1
palette 2

Some overlays may visually appear different depending on palette behavior.

Moles / Freckles Not Using Colors

Explanation​

Moles/freckles typically do NOT use hair-style color palettes like:

beard
eyebrows
makeup

Usually only:

style
opacity

are relevant.

Appearance Not Saving

Problem​

Changes preview correctly but disappear after reconnect.

Common Causes​

Typical causes:

database save failure
invalid JSON
SQL mismatch
conversion failure

Verify:

playerskins table
JSON encoding
SQL columns
converter logic

SQL Errors

Problem​

oxmysql query errors
invalid syntax

Common Cause​

Tables or JSON structures may not match expected format.

Example issue:

Lua table inserted directly into SQL without JSON encoding

Always encode structured data before saving:

json.encode(data)

Appearance Resets After Restart

Problem​

Player appearance resets after reconnect or resource restart.

Common Causes​

Typical causes:

missing synchronization
reload conflict
external appearance resource
invalid save structure

Verify:

skin saves correctly
tattoos rebuild correctly
ped reload triggers
appearance synchronization runs

Commands Not Working

Problem​

Commands do not execute.

Verify:

QBCore installed
permission valid
command enabled

inside:

Config.System.commands

Menu Inputs Stuck

Problem​

Enter key or hotkeys trigger unexpectedly after opening menus.

Cause​

Keys may still be considered pressed during UI focus switching.

Use configurable delays:

Config.UI.HotkeyDelay

and validate key release states before accepting interactions.

Tattoo Opacity Looks Wrong

Problem​

Opacity values appear too strong or too weak.

Cause​

Some systems use:

0 -> 100

while others use:

0.0 -> 1.0

The resource internally normalizes values during rebuild workflows.

Migration Issues

Problem​

Old appearance systems conflict with XDEV Appearance.

Recommended process:

1. Disable old reload systems
2. Disable old tattoo rebuilds
3. Verify SQL structure
4. Verify compatibility events
5. Test synchronization

Debug Recommendation

When debugging appearance issues:

test freemode first
test without external resources
test synchronization separately

before debugging addon/custom ped behavior.

Developer Notes

Appearance systems are heavily affected by:

ped limitations
GTA natives
external resources
cached states

Most visual bugs are synchronization problems rather than database problems.

Final Notes

XDEV Appearance was intentionally designed around:

modularity
compatibility
rebuild reliability
conversion support

to reduce long-term appearance desync issues across large roleplay servers.