# Client

For server events and callbacks see [Server](./server.mdx).

## Menu [#menu]
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### startPlayerCustomization(callback, config, hooks) [#startplayercustomizationcallback-config-hooks]
    <p className="text-fd-muted-foreground text-sm">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.</p>
    ```lua
    ---@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
    })
    ```
    <p className="text-fd-muted-foreground text-sm">Optional <code>hooks</code> only apply to that menu. <code>canOpen</code> returning <code>false</code> stops it from opening and the callback never runs. <code>canSave</code> returning <code>false, reason</code> keeps the menu open and shows the reason. <code>takeCamera</code> returning <code>true</code> hands you the camera instead of destroying it. A hook that errors is logged, <code>canOpen</code> then refuses and <code>canSave</code> lets the save through.</p>
    ```lua
    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,
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### cancelPlayerCustomization() [#cancelplayercustomization]
    <p className="text-fd-muted-foreground text-sm">Close the open menu like the cancel button. The look reverts and the callback gets <code>nil</code>.</p>
    ```lua
    ---@return boolean cancelled `false` when no menu is open
    local cancelled = exports['illenium-appearance']:cancelPlayerCustomization()
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getInterfaceVisibilityState() [#getinterfacevisibilitystate]
    <p className="text-fd-muted-foreground text-sm">Which parts of the UI are open.</p>
    ```lua
    ---@return { app: boolean, loadingScreen: boolean, exportPanel: boolean }
    local visibility = exports['illenium-appearance']:getInterfaceVisibilityState()
    if visibility.app then
        print('Menu is open')
    end
    ```
</div>

## Read a ped [#read-a-ped]
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedModel(ped) [#getpedmodelped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the model name associated with a player's entity. Returns <code>nil</code> for models missing from the ped list.</p>
    ```lua
    ---@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"
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedComponents(ped) [#getpedcomponentsped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the clothing and accessory components of a pedestrian's model.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Components data
    local components = exports['illenium-appearance']:getPedComponents(ped)
    print(components[1].drawable)
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedProps(ped) [#getpedpropsped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the props (hats, glasses, etc.) for a pedestrian.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Props data
    local props = exports['illenium-appearance']:getPedProps(ped)
    print(props[1].prop_id)
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedHeadBlend(ped) [#getpedheadblendped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the head blend data (shape, skin mix, etc.) for a pedestrian.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Head blend data
    local headBlend = exports['illenium-appearance']:getPedHeadBlend(ped)
    print(headBlend.shapeFirst)
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedFaceFeatures(ped) [#getpedfacefeaturesped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the face feature data (facial traits) for a pedestrian.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Face features
    local faceFeatures = exports['illenium-appearance']:getPedFaceFeatures(ped)
    print(faceFeatures['noseWidth'])
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedHeadOverlays(ped) [#getpedheadoverlaysped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the head overlays (makeup, scars, etc.) for a pedestrian.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Head overlays
    local headOverlays = exports['illenium-appearance']:getPedHeadOverlays(ped)
    print(headOverlays['blush'].opacity)
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedHair(ped) [#getpedhairped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the hair data for a pedestrian, including style and color.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Hair data
    local hair = exports['illenium-appearance']:getPedHair(ped)
    print(hair.style)
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### getPedAppearance(ped) [#getpedappearanceped]
    <p className="text-fd-muted-foreground text-sm">Retrieves the full appearance object for a pedestrian.</p>
    ```lua
    ---@param ped number Entity ID
    ---@return table Full appearance
    local appearance = exports['illenium-appearance']:getPedAppearance(ped)
    print(appearance.model)
    ```
</div>

## Set the player [#set-the-player]
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPlayerModel(model) [#setplayermodelmodel]
    <p className="text-fd-muted-foreground text-sm">Sets the player’s model to the specified model. Health and armour carry over, max health resets to 200.</p>
    ```lua
    ---@param model string|number Model name or hash
    ---@return number ped The new ped
    local ped = exports['illenium-appearance']:setPlayerModel("mp_f_freemode_01")
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPlayerAppearance(appearance) [#setplayerappearanceappearance]
    <p className="text-fd-muted-foreground text-sm">Sets the player's model and full appearance. Values that don't exist on the client are clamped and the player is notified.</p>
    ```lua
    ---@param appearance table Full appearance, including `model`
    local appearance = lib.callback.await('illenium-appearance:server:getAppearance', false)
    exports['illenium-appearance']:setPlayerAppearance(appearance)
    ```
</div>

## Set a ped [#set-a-ped]
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedAppearance(ped, appearance) [#setpedappearanceped-appearance]
    <p className="text-fd-muted-foreground text-sm">Sets the full appearance on an existing ped. Does not change the model, use <code>setPlayerAppearance</code> for the player.</p>
    ```lua
    ---@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
        }
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedHeadBlend(ped, headBlend) [#setpedheadblendped-headblend]
    <p className="text-fd-muted-foreground text-sm">Sets the head blend data (shape, skin mix, etc.) for a pedestrian.</p>
    ```lua
    ---@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
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedFaceFeatures(ped, faceFeatures) [#setpedfacefeaturesped-facefeatures]
    <p className="text-fd-muted-foreground text-sm">Sets the face features for a pedestrian.</p>
    ```lua
    ---@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
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedHeadOverlays(ped, headOverlays) [#setpedheadoverlaysped-headoverlays]
    <p className="text-fd-muted-foreground text-sm">Sets the head overlays (makeup, scars, etc.) for a pedestrian.</p>
    ```lua
    ---@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 }
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedHair(ped, hair, tattoos) [#setpedhairped-hair-tattoos]
    <p className="text-fd-muted-foreground text-sm">Sets the hair data for a pedestrian, including style and color. On freemode peds it also redraws tattoos, from <code>tattoos</code> or the ones already applied.</p>
    ```lua
    ---@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
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedEyeColor(ped, eyeColor) [#setpedeyecolorped-eyecolor]
    <p className="text-fd-muted-foreground text-sm">Sets the eye color.</p>
    ```lua
    ---@param ped number Entity ID
    ---@param eyeColor number Eye color index
    exports['illenium-appearance']:setPedEyeColor(ped, 3)
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedComponent(ped, component) [#setpedcomponentped-component]
    <p className="text-fd-muted-foreground text-sm">Sets one clothing component. Out of range drawables and textures are clamped, face and hair are skipped on freemode peds.</p>
    ```lua
    ---@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 })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedComponents(ped, components) [#setpedcomponentsped-components]
    <p className="text-fd-muted-foreground text-sm">Sets a list of components, same rules as <code>setPedComponent</code>.</p>
    ```lua
    ---@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 },
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedProp(ped, prop) [#setpedpropped-prop]
    <p className="text-fd-muted-foreground text-sm">Sets one prop. A <code>drawable</code> of <code>-1</code> removes it.</p>
    ```lua
    ---@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 })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedProps(ped, props) [#setpedpropsped-props]
    <p className="text-fd-muted-foreground text-sm">Sets a list of props, same rules as <code>setPedProp</code>.</p>
    ```lua
    ---@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 },
    })
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### setPedTattoos(ped, tattoos) [#setpedtattoosped-tattoos]
    <p className="text-fd-muted-foreground text-sm">Replaces all tattoos. <code>nil</code> or an empty table removes them.</p>
    ```lua
    ---@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)
    ```
</div>

## Events [#events]
Client events other scripts can trigger with `TriggerEvent`.

<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:reloadSkin [#illenium-appearanceclientreloadskin]
    <p className="text-fd-muted-foreground text-sm">Reapplies the saved appearance. Refused while on cooldown, dead, cuffed, in a vehicle or falling, <code>bypassChecks</code> only skips the cooldown.</p>
    ```lua
    ---@param bypassChecks? boolean
    TriggerEvent('illenium-appearance:client:reloadSkin')
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:ClearStuckProps [#illenium-appearanceclientclearstuckprops]
    <p className="text-fd-muted-foreground text-sm">Deletes every object attached to the player. Same cooldown and checks as <code>reloadSkin</code>.</p>
    ```lua
    TriggerEvent('illenium-appearance:client:ClearStuckProps')
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:openClothingShop [#illenium-appearanceclientopenclothingshop]
    <p className="text-fd-muted-foreground text-sm">Opens the clothing store. With <code>isPedMenu</code> it opens every section for free.</p>
    ```lua
    ---@param isPedMenu? boolean
    TriggerEvent('illenium-appearance:client:openClothingShop')
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:OpenBarberShop [#illenium-appearanceclientopenbarbershop]
    <p className="text-fd-muted-foreground text-sm">Opens the barber, charged like the shop.</p>
    ```lua
    TriggerEvent('illenium-appearance:client:OpenBarberShop')
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:OpenTattooShop [#illenium-appearanceclientopentattooshop]
    <p className="text-fd-muted-foreground text-sm">Opens the tattoo shop, charged like the shop.</p>
    ```lua
    TriggerEvent('illenium-appearance:client:OpenTattooShop')
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:OpenSurgeonShop [#illenium-appearanceclientopensurgeonshop]
    <p className="text-fd-muted-foreground text-sm">Opens the plastic surgeon, charged like the shop.</p>
    ```lua
    TriggerEvent('illenium-appearance:client:OpenSurgeonShop')
    ```
</div>
<br />
<div className="flex flex-col gap-2 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
    ### illenium-appearance:client:openOutfitMenu [#illenium-appearanceclientopenoutfitmenu]
    <p className="text-fd-muted-foreground text-sm">Opens the outfit menu (change, save, share and delete outfits).</p>
    ```lua
    TriggerEvent('illenium-appearance:client:openOutfitMenu')
    ```
</div>
