Commands & Exports

This section lists all available commands, exports, and events included in the script. You’ll find client-side, server-side, and shared functions designed to help developers integrate, extend, or interact with the system easily within their own scripts or frameworks.

Commands

This section lists all available commands included in the script. Each command is designed to simplify administration, player interaction, or debugging tasks. You’ll find detailed descriptions, usage examples, and permission requirements to help you manage and customize your server efficiently.

Command
Description

/save-images

The new clothing photography engine starts.

/test_cam_saver [component] [componentId]

Test the camera saver.

/create_shop

Create clothing stores, barbershops, tattoo parlors, or surgeons in-game.

/delete_shop

Delete a shop (this must be created in-game, not in config)

/appearance

It will open the customization menu (administrative)

/reloadskin

It will refresh your player skin.

/clearstuckprops

Will fix if a prop breaks on your player (situational)

/migrateskins

Migration command for qb-clothing, esx_skin, fivem-appearance

/migrateoutfits

Only compatible with servers that previously used illenium-appearance.

Client Exports

This section provides all available client exports for the script. These functions allow you to interact directly with the system from the client side, enabling custom features, UI interactions, and integrations with other resources. Each export includes a short description and usage example for easy implementation.

startPlayerCustomization

The startPlayerCustomization export opens the character customization menu so the player can change their appearance (clothes, face, hair, etc.). It sets up the camera, hides the HUD, and locks the player in place until they finish.

How to Use

You can use this export in a command like this:

RegisterCommand('customize', function()
    local config = exports['qs-appearance']:GetDefaultConfig()
    -- you can see what options of the config in qs-appearance/types.lua `Config` type
    config.character = true               -- this will enable character creation and make all the prices 0
    config.enableExit = true              -- this will enable the exit button in the customization menu
    config.upper_body = true
    config.componentConfig.gloves = false -- this will disable gloves in the upper body section
    exports['qs-appearance']:startPlayerCustomization(function(appearance)
        if appearance then
            print('Player finished customizing.')
            -- You can save the appearance here
        else
            print('Player cancelled customization.')
        end
    end, config)
end)

What It Does

  • Opens the customization menu

  • Freezes the player and hides the HUD

  • Lets the player change their appearance

  • Calls your callback function when done or cancelled

getPedModel

The getPedModel export allows you to retrieve the internal model identifier of a given ped entity. This is useful when you need to identify the ped’s base model (such as male, female, or any custom ped) in order to apply logic, customization, or compatibility checks.

How to Use

To get the model name of any ped entity, use the following code:

local ped = PlayerPedId()
local model = exports['qs-appearance']:getPedModel(ped)

print("Ped model:", model)

This export returns a string representing the model name associated with the given ped, such as "mp_m_freemode_01". The function automatically initializes internal mappings if they haven't been computed yet, ensuring consistent results across uses.

getPedComponents

The getPedComponents export allows you to retrieve a complete list of clothing components applied to a given ped. This includes data such as drawable variations and textures for each component slot (e.g., torso, pants, arms, gloves). It's ideal for saving appearances or debugging character customization.

How to Use

To get the clothing components of a ped, use the following code:

local ped = PlayerPedId()
local components = exports['qs-appearance']:getPedComponents(ped)

for i, comp in pairs(components) do
    print("Component ID:", comp.component_id)
    print("Drawable:", comp.drawable)
    print("Texture:", comp.texture)
end

This will return a table indexed by component slot, where each entry contains:

  • component_id: The slot ID

  • drawable: The drawable index (or combined index for gloves)

  • texture: The texture variation

Special cases like arms (component_id == 3) and gloves (component_id == 99) are handled separately for accuracy.

getPedProps

The getPedProps export allows you to retrieve all prop accessories currently applied to a given ped. This includes elements like hats, glasses, watches, and more. It is useful for saving or analyzing player props when managing appearance systems.

How to Use

To get the props of a ped, use the following code:

local ped = PlayerPedId()
local props = exports['qs-appearance']:getPedProps(ped)

for i, prop in pairs(props) do
    print("Prop ID:", prop.prop_id)
    print("Drawable:", prop.drawable)
    print("Texture:", prop.texture)
end

This function returns a table where each entry includes:

  • prop_id: The identifier for the prop slot (e.g., hat, glasses)

  • drawable: The model variation index for that prop

  • texture: The texture variation for that prop

It loops through all predefined prop slots, ensuring accurate and complete data for character customization or syncing purposes.

getPedHeadBlend

The getPedHeadBlend export allows you to retrieve detailed information about a ped’s genetic face and skin blending data. This includes the heritage-based head structure used by the freemode characters, which combines parental facial features and skin tones. It's essential for accurately storing or replicating character appearance in custom servers.

How to Use

To retrieve the head blend data of a ped, use the following code:

local ped = PlayerPedId()
local blendData = exports['qs-appearance']:getPedHeadBlend(ped)

print("Father Shape ID:", blendData.shapeFirst)
print("Mother Shape ID:", blendData.shapeSecond)
print("Shape Mix:", blendData.shapeMix)
print("Skin Mix:", blendData.skinMix)

This export returns a table with the following fields:

  • shapeFirst, shapeSecond, shapeThird: Parental shape IDs

  • skinFirst, skinSecond, skinThird: Parental skin tone IDs

  • shapeMix, skinMix, thirdMix: Blend percentages (0.0 to 1.0)

  • shape: A string like "21_0" combining the first and second shape IDs

  • skin: A string like "4_1" combining the first and second skin tone IDs

This data is crucial for reproducing the exact facial structure and skin tone of any freemode ped using the GTA V character creator system.

getPedFaceFeatures

The getPedFaceFeatures export allows you to retrieve all facial customization values of a ped, including nose width, jawline, cheekbone height, and more. These are the detailed morph values used in the GTA V character creator to fine-tune a freemode ped's face.

How to Use

To get the facial features of a ped, use the following code:

local ped = PlayerPedId()
local faceFeatures = exports['qs-appearance']:getPedFaceFeatures(ped)

for feature, value in pairs(faceFeatures) do
    print("Feature:", feature, "Value:", value)
end

This export returns a table where:

  • The keys are face feature names (as defined in constants.FACE_FEATURES)

  • The values are normalized floats (rounded to one decimal) representing each morph target, usually between -1.0 and 1.0

This data is essential for saving and restoring highly customized characters, enabling full reconstruction of facial structures across sessions or between servers.

getPedHeadOverlays

The getPedHeadOverlays export allows you to retrieve all head overlay data applied to a ped, such as blemishes, beards, makeup, lipstick, and more. These overlays are part of GTA V’s freemode character customization and define additional facial details.

How to Use

To get the head overlays of a ped, use the following code:

local ped = PlayerPedId()
local overlays = exports['qs-appearance']:getPedHeadOverlays(ped)

for name, data in pairs(overlays) do
    print("Overlay:", name)
    print("Style:", data.style)
    print("Opacity:", data.opacity)
    print("Color:", data.color)
    print("Second Color:", data.secondColor)
end

This export returns a table where:

  • Each key is a named overlay (e.g., beard, makeup, blush) from constants.HEAD_OVERLAYS

  • Each value is a table containing:

    • style: The index of the selected overlay style

    • opacity: The blend opacity of the overlay (0.0–1.0)

    • color: The primary color ID

    • secondColor: The secondary color ID (used by some overlays)

If an overlay is not applied (value == 255), the function normalizes it by setting style and opacity to 0. This makes it safe and consistent to save, apply, or replicate overlays across characters.

getPedHair

The getPedHair export allows you to retrieve detailed information about a ped’s hairstyle, including the selected style, base color, highlight color, and texture variation. It’s ideal for storing or replicating custom hairstyles in character creation systems.

How to Use

To get the hair data of a ped, use the following code:

local ped = PlayerPedId()
local hairData = exports['qs-appearance']:getPedHair(ped)

print("Hair Style:", hairData.style)
print("Hair Texture:", hairData.texture)
print("Hair Color:", hairData.color)
print("Highlight Color:", hairData.highlight)

This export returns a table with:

  • style: Hair model index (drawable ID for slot 2)

  • texture: Texture variation for the selected hair

  • color: Primary hair color ID

  • highlight: Secondary highlight color ID

This function ensures you can track and reapply exact hairstyles with full visual fidelity in any freemode ped customization workflow.

getPedAppearance

The getPedAppearance export allows you to retrieve the complete visual configuration of a ped, including model, facial structure, clothing, props, overlays, tattoos, hair, and eye color. It is designed for full appearance saving, cloning, or syncing across sessions or servers.

How to Use

To get the full appearance data of a ped, use the following code:

local ped = PlayerPedId()
local appearance = exports['qs-appearance']:getPedAppearance(ped)

print("Model:", appearance.model)
print("Eye Color:", appearance.eyeColor)
print("Total components:", #appearance.components)

This export returns a comprehensive table including:

  • model: The ped model string (e.g., mp_m_freemode_01)

  • headBlend: Facial and skin blend data from parents

  • faceFeatures: Morph values for facial structure

  • headOverlays: Makeup, beards, blemishes, etc.

  • components: Clothing items (torso, pants, shoes, etc.)

  • props: Accessories (glasses, hats, etc.)

  • hair: Hair style, texture, color, and highlight

  • tattoos: A list of all active tattoos (client-side retrieved)

  • eyeColor: Eye color index (normalized and validated)

This export is the most complete representation of a ped’s visual state and is ideal for any save/load appearance system, identity cloning, or advanced character design workflows.

setPlayerModel

The setPlayerModel export allows you to dynamically change a player’s ped model by providing either a string (e.g., "mp_m_freemode_01") or a numeric hash. It also ensures the model is properly loaded, assigned, and, if applicable, initialized with default appearance settings for freemode characters.

How to Use

To change a player's model to freemode male or female, use:

exports['qs-appearance']:setPlayerModel("mp_m_freemode_01")

You can also pass a custom model hash:

exports['qs-appearance']:setPlayerModel(joaat("a_m_m_bevhills_01"))

This export performs the following:

  • Converts the model string to a hash if needed

  • Requests and waits for the model to load

  • Sets the player model with SetPlayerModel

  • Applies default component variations for freemode models

  • Sets default face blend data depending on gender

  • Resets any tattoos (PED_TATTOOS = {})

Returns the updated ped entity if the model was successfully applied, or the playerId if the model was invalid. This function is ideal for character creation, identity change mechanics, or any system requiring model switching with proper initialization.

setPedHeadBlend

The setPedHeadBlend export allows you to apply facial and skin blend data to a freemode ped. This function is essential for replicating custom character genetics, such as parent-based facial structure and skin tone blending.

How to Use

To apply a head blend to a ped, use the following code:

local ped = PlayerPedId()
local blendData = {
    shapeFirst = 21,
    shapeSecond = 0,
    shapeThird = 0,
    skinFirst = 4,
    skinSecond = 1,
    skinThird = 0,
    shapeMix = 0.6,
    skinMix = 0.4,
    thirdMix = 0.0
}

exports['qs-appearance']:setPedHeadBlend(ped, blendData)

This export takes two arguments:

  • ped: The ped entity to apply the blend to

  • headBlend: A table containing the shape and skin parent IDs and mix ratios

The function only executes if the ped model is a freemode ped (mp_m_freemode_01 or mp_f_freemode_01), ensuring compatibility. It applies the blend using SetPedHeadBlendData, allowing precise control over character genetics and appearance.

CheckIfInventoryBlocked

The CheckIfInventoryBlocked export allows you to check if the player's inventory is currently blocked (for example, when they are in a menu or in a restricted situation where they can't interact with their inventory). This is useful for ensuring certain actions only happen when the inventory is accessible.

How to Use

To check if the inventory is blocked, use the following code:

local isBlocked = exports['qs-inventory']:CheckIfInventoryBlocked()
if isBlocked then
    print("Inventory is blocked.")
else
    print("Inventory is not blocked.")
end

Here’s an example of a command that checks if the player's inventory is blocked:

RegisterCommand('checkinventory', function()
    local isBlocked = exports['qs-inventory']:CheckIfInventoryBlocked()

    if isBlocked then
        print("Result: Inventory is currently blocked.")
    else
        print("Result: Inventory is not blocked and can be used.")
    end
end)

This example checks if the inventory is blocked when using the /checkinventory command. If the inventory is blocked, it will print a corresponding message; otherwise, it will confirm that the inventory is usable.

setPedFaceFeatures

The setPedFaceFeatures export allows you to apply detailed morph targets to a freemode ped's face. These values control features like nose width, jawline, cheekbone shape, and other customizable facial characteristics.

How to Use

To apply a set of face features to a ped, use the following code:

local ped = PlayerPedId()
local features = {
    nose_width = 0.2,
    jawline = -0.4,
    cheekbone_height = 0.1,
    -- Add the rest based on constants.FACE_FEATURES
}

exports['qs-appearance']:setPedFaceFeatures(ped, features)

This export takes:

  • ped: The ped entity to modify

  • faceFeatures: A table where each key corresponds to an entry in constants.FACE_FEATURES and each value is a float between -1.0 and 1.0

The function loops through all predefined facial features and applies them with SetPedFaceFeature, converting each to a float for proper interpolation. It is ideal for restoring saved faces or generating new randomized ones.

setPedHeadOverlays

The setPedHeadOverlays export allows you to apply facial detail overlays to a ped, such as beards, makeup, blemishes, and more. These overlays add depth and realism to freemode characters and are commonly used in character customization systems.

How to Use

To apply head overlays to a ped, use the following code:

local ped = PlayerPedId()
local overlays = {
    beard = { style = 2, opacity = 0.8, color = 1, secondColor = 1 },
    lipstick = { style = 5, opacity = 0.6, color = 2, secondColor = 0 },
    -- Add other overlays as needed
}

exports['qs-appearance']:setPedHeadOverlays(ped, overlays)

This export takes:

  • ped: The ped entity to apply overlays to

  • headOverlays: A table where keys are overlay names (e.g., "beard", "makeUp") and values include:

    • style: Overlay style index

    • opacity: Blend amount (0.0–1.0)

    • color: Primary color ID (optional)

    • secondColor: Secondary color ID (optional)

The function automatically sets the appropriate colorType based on the overlay (e.g., 2 for lipstick or makeup). It ensures visual consistency by updating both the style and color layers, making it ideal for restoring or customizing detailed character appearances.

setPedHair

The setPedHair export allows you to apply a complete hairstyle configuration to a ped, including the style index, texture variation, color, and highlight. If the ped is a freemode model, it also re-applies tattoos to ensure compatibility with hair variations that may hide or affect them.

How to Use

To apply a hairstyle to a ped, use the following code:

local ped = PlayerPedId()
local hair = {
    style = 5,
    texture = 1,
    color = 2,
    highlight = 3
}

exports['qs-appearance']:setPedHair(ped, hair)

You may optionally provide tattoo data as a third argument:

exports['qs-appearance']:setPedHair(ped, hair, savedTattoos)

This export takes:

  • ped: The ped entity to modify

  • hair: A table with hairstyle settings:

    • style: Hair drawable index (component 2)

    • texture: Texture variation

    • color: Hair color ID

    • highlight: Highlight color ID

  • tattoos (optional): Tattoo data to reapply after hair change

If the ped model is a freemode character, the function also calls setTattoos, preserving tattoo appearance across hairstyle changes.

setPedEyeColor

The setPedEyeColor export allows you to set the eye color of a ped by specifying a valid eye color ID. It’s typically used in character customization systems to apply cosmetic changes to freemode characters.

How to Use

To set the eye color of a ped, use the following code:

local ped = PlayerPedId()
exports['qs-appearance']:setPedEyeColor(ped, 3) -- 3 = light blue (example)

This export takes:

  • ped: The ped entity to modify

  • eyeColor: A number representing the eye color index

The valid range for eyeColor depends on the game (typically 0–31). It uses SetPedEyeColor internally and is a simple but essential part of complete character appearance customization.

setPedComponent

The setPedComponent export allows you to apply a single clothing component to a ped, such as a shirt, pants, or jacket. It includes automatic handling for special cases like torso adjustments based on jackets, and skips invalid combinations for freemode peds.

How to Use

To apply a clothing component to a ped, use the following code:

local ped = PlayerPedId()
local component = {
    component_id = 11, -- Jacket
    drawable = 15,
    texture = 2
}

exports['qs-appearance']:setPedComponent(ped, component)

This export takes:

  • ped: The ped entity to modify

  • component: A table with:

    • component_id: The slot ID (e.g., 11 for jacket)

    • drawable: The model variation index

    • texture: The texture index

Behavior:

  • Skips application of component 0 (face) and 2 (hair) for freemode peds, as they are typically handled elsewhere.

  • If the component is a jacket (component_id == 11), it attempts to adjust the arms (component 3) using internal torso-hand mapping (GetUpperBodyData()), ensuring visual compatibility.

  • Applies the variation using SetPedComponentVariation. If the component ID is 99 (used internally for gloves), it remaps to component 3 (arms).

This function is ideal for granular updates to specific clothing slots while maintaining compatibility with freemode models.

setPedComponents

The setPedComponents export allows you to apply a full set of clothing components to a ped in a single operation. It loops through all provided components and applies them individually using the internal logic of setPedComponent.

How to Use

To apply a full outfit to a ped, use the following code:

local ped = PlayerPedId()
local components = {
    { component_id = 11, drawable = 15, texture = 2 }, -- Jacket
    { component_id = 4, drawable = 6, texture = 1 },   -- Pants
    { component_id = 6, drawable = 2, texture = 0 }    -- Shoes
}

exports['qs-appearance']:setPedComponents(ped, components)

This export takes:

  • ped: The ped entity to modify

  • components: A table of component tables, where each entry includes:

    • component_id: Slot ID (e.g., torso, pants)

    • drawable: Variation index

    • texture: Texture index

Each component is passed through the setPedComponent function, ensuring proper handling of special cases (like torso adjustments) and freemode model validation. This export is ideal for applying full outfits or restoring saved appearances efficiently.

setPedProp

The setPedProp export allows you to apply or remove an individual accessory (prop) to a ped, such as hats, glasses, or watches. It intelligently clears props when an invalid drawable index is provided, ensuring clean application.

How to Use

To apply a prop to a ped, use the following code:

local ped = PlayerPedId()
local prop = {
    prop_id = 0,       -- Hat slot
    drawable = 5,      -- Hat model index
    texture = 0        -- Texture variation
}

exports['qs-appearance']:setPedProp(ped, prop)

To remove a prop, pass a drawable value of -1 or 6363:

local prop = {
    prop_id = 1,       -- Glasses slot
    drawable = -1      -- Will trigger prop removal
}

exports['qs-appearance']:setPedProp(ped, prop)

This export takes:

  • ped: The ped entity to modify

  • prop: A table including:

    • prop_id: The accessory slot ID

    • drawable: The prop variation index (-1 or 6363 clears the slot)

    • texture: The texture variation (optional if clearing)

It uses SetPedPropIndex to apply the prop or ClearPedProp when removal is needed, making it useful for both equipping and unequipping individual accessories dynamically.

setPedProps

The setPedProps export allows you to apply a full set of accessories (props) to a ped at once. This includes items such as hats, glasses, earrings, and watches. It uses the internal setPedProp function to handle each accessory safely and consistently.

How to Use

To apply multiple props to a ped, use the following code:

local ped = PlayerPedId()
local props = {
    { prop_id = 0, drawable = 5, texture = 1 },  -- Hat
    { prop_id = 1, drawable = 3, texture = 0 },  -- Glasses
    { prop_id = 2, drawable = -1 }              -- Remove earrings
}

exports['qs-appearance']:setPedProps(ped, props)

This export takes:

  • ped: The ped entity to modify

  • props: A table of prop definitions, where each entry includes:

    • prop_id: Accessory slot ID (e.g., 0 for hats)

    • drawable: Variation index (-1 or 6363 removes the prop)

    • texture: Texture variation (optional if removing)

It loops through each entry and applies or removes the prop as needed, making it ideal for restoring full accessory sets during character load or outfit switching.

setPlayerAppearance

The setPlayerAppearance export allows you to completely apply a saved player appearance, including model, facial features, clothing, hair, props, overlays, tattoos, and more. It combines both model loading and full appearance restoration in a single call.

How to Use

To fully load a saved appearance on a player, use the following code:

local savedAppearance = {
    model = "mp_m_freemode_01",
    headBlend = { shapeFirst = 21, shapeSecond = 0, shapeThird = 0, skinFirst = 4, skinSecond = 1, skinThird = 0, shapeMix = 0.5, skinMix = 0.5, thirdMix = 0 },
    faceFeatures = { nose_width = 0.1, jawline = -0.2, cheekbone_height = 0.3 },
    headOverlays = { beard = { style = 2, opacity = 0.7, color = 1, secondColor = 1 } },
    components = { { component_id = 11, drawable = 15, texture = 2 } },
    props = { { prop_id = 0, drawable = 5, texture = 1 } },
    hair = { style = 5, texture = 1, color = 2, highlight = 3 },
    tattoos = {}, -- if any
    eyeColor = 3
}

exports['qs-appearance']:setPlayerAppearance(savedAppearance)

This export takes:

  • appearance: A table structured exactly like the output of getPedAppearance, containing all relevant appearance data.

Internally, this function:

  1. Sets the ped model using setPlayerModel

  2. Applies the rest of the appearance (blend, features, overlays, clothing, etc.) using setPedAppearance

This export is essential for restoring full character appearances, especially after character selection, respawn, or loading from a database.

setPedAppearance

The setPedAppearance export allows you to apply a full appearance configuration to any ped entity. It handles everything from clothing and props to facial features, head overlays, tattoos, hair, and eye color. This export is ideal for restoring saved character data to an NPC or the player ped.

How to Use

To apply a full appearance to a ped, use the following code:

local ped = PlayerPedId()
local appearance = exports['qs-appearance']:getPedAppearance(ped)

-- Later, restore the same appearance:
exports['qs-appearance']:setPedAppearance(ped, appearance)

This export takes:

  • ped: The ped entity to apply the appearance to

  • appearance: A table structured like the result of getPedAppearance, containing:

    • components: Outfit components (e.g., jacket, pants)

    • props: Accessories (e.g., hat, glasses)

    • headBlend: Facial and skin blending

    • faceFeatures: Facial morphs

    • headOverlays: Beards, makeup, blemishes, etc.

    • hair: Hair style and color

    • eyeColor: Eye color index

    • tattoos: Tattoo list (optional)

Behavior:

  • Applies components and props unconditionally

  • Applies other features conditionally (only if they exist)

  • Includes logic to verify freemode models before applying headBlend

This export is perfect for synchronizing or restoring detailed ped appearances, both for players and AI characters.

setPedTattoos

The setPedTattoos export allows you to apply a list of tattoos to a ped and store them internally for later use. This is essential for preserving character identity, especially for freemode peds using custom tattoo layers.

How to Use

To apply tattoos to a ped, use the following code:

local ped = PlayerPedId()
local tattoos = {
    { collection = "mpbusiness_overlays", name = "MP_Buis_Face_01_M" },
    { collection = "mpchristmas2_overlays", name = "MP_Xmas2_M_Tat_005" }
}

exports['qs-appearance']:setPedTattoos(ped, tattoos)

This export takes:

  • ped: The ped entity to apply tattoos to

  • tattoos: A table of tattoo entries, where each tattoo contains:

    • collection: The overlay dictionary name

    • name: The specific overlay name

Internally, this function saves the tattoos in PED_TATTOOS for reuse (e.g., when switching hair or models) and applies them using the internal setTattoos logic. It is designed to maintain visual consistency across customization changes.