# Editables

These two files are designed to be modified without touching the core script. Put all your custom logic here.

> **Never** modify files outside of `editable.lua` and the bridge files. Core files may be overwritten on updates.

#### `resource/client/editable.lua`

**Hook: `Editable.onSelectionOpen()`**

Fires every time the character selection or creation screen opens. Use this to hide your HUD, pause timers, etc.

```lua
function Editable.onSelectionOpen()
    TriggerEvent("myHud:disable")
    -- exports['okokTextUI']:Close()
end
```

**Hook: `Editable.onCharacterLoad(char, isNew)`**

Fires after a character has fully loaded and the player is in the world. `char` is the raw player data table from your framework (structure varies per framework — see below). `isNew` is `true` when this is a freshly created character.

```lua
function Editable.onCharacterLoad(char, isNew)
    TriggerEvent("myHud:enable")

    if isNew then
        -- first-time-only logic, e.g. play an intro cutscene
    end
end
```

**`char` data per framework:**

| Framework | Key examples                                                                           |
| --------- | -------------------------------------------------------------------------------------- |
| ESX       | `char.firstName`, `char.lastName`, `char.job`, `char.coords`, `char.sex`               |
| QBCore    | `char.charinfo.firstname`, `char.charinfo.lastname`, `char.job.label`, `char.metadata` |
| QBox      | Same as QBCore                                                                         |

**Applying a custom appearance system: `Editable.setSkin(skinData)`**

This function already exists and is called automatically. Edit it to switch appearance systems:

```lua
function Editable.setSkin(skinData)
    local ped = PlayerPedId()
    if type(skinData) == "string" then skinData = json.decode(skinData) end

    -- Uncomment whichever system you use (only one at a time):
    -- exports['fivem-appearance']:setPedAppearance(ped, skinData)
    -- exports['illenium-appearance']:setPedAppearance(ped, skinData)
    -- exports.bl_appearance:SetPlayerPedAppearance(skinData)
    -- TriggerEvent("tgiann-clothing:client:loadPedClothing", skinData.skin, ped)
    -- exports['rcore_clothing']:setPedSkin(ped, skinData)

    return true  -- return true so the fallback skinchanger is skipped
end
```

***

#### `resource/server/editable.lua`

**Hook: `Editable.onCharacterSetup(source, char, isNew)`**

Fires on the server after a character is set up and the player is loading in. Use this to sync data with other resources, give starter items from a custom system, etc.

```lua
function Editable.onCharacterSetup(source, char, isNew)
    -- source = player server ID
    -- char   = character data table (citizenid / slot, firstName, lastName, ...)
    -- isNew  = true for brand-new characters

    if isNew then
        TriggerClientEvent("myWeapons:give", source, "WEAPON_PISTOL")
    end

    -- Example: notify another resource
    TriggerEvent("myScript:characterLoaded", source, char, isNew)
end
```

**Hook: `Editable.onCharacterDelete(identifier)`**

Fires just **before** a character is removed from the database. Use this to clean up rows in your own tables.

```lua
function Editable.onCharacterDelete(identifier)
    -- identifier = citizenid (QB/QBox) or "char1:abc123" (ESX)
    MySQL.update('DELETE FROM my_table WHERE identifier = ?', { identifier })
end
```

**Fetching appearance from a custom table: `Editable.getAppearance(identifier)`**

This function already exists. Edit it to pull skin data from your appearance resource's table instead of the default one:

```lua
function Editable.getAppearance(identifier)
    local skin = nil

    if GetResourceState('fivem-appearance') == 'started' then
        local result = MySQL.query.await("SELECT * FROM `appearance` WHERE `citizenid` = ?", { identifier })
        if result and result[1] then
            skin = json.decode(result[1].skin)
        end
    end

    return skin  -- return nil to fall back to the default skin column
end
```

> **Never** modify files outside of `editable.lua` and the bridge files. Core files may be overwritten on updates.

***

### Events Reference

> For hooking into character load/setup/delete, prefer `Editable.onCharacterLoad`, `Editable.onCharacterSetup`, and `Editable.onCharacterDelete` in the editable files — they are the intended integration points and work across all frameworks. The raw net events below are documented for reference only.

#### Client Net Events (QBCore / QBox only)

These are fired from the server to the client. You can listen to them with `AddEventHandler` in your own resource's client script.

| Event                                        | Payload           | Description                                                                                 |
| -------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- |
| `ars_multicharacter:client:loadCharacter`    | `coords, cData`   | Fires when an existing character is loaded. `cData` contains citizenid, charinfo, job, etc. |
| `ars_multicharacter:client:loadNewCharacter` | `data, apartment` | Fires when a brand-new character is created.                                                |

#### Client Net Events (ESX only)

| Event                                         | Payload | Description                                                                                   |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `ars_multicharacter:esx:client:setPlayerData` | `data`  | Fires to push identity data (firstName, lastName, dob, sex, height) to the ESX player object. |

#### Example — Listening to a client character load event (QBCore/QBox)

```lua
-- In your own resource's CLIENT script
AddEventHandler("ars_multicharacter:client:loadCharacter", function(coords, cData)
    -- cData.citizenid, cData.charinfo.firstname, cData.job.label ...
    TriggerEvent("myScript:playerReady", cData)
end)
```

#### Example — Hooking character load via editable.lua (all frameworks, recommended)

**Client** (`resource/client/editable.lua`):

```lua
function Editable.onCharacterLoad(char, isNew)
    TriggerEvent("myScript:playerReady", char, isNew)
end
```

**Server** (`resource/server/editable.lua`):

```lua
function Editable.onCharacterSetup(source, char, isNew)
    TriggerEvent("myScript:characterSetup", source, char, isNew)
end
```

***