Client

Open the menu, read a ped, set a ped. All from Lua.

Illenium Appearance Remaster

Pricing, previews and purchase options on the store.

For server events and callbacks see Server.

startPlayerCustomization(callback, config, hooks)

Starts the player customization process, allowing players to modify their appearance. The callback is triggered once customization is complete, returning appearance data or nil if canceled.

---@param callback function Receives `appearance` data if saved or `nil` if canceled
---@param config table Configuration for customization options
---@param hooks? { canOpen?: fun(): boolean, canSave?: fun(appearance: table): boolean, string?, takeCamera?: fun(appearance: table?, camera: number): boolean? }
---@return boolean opened `false` when `canOpen` refused
exports['illenium-appearance']:startPlayerCustomization(function(appearance)
    if appearance then
        print('Customization saved!')
    else
        print('Customization canceled.')
    end
end, {
    ped = true,
    headBlend = true,
    faceFeatures = true,
    headOverlays = true,
    components = true,
    props = true,
    allowExit = true,
    tattoos = true
})

Optional hooks only apply to that menu. canOpen returning false stops it from opening and the callback never runs. canSave returning false, reason keeps the menu open and shows the reason. takeCamera returning true hands you the camera instead of destroying it. A hook that errors is logged, canOpen then refuses and canSave lets the save through.

exports['illenium-appearance']:startPlayerCustomization(function(appearance)
    -- appearance, or nil when cancelled
end, { components = true, props = true }, {
    canOpen = function()
        return creatingCharacter
    end,
    canSave = function(appearance)
        return appearance.hair.style ~= 0, "Pick a hairstyle first."
    end,
    takeCamera = function(appearance, camera)
        MyCamera.takeOver(camera)
        return true
    end,
})

cancelPlayerCustomization()

Close the open menu like the cancel button. The look reverts and the callback gets nil.

---@return boolean cancelled `false` when no menu is open
local cancelled = exports['illenium-appearance']:cancelPlayerCustomization()

getInterfaceVisibilityState()

Which parts of the UI are open.

---@return { app: boolean, loadingScreen: boolean, exportPanel: boolean }
local visibility = exports['illenium-appearance']:getInterfaceVisibilityState()
if visibility.app then
    print('Menu is open')
end

Read a ped

getPedModel(ped)

Retrieves the model name associated with a player's entity. Returns nil for models missing from the ped list.

---@param ped number Entity ID of the pedestrian
---@return string? Model name
local pedModel = exports['illenium-appearance']:getPedModel(ped)
print(pedModel)  -- e.g. "mp_m_freemode_01"

getPedComponents(ped)

Retrieves the clothing and accessory components of a pedestrian's model.

---@param ped number Entity ID
---@return table Components data
local components = exports['illenium-appearance']:getPedComponents(ped)
print(components[1].drawable)

getPedProps(ped)

Retrieves the props (hats, glasses, etc.) for a pedestrian.

---@param ped number Entity ID
---@return table Props data
local props = exports['illenium-appearance']:getPedProps(ped)
print(props[1].prop_id)

getPedHeadBlend(ped)

Retrieves the head blend data (shape, skin mix, etc.) for a pedestrian.

---@param ped number Entity ID
---@return table Head blend data
local headBlend = exports['illenium-appearance']:getPedHeadBlend(ped)
print(headBlend.shapeFirst)

getPedFaceFeatures(ped)

Retrieves the face feature data (facial traits) for a pedestrian.

---@param ped number Entity ID
---@return table Face features
local faceFeatures = exports['illenium-appearance']:getPedFaceFeatures(ped)
print(faceFeatures['noseWidth'])

getPedHeadOverlays(ped)

Retrieves the head overlays (makeup, scars, etc.) for a pedestrian.

---@param ped number Entity ID
---@return table Head overlays
local headOverlays = exports['illenium-appearance']:getPedHeadOverlays(ped)
print(headOverlays['blush'].opacity)

getPedHair(ped)

Retrieves the hair data for a pedestrian, including style and color.

---@param ped number Entity ID
---@return table Hair data
local hair = exports['illenium-appearance']:getPedHair(ped)
print(hair.style)

getPedAppearance(ped)

Retrieves the full appearance object for a pedestrian.

---@param ped number Entity ID
---@return table Full appearance
local appearance = exports['illenium-appearance']:getPedAppearance(ped)
print(appearance.model)

Set the player

setPlayerModel(model)

Sets the player’s model to the specified model. Health and armour carry over, max health resets to 200.

---@param model string|number Model name or hash
---@return number ped The new ped
local ped = exports['illenium-appearance']:setPlayerModel("mp_f_freemode_01")

setPlayerAppearance(appearance)

Sets the player's model and full appearance. Values that don't exist on the client are clamped and the player is notified.

---@param appearance table Full appearance, including `model`
local appearance = lib.callback.await('illenium-appearance:server:getAppearance', false)
exports['illenium-appearance']:setPlayerAppearance(appearance)

Set a ped

setPedAppearance(ped, appearance)

Sets the full appearance on an existing ped. Does not change the model, use setPlayerAppearance for the player.

---@param ped number Entity ID
---@param appearance table Full appearance data
exports['illenium-appearance']:setPedAppearance(ped, {
    headBlend = {
        shapeFirst = 0, shapeSecond = 1, shapeThird = 2,
        skinFirst = 0, skinSecond = 1, skinThird = 2,
        shapeMix = 0.5, skinMix = 0.5, thirdMix = 0.5
    },
    faceFeatures = {
        noseWidth = 0.8,
        cheeksBoneWidth = 0.5,
        chinBoneLenght = 0.7
    }
})

setPedHeadBlend(ped, headBlend)

Sets the head blend data (shape, skin mix, etc.) for a pedestrian.

---@param ped number Entity ID
---@param headBlend table Head blend data
exports['illenium-appearance']:setPedHeadBlend(ped, {
    shapeFirst = 0, shapeSecond = 1, shapeThird = 2,
    skinFirst = 0, skinSecond = 1, skinThird = 2,
    shapeMix = 0.5, skinMix = 0.5, thirdMix = 0.5
})

setPedFaceFeatures(ped, faceFeatures)

Sets the face features for a pedestrian.

---@param ped number Entity ID
---@param faceFeatures table Face features data
exports['illenium-appearance']:setPedFaceFeatures(ped, {
    noseWidth = 0.8, cheeksBoneWidth = 0.5, chinBoneLenght = 0.7
})

setPedHeadOverlays(ped, headOverlays)

Sets the head overlays (makeup, scars, etc.) for a pedestrian.

---@param ped number Entity ID
---@param headOverlays table Head overlays data
exports['illenium-appearance']:setPedHeadOverlays(ped, {
    blush = { style = 1, opacity = 0.5, color = 1 },
    moleAndFreckles = { style = 2, opacity = 0.3 }
})

setPedHair(ped, hair, tattoos)

Sets the hair data for a pedestrian, including style and color. On freemode peds it also redraws tattoos, from tattoos or the ones already applied.

---@param ped number Entity ID
---@param hair table Hair data
---@param tattoos? table Tattoos to redraw with the hair
exports['illenium-appearance']:setPedHair(ped, {
    style = 1, color = 0, highlight = 1, texture = 0
})

setPedEyeColor(ped, eyeColor)

Sets the eye color.

---@param ped number Entity ID
---@param eyeColor number Eye color index
exports['illenium-appearance']:setPedEyeColor(ped, 3)

setPedComponent(ped, component)

Sets one clothing component. Out of range drawables and textures are clamped, face and hair are skipped on freemode peds.

---@param ped number Entity ID
---@param component { component_id: number, drawable: number, texture: number }
exports['illenium-appearance']:setPedComponent(ped, { component_id = 11, drawable = 15, texture = 0 })

setPedComponents(ped, components)

Sets a list of components, same rules as setPedComponent.

---@param ped number Entity ID
---@param components { component_id: number, drawable: number, texture: number }[]
exports['illenium-appearance']:setPedComponents(ped, {
    { component_id = 4, drawable = 21, texture = 0 },
    { component_id = 6, drawable = 34, texture = 0 },
})

setPedProp(ped, prop)

Sets one prop. A drawable of -1 removes it.

---@param ped number Entity ID
---@param prop { prop_id: number, drawable: number, texture: number }
exports['illenium-appearance']:setPedProp(ped, { prop_id = 0, drawable = -1, texture = 0 })

setPedProps(ped, props)

Sets a list of props, same rules as setPedProp.

---@param ped number Entity ID
---@param props { prop_id: number, drawable: number, texture: number }[]
exports['illenium-appearance']:setPedProps(ped, {
    { prop_id = 0, drawable = 12, texture = 0 },
    { prop_id = 1, drawable = -1, texture = 0 },
})

setPedTattoos(ped, tattoos)

Replaces all tattoos. nil or an empty table removes them.

---@param ped number Entity ID
---@param tattoos? table<string, table[]> Tattoos per zone, same shape as `appearance.tattoos`
local appearance = exports['illenium-appearance']:getPedAppearance(PlayerPedId())
exports['illenium-appearance']:setPedTattoos(PlayerPedId(), appearance.tattoos)

Events

Client events other scripts can trigger with TriggerEvent.

illenium-appearance:client:reloadSkin

Reapplies the saved appearance. Refused while on cooldown, dead, cuffed, in a vehicle or falling, bypassChecks only skips the cooldown.

---@param bypassChecks? boolean
TriggerEvent('illenium-appearance:client:reloadSkin')

illenium-appearance:client:ClearStuckProps

Deletes every object attached to the player. Same cooldown and checks as reloadSkin.

TriggerEvent('illenium-appearance:client:ClearStuckProps')

illenium-appearance:client:openClothingShop

Opens the clothing store. With isPedMenu it opens every section for free.

---@param isPedMenu? boolean
TriggerEvent('illenium-appearance:client:openClothingShop')

illenium-appearance:client:OpenBarberShop

Opens the barber, charged like the shop.

TriggerEvent('illenium-appearance:client:OpenBarberShop')

illenium-appearance:client:OpenTattooShop

Opens the tattoo shop, charged like the shop.

TriggerEvent('illenium-appearance:client:OpenTattooShop')

illenium-appearance:client:OpenSurgeonShop

Opens the plastic surgeon, charged like the shop.

TriggerEvent('illenium-appearance:client:OpenSurgeonShop')

illenium-appearance:client:openOutfitMenu

Opens the outfit menu (change, save, share and delete outfits).

TriggerEvent('illenium-appearance:client:openOutfitMenu')