# 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
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.arius-scripts.com/site/documentation/resources/multicharacter/configuration/editables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.