esx_skin

esx_skin is the ESX Legacy character creator. It opens a Svelte NUI on top of skinchanger, lets players edit their ped, and stores the result in users.skin. Use its server exports when your own resource (clothing shop, barber, outfit wardrobe) needs to read or save a player's appearance.

OverviewCopy Anchor Link

How saving worksCopy Anchor Link

1.16 moved all skin storage to the server and hardened it:

• Every skin is validated against Config.SkinFields. Unknown keys, non-integers or out-of-range values are rejected.
• Clients can only save through esx_skin:save while they have an edit session. Sessions are created on the first login of a player without a skin, by the /skin command, and by the BeginSkinEdit export. A session expires after Config.SkinEditSessionTTL and is consumed by a successful save.
• Saves are rate limited per player (Config.SkinSaveCooldown) and queued per identifier.
• Shops should save on the server with a scope (clothes, barber, outfit) so the player cannot change fields the shop does not sell.

ConfigurationCopy Anchor Link

Scopes are built in config.lua:

Server exportsCopy Anchor Link

SaveSkinCopy Anchor Link

exports.esx_skin:SaveSkin(playerId, skin, callback, scope)

Returns false when the request was rejected immediately, otherwise true (queued). With barber, only barber fields are copied onto the stored skin. With clothes or outfit, any change outside the scope is rejected with appearance_scope_mismatch:<field>.

xLib.callback.register('myshop:buyHaircut', function(source, skin)
    local p = promise.new()
    exports.esx_skin:SaveSkin(source, skin, function(success, reason)
        p:resolve({ success = success, reason = reason })
    end, 'barber')
    return Citizen.Await(p)
end)

SaveOutfitCopy Anchor Link

exports.esx_skin:SaveOutfit(playerId, clothes, callback)

local policeUniform = { tshirt_1 = 58, tshirt_2 = 0, torso_1 = 55, torso_2 = 0, arms = 41, pants_1 = 25, pants_2 = 0, shoes_1 = 25, shoes_2 = 0 }

exports.esx_skin:SaveOutfit(source, policeUniform, function(saved, skin)
    if saved then
        TriggerClientEvent('skinchanger:loadSkin', source, skin)
    end
end)

GetSkinCopy Anchor Link

local skin, ready = exports.esx_skin:GetSkin(playerId)

Returns the stored skin table (or nil) and ready, which is false when the player is not loaded or the database read failed. Uses the cache when possible.

BeginSkinEditCopy Anchor Link

local ok = exports.esx_skin:BeginSkinEdit(playerId)

Opens an edit session so the client may save its full skin once through the saveable menu. Returns false if the player is not loaded or a save is in flight.

RegisterCommand('plasticsurgery', function(source)
    if exports.esx_skin:BeginSkinEdit(source) then
        TriggerClientEvent('esx_skin:openSaveableMenu', source)
    end
end, true)

ValidateSkinCopy Anchor Link

local clean = exports.esx_skin:ValidateSkin(skin)

Returns a decoded copy of the skin if it passes Config.SkinFields validation, otherwise nil.

SetBackpackCapacityCopy Anchor Link

local ok = exports.esx_skin:SetBackpackCapacity(playerId, bag)

Stores authorizedBackpack in the player's metadata and sets max weight to ESX MaxWeight + Config.BackpackWeight[bag]. Returns false for unknown bags.

Server callbackCopy Anchor Link

esx_skin:getPlayerSkin returns the stored skin and the job outfits:

xLib.callback('esx_skin:getPlayerSkin', false, function(skin, jobSkin)
    if skin then
        TriggerEvent('skinchanger:loadSkin', skin)
    end
    -- jobSkin = { skin_male = ..., skin_female = ... } from the player's job grade
end)

It is also registered as a compat callback, so ESX.TriggerServerCallback('esx_skin:getPlayerSkin', cb) keeps working.

Client eventsCopy Anchor Link

All menu events take Lua functions as arguments, so trigger them locally with TriggerEvent (or from the server without callbacks).

submitCb(data, menu) and cancelCb(data, menu) receive data.current (focused element), data.elements, and a menu handle with close(), update(_, element) and refresh(). When you cancel, the last skin is restored automatically.

-- shop: only show clothes, let the server decide whether to save
TriggerEvent('esx_skin:openRestrictedMenu', function(data, menu)
    menu.close()
    TriggerEvent('skinchanger:getSkin', function(skin)
        TriggerServerEvent('myshop:buyClothes', skin) -- server calls SaveSkin(..., 'clothes')
    end)
end, function(data, menu)
    menu.close()
end, { 'tshirt_1', 'tshirt_2', 'torso_1', 'torso_2', 'arms', 'pants_1', 'pants_2', 'shoes_1', 'shoes_2' })

CommandsCopy Anchor Link

Common issuesCopy Anchor Link

• "Your appearance could not be saved". Check the F8 console for [esx_skin] Appearance save failed: <reason>. edit_session_missing means no BeginSkinEdit was called; invalid_appearance:... means a field is unknown or out of range; rate_limited means saves come too fast.
• Old shop scripts stop saving. Scripts that open esx_skin:openSaveableMenu or fire esx_skin:save from the client without a server-side BeginSkinEdit no longer work. Move the save to the server and use SaveSkin with a scope.
• Backpack weight does not apply. With Config.AllowClothingBackpackCapacity = false you must call SetBackpackCapacity. It never applies when es_extended uses ox_inventory or another custom inventory.
• esx_skin:setWeight does nothing. It is kept as an empty handler for compatibility.

RelatedCopy Anchor Link

• skinchanger
• esx_identity
• esx_multicharacter
• Callbacks guide

Frequently asked questions