DOCSEARCHbyAlgolia
Submit Docs

illenium-appearance

repository·main·Indexed 43 days ago

https://github.com/illeniumstudios/illenium-appearance

A comprehensive replacement for clothing and character appearance resources in FiveM. It supports qb-core, ESX, and ox_core frameworks, providing advanced features such as tattoo support, job-restricted clothing, skin migration from qb-clothing and esx_skin, and rank-based clothing rooms for jobs and gangs.

Tokens
2.4K
Snippets
3
Records
14
Agent score
53%

What's inside illenium-appearance

  1. Overview of illenium-appearance features

    main

    illenium-appearance is a replacement for clothing resources that provides advanced character customization and management. Key features include:

    • Customization: Support for Tattoos, Hair Textures, and Makeup Secondary Colors.
    • Clothing Management: Player outfits, rank-based clothing rooms for Jobs/Gangs, and job/gang-locked stores.
    • Access Control: Blacklist or limit components, props, and peds based on Jobs, Gangs, CitizenIDs, or ACEs (useful for VIP clothing).
    • Integration: Polyzone support, qb-target support, and OX Lib UI.
    • Migration: Supports skin migration from qb-clothing, old fivem-appearance, and esx_skin.
    • Persistence: Persists Job/Gang clothes on reconnects or logouts.
    • Commands:
      • /pedmenu: Opens the Ped Menu (configurable).
      • /reloadskin: Reloads the player's skin.

  2. Check framework compatibility and dependencies

    main

    Before installing, ensure your server uses one of the supported frameworks and meets the dependency requirements:

    Supported Frameworks

    • qb-core
    • ESX
    • ox_core (experimental)

    Required Dependencies

    • ox_lib (Required for all)
    • Framework-specific core (Required):
      • qb-core (Latest) for qb-core servers
      • es_extended (Latest) for ESX servers
      • ox_core for ox_core servers

    Optional Dependencies

    • qb-target (For qb-core based servers)

  4. How outfit management works

    main

    The system provides several ways to manage outfits, categorized by ownership:

    1. Player Outfits: Standard outfits saved by players that they can change, update, delete, or generate codes for.
    2. Job/Gang Outfits: Outfits managed by organizations. If Config.BossManagedOutfits is enabled, these are handled via a specific management menu where bosses can save, change, or delete outfits for their members.
    3. Uniforms: Special appearance configurations (often for jobs) that are synced via the server and can be set to persist or be automatically reloaded.

  6. Reload player appearance

    main

    The event illenium-appearance:client:reloadSkin allows a player to refresh their current appearance from the database. This is useful if appearance data has been updated externally or if the player's model needs to be reset.

    Behavior:

    • It checks for a cooldown period defined in Config.ReloadSkinCooldown.
    • It verifies the player is not in a vehicle, not falling, and passes framework metadata checks.
    • It backs up player stats, fetches the appearance from the server, applies it, and restores stats.
    • If Config.PersistUniforms is enabled, it will also attempt to reload any active uniforms.

  7. Open the clothing shop

    main

    Use OpenShop to launch the customization interface for a specific purpose (e.g., a clothing store or a barber shop). It checks if the player has sufficient funds before opening the menu.

    Parameters:

    • config: A configuration table defining which customization sections are available (e.g., components, props, tattoos).
    • isPedMenu: Boolean indicating if the shop is being accessed via a Ped menu (which may include more customization options like head blend and face features).
    • shopType: A string identifying the shop type (e.g., "clothing"). This is used to determine which server-side charge event to trigger upon successful customization.

    Note: If isPedMenu is true, the system may automatically include more advanced customization options like headBlend, faceFeatures, and headOverlays.

    -- Example: Opening a basic clothing shop
OpenShop({
    components = true,
    props = true
}, false, "clothing")

  9. Server Callbacks for Appearance and Outfits

    main

    The following lib.callback methods are available for client-to-server communication to manage player appearance, outfits, and shop transactions.

    Get Player Appearance

    Retrieves the current appearance data for a player.

    • Callback: illenium-appearance:server:getAppearance(model)
    • Returns: The player's appearance data via the framework.

    Manage Outfits

    • Generate Outfit Code: illenium-appearance:server:generateOutfitCode(outfitID) Generates or retrieves a unique sharing code for a specific outfit ID.
    • Import Outfit Code: illenium-appearance:server:importOutfitCode(outfitName, outfitCode) Imports an outfit from a sharing code. Returns true on success or nil on failure.
    • Get Player Outfits: illenium-appearance:server:getOutfits() Returns a list of all saved outfits for the calling player.
    • Get Management Outfits: illenium-appearance:server:getManagementOutfits(mType, gender) Retrieves outfits assigned to specific jobs or gangs based on the player's rank and gender. mType can be "Gang" or a job type.

    Shop and Payment Logic

    • Check Funds: illenium-appearance:server:hasMoney(shopType) Checks if a player has enough cash for a specific shop type. shopType can be "clothing", "barber", "tattoo", or "surgeon". Returns true, amount if successful.
    • Pay for Tattoo: illenium-appearance:server:payForTattoo(tattoo) Attempts to remove money for a tattoo purchase. tattoo should be an object containing cost and label.
    • Charge Customer: illenium-appearance:server:chargeCustomer(shopType) A server-side event/logic used to charge a player for shop services (clothing, barber, etc.) using cash.

  11. Server Events for Appearance and Outfit Management

    main

    Use these RegisterNetEvent and RegisterServerEvent triggers to manipulate appearance and outfit data from the client or other server scripts.

    Appearance Persistence

    • Save Appearance: illenium-appearance:server:saveAppearance(appearance) Saves the provided appearance data to the player's record in the database.

    Outfit Management

    • Save Outfit: illenium-appearance:server:saveOutfit(name, model, components, props) Saves a new custom outfit with a name, model, components, and props.
    • Update Outfit: illenium-appearance:server:updateOutfit(id, model, components, props) Updates an existing outfit by its ID.
    • Delete Outfit: illenium-appearance:server:deleteOutfit(id) Deletes an outfit and its associated sharing code.
    • Save Management Outfit: illenium-appearance:server:saveManagementOutfit(outfitData) Saves an outfit to the management/job outfit database.
    • Delete Management Outfit: illenium-appearance:server:deleteManagementOutfit(id) Deletes a management outfit by ID.

    Uniforms and Routing

    • Sync Uniform: illenium-appearance:server:syncUniform(uniform) Sets the current uniform for the player.
    • Get Uniform: (via callback) illenium-appearance:server:getUniform() Retrieves the player's current uniform.
    • Change Routing Bucket: illenium-appearance:server:ChangeRoutingBucket() Sets the player's routing bucket to their own server ID.
    • Reset Routing Bucket: illenium-appearance:server:ResetRoutingBucket() Resets the player's routing bucket to 0.