> For the complete documentation index, see [llms.txt](https://atiysus-organization.gitbook.io/aty-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atiysus-organization.gitbook.io/aty-scripts/multi-character-v2/installation.md).

# Installation

### Installation

Welcome to the **Aty Scripts - Multi Character V2** documentation! This guide will walk you through installation, configuration, and usage. Please follow each step carefully for a smooth setup.

***

### Download

* Purchase the asset from your [Keymaster](https://keymaster.fivem.net/).
* Only use the asset with the Keymaster account that owns your server key.
* If you have issues with FiveM Escrow, asset startup, or account problems, check the [official documentation](https://docs.fivem.net/docs/server-manual/setting-up-a-server/#license-key) for troubleshooting.

***

### Dependencies

This script **requires**:

* **Framework:** Either [QBCore](https://github.com/qbcore-framework/qb-core) or [ESX](https://github.com/esx-framework/esx-legacy).
* **MySQL Resource:** One of the following:
  * [oxmysql](https://github.com/overextended/oxmysql)
  * [mysql-async](https://github.com/brouznouf/fivem-mysql-async)
  * [ghmattimysql](https://github.com/GHMatti/ghmattimysql)

***

### Ensuring the Script

Add the following line to your `server.cfg`, **after** your MySQL and framework scripts:

```
ensure [aty]/aty_multicharv2
```

Replace `[aty]` with your folder structure if different.

***

### Setting Up

#### 1. Configure the Script

* Open `shared/config.lua` and adjust settings to your needs:
  * Default spawn location
  * Spawn selector type
  * Starter items
  * Available spawn points
  * Default skins for each skin script

#### 2. Database Setup

The script will automatically create the required tables (`aty_multichar_codes`, `aty_multichar_slots`) on first run. Ensure your MySQL resource is running and configured.

***

### Usage

#### Character Selection

* On player join, the character selection menu will appear.
* Players can create, delete, or switch characters.
* Supports multiple character slots, with the ability to unlock more via redeem codes.

#### Spawn Selector

* The spawn selector can be customized.
* To change the spawn selector logic, edit the `SpawnSelector` function in:

  ```
  server/open.lua
  ```

  Example:

  ```lua
  function SpawnSelector(src, playerData, firstSpawn)
      if GetResourceState("aty_spawnselectorv2") == "started" then
          TriggerClientEvent("aty_spawnselectorv2:client:open", src, firstSpawn, playerData)
      elseif GetResourceState("qb-spawn") == "started" then
          TriggerClientEvent("qb-spawn:client:open", src, firstSpawn, playerData)
      -- ...other selectors...
      end
  end
  ```

***

### Skin System Integration

#### Getting Player Skin

The script supports multiple skin systems. The function to get a player's skin is:

```lua
function GetPlayerSkinData(id)
    -- Handles all supported skin scripts
end
```

#### Setting Player Skin

To set a player's skin, the script uses:

```lua
function SetPedSkin(ped, skin)
    if Utils.SkinScript == "illenium-appearance" then
        exports['illenium-appearance']:setPedAppearance(ped, skin)
    elseif Utils.SkinScript == "fivem-appearance" then
        exports['fivem-appearance']:setPedAppearance(ped, skin)
    elseif Utils.SkinScript == "skinchanger" or Utils.SkinScript == "esx_skin" then
        TriggerEvent("skinchanger:loadSkin", skin)
    elseif Utils.SkinScript == "qb-clothing" then
        TriggerEvent('qb-clothing:client:loadPlayerClothing', skin, ped)
    elseif Utils.SkinScript == "rcore_clothing" then
        exports['rcore_clothing']:setPedSkin(ped, skin)
    elseif Utils.SkinScript == "tgiann-clothing" then
        TriggerEvent("tgiann-clothing:client:loadPedClothing", skin, ped)
    elseif Utils.SkinScript == "bl_appearance" then
        exports.bl_appearance:SetPlayerPedAppearance(skin)
    elseif Utils.SkinScript == "crm-appearance" then
        exports['crm-appearance']:crm_set_ped_appearance(ped, skin)
    end
end
```

#### Opening the Skin Menu

To open the skin creation menu for your skin script:

```lua
function SkinMenu()
    local playerPed = PlayerPedId()
    if Utils.SkinScript == 'skinchanger' then
        TriggerEvent('esx_skin:openSaveableMenu', function()
            SetPedAoBlobRendering(playerPed, true)
            ResetEntityAlpha(playerPed)
            SetEntityVisible(playerPed, true)
        end)
    elseif Utils.SkinScript == 'fivem-appearance' then
        SetPedAoBlobRendering(playerPed, true)
        ResetEntityAlpha(playerPed)
        SetEntityVisible(playerPed, true)
        exports['fivem-appearance']:startPlayerCustomization(function(appearance)
            if appearance then
                TriggerServerEvent("fivem-appearance:save", appearance)
            end
        end, {ped = true, headBlend = true, faceFeatures = true, headOverlays = true, components = true, componentConfig = { masks = true, upperBody = true, lowerBody = true, bags = true, shoes = true, scarfAndChains = true, bodyArmor = true, shirts = true, decals = true, jackets = true }, props = true, propConfig = { hats = true, glasses = true, ear = true, watches = true, bracelets = true }, tattoos = true, enableExit = true})
    elseif Utils.SkinScript == 'illenium-appearance' then
        SetPedAoBlobRendering(playerPed, true)
        ResetEntityAlpha(playerPed)
        SetEntityVisible(playerPed, true)
        exports['illenium-appearance']:startPlayerCustomization(function(appearance)
            if appearance then
                TriggerServerEvent("illenium-appearance:server:saveAppearance", appearance)
            end
        end, {ped = true, headBlend = true, faceFeatures = true, headOverlays = true, components = true, componentConfig = { masks = true, upperBody = true, lowerBody = true, bags = true, shoes = true, scarfAndChains = true, bodyArmor = true, shirts = true, decals = true, jackets = true }, props = true, propConfig = { hats = true, glasses = true, ear = true, watches = true, bracelets = true }, tattoos = true, enableExit = true})
    elseif Utils.SkinScript == 'qb-clothing' then
        TriggerEvent('qb-clothes:client:CreateFirstCharacter', false, false)
    elseif Utils.SkinScript == 'rcore_clothing' then
        TriggerEvent('rcore_clothing:openCharCreator')
    elseif Utils.SkinScript == 'tgiann-clothing' then
        if Utils.Framework == 'es_extended' then
            TriggerEvent("tgiann-clothing:esx:createNew")
        else
            TriggerEvent("qb-clothes:client:CreateFirstCharacter")
        end
    elseif Utils.SkinScript == 'bl_appearance' then
        exports.bl_appearance:InitialCreation()
    elseif Utils.SkinScript == 'crm-appearance' then
        TriggerEvent('crm-appearance:init-new-character', 'crm-male') 
    end
end
```

***

### Redeem Codes & Extra Slots

* Admins can generate redeem codes via the server console:

  ```
  purchased_slot {code}
  ```
* Players can redeem codes in the UI to unlock extra character slots.

***

### Commands

* `/logout` — Logs out the current character and opens the character selection menu.

***

### Support

If you encounter issues:

* Double-check your dependencies and configuration.
* Ensure your database is running and accessible.
* Review your server console for errors.
* For further help, contact the script author or your asset provider.

***