Client Edit

🔧 Framework Validation & Core Setup

Before any logic runs, the module validates the configured framework and ensures required resources are running.

✔ Supported frameworks:

• qbcore
• qbox (backward-compatible with qb-core exports)

✔ Required resource:

• qb-core (must be started)

If validation fails, the script exits silently to prevent errors.

Copyif not Config.Framework 
    or (Config.Framework:lower() ~= 'qbcore' and Config.Framework:lower() ~= 'qbox') then
    return
end

if GetResourceState('qb-core') ~= 'started' then return end

local QBCore = exports['qb-core']:GetCoreObject()

🧰 Utility Functions

Debug Logger

Standardized logging utility that respects global debug settings.

CopyCustomize.Log(level, message)

• Levels: info, debug
• Controlled by:
  • Config.Debug
  • Config.DebugLevel

Logs are automatically filtered to avoid unnecessary spam.

Server Callback Wrapper

Convenience wrapper around QBCore callbacks.

CopyCustomize.TriggerCallback(name, cb, ...)

Internally uses:

CopyQBCore.Functions.TriggerCallback

🎭 Appearance Handling System

The module supports multiple appearance systems and automatically selects the best available option.

Supported Appearance Resources (Priority Order)

1. illenium-appearance (preferred)
2. fivem-appearance
3. qb-clothing
4. Native GTA fallback (automatic)

Native Appearance Fallback

If no supported appearance resource is running, the system applies appearance manually using GTA natives.

Handled features:

• Clothing components
• Props (hats, glasses, etc.)
• Head blend (heritage)
• Head overlays (makeup, blemishes, tattoos)

This ensures display peds always render correctly, even without external appearance scripts.

Apply Appearance to Ped

Main public function for setting ped appearance.

CopyCustomize.SetPedAppearance(ped, appearance)

Features:

• Accepts Lua tables or JSON-encoded strings
• Automatically decodes JSON when needed
• Detects and uses the correct appearance system
• Falls back to native application if required

This function is primarily used for:

• Character slot preview peds
• Cinematic display characters

👤 Player Load Handling

On Player Loaded

Called once the player has successfully joined the server.

CopyCustomize.OnPlayerLoaded()

Actions performed:

• Shuts down the default loading screen
• Handles screen fade transitions
• Waits for QBCore player data to fully load
• Manually triggers QBCore load events:
  • QBCore:Server:OnPlayerLoaded
  • QBCore:Client:OnPlayerLoaded

This prevents compatibility issues with resources that rely on these events.

🌦 Environment & Sync Control

During character selection and creation, weather and time sync are disabled to avoid visual inconsistencies.

Disable Weather Sync

CopyCustomize.DisableWeatherSync()

Supported resources:

• qb-weathersync
• cd_easytime

Enable Weather Sync

CopyCustomize.EnableWeatherSync()

Restores normal weather and time synchronization after selection is complete.

🏠 Interior / Housing Metadata Reset

Prevents players from being stuck inside interiors after character switching.

CopyCustomize.SetInsideMeta()

Supported housing systems:

• qb-houses
• qb-apartments

Resets inside metadata safely on the server.

👕 First Character Creation (Clothing)

Handles opening the clothing/appearance UI for brand new characters only.

CopyCustomize.CreateFirstCharacterClothes()

Behavior depends on the active appearance system:

• illenium-appearance → qb-clothes event
• fivem-appearance → native customization flow with save callback
• fallback → qb-clothes default behavior

📍 Spawn System Handling

Handles spawning logic based on the configured spawn system.

CopyCustomize.HandleSpawn(cData, isNew)

Supported Spawn Systems

• standalone
  • Uses internal spawn logic
  • Returns false
• qb-spawn
  • Opens qb-spawn UI
  • Automatically passes character data
  • Returns true
• custom
  • Allows external scripts to handle spawning
  • Returns true

This function determines whether the default spawn flow should continue or stop.

📦 Module Export

At the end of the file, the module returns the Customize table:

Copyreturn Customize

This allows the character system to access all utilities and handlers cleanly.

✅ Notes

• This module assumes QBCore-compatible exports
• Appearance fallback ensures display peds always render
• Safe guards prevent execution if dependencies are missing
• Designed to be framework-agnostic where possible