# Configuration

The config/config.lua file controls all the core logic of the multicharacter system, including character slots, spawn settings, framework behavior, appearance handlers, UI content, and more\
\
Let’s break it all down.

***

## Config File (config.lua)

This file controls the basic functionality of the multicharacter.

### Locale

Sets the active language for the UI.

```lua
Config.Locale = "en"
```

Must match a file inside the /locales/ folder.

***

### Framework Prefix

Prefix used in the database to distinguish character entries (mostly for ESX-based servers).

```
Config.Prefix = "char"
```

***

### Appearance Integration

```lua
Config.AppereanceResource = "qb-clothing"
```

Supported options:

* "qb-clothing"
* "fivem-appearance"
* "illenium-appearance"
* "skinchanger"
* "tgiann-clothing", "dx\_clothing", "rcore\_clothing", "dx-clothing", "karma-clothing"

> This defines which skin/appearance resource will be used during character creation.

***

### Spawn Settings

```lua
Config.SpawnLastLocation = false
Config.defaultSpawn = vector4(-1037.449, -2737.475, 20.1692, 329.1169)
```

* SpawnLastLocation: If true, player will spawn at their last known location.
* defaultSpawn: The default spawn location if not using apartment or housing systems.

***

### Camera Setup

```lua
Config.CamCoords = vector4(-556.22, 286.16, 882.2, -85.00)
Config.HiddenCoords = vector4(-779.01, 326.18, 196.08, 91.04)
```

* CamCoords: Where the camera is placed during character selection.
* HiddenCoords: Where your actual ped is teleported (hidden) during selection.

***

### Starter Items

```lua
Config.starterItems = {
    { item = "bread", count = 5 },
    { item = "water", count = 5 },
}
```

* Items automatically given to the player when they create a new character.

***

### Identifier Settings

```lua
Config.Identifier = {
    column = "license",
    type = "license"
}
```

* column: The database field to use for linking players.
* type: Accepted types: "license", "steam", "fivem", "discord".

> ⚠️ If you’re using Qbox, change to license2.

***

### UI Page Animation

```lua
Config.PageAnimation = "slide"
```

Controls how the multicharacter pages transition.

Options: "slide", "fade", "none"

***

### UI Settings

```lua
Config.UISettings = {
    ['serverHeader'] = "SAKA <span>ROLEPLAY</span>",
    ['storeLabel'] = "SAKA <br>STORE",
    ['serverLabel'] = "Saka Roleplay",
    ['serverLogo'] = "https://.../sakaIcon.png",
    ['serverLogoLight'] = "https://.../serverIcon.png",
}
```

Modify branding, labels, and logos shown in the interface.

***

### PED Animations

{% code overflow="wrap" %}

```lua
Config.Animations = {
    { dict = "anim@heists@heist_corona@single_team", name = "single_team_loop_boss" },
}
```

{% endcode %}

Random idle animations shown during character selection.

***

### Character Slot & Limit

```lua
Config.defaultMaxNumberCharacters = 5
Config.defaultCharactersLimit = 3
```

* defaultMaxNumberCharacters: How many slots are visually shown.
* defaultCharactersLimit: How many characters the player can actually use (unless upgraded via Discord/Tebex/etc.)

***

### Character Options

```lua
Config.canWriteStory = true
Config.canDeleteChar = true
```

* canWriteStory: Players can write a short backstory.
* canDeleteChar: Players can delete characters themselves.

***

### Input Limits

```lua
Config.inputsLengths = {
    firstName = { min = 2, max = 20 },
    lastName = { min = 2, max = 20 },
    height = { min = 100, max = 220 },
}
```

* Minimum and maximum lengths for first name, last name, and height input.

***

### Birthday Format

```lua
Config.birthDayType = "dd/mm/yyyy"
```

Available formats:

* "mm/dd/yyyy"
* "dd/mm/yyyy"
* "yyyy/mm/dd"

***

### Character Deletion Tables

```lua
Config.deleteTables = {
    esx = {
        { table = "users", column = "identifier" },
        ...
    },
    qb = {
        { table = "players", column = "citizenid" },
        ...
    }
}
```

* Defines which database rows get deleted when a character is removed.

> ⚠️  Make sure these tables exist in your database.

***

### Job Icons

```lua
Config.JobIcons = {
    ['police'] = 'police.png',
    ['ambulance'] = 'ambulance.png',
    ...
}
```

* Maps job names to icons shown in character profiles.
* Place icon files in the UI assets folder.

***

### Max Music Upload

```lua
Config.MaxMusic = 5
```

* The maximum number of songs that can be added via the UI.

***

### Logout Command

```lua
Config.Commands = {
    ['logout'] = {
        enable = true,
        command = "logout",
        permission = "user"
    }
}
```

* Enables a /logout command to return to character selection.
* permission: Set required permission group.

***

## Theme File (theme.lua)

The config/theme.lua file lets you fully style the multicharacter UI. Two built-in themes are available:

* Light – Bright, clean look
* Dark – Dark, high-contrast style

Each theme includes four sections:

### General Appearance

Controls core colors for text, backgrounds, buttons, and more.

```lua
general = {
    textColor = "#000000",
    textColorSecondary = "#000000",
    background = "#FFFFFFBF",
    musicPlayerBackground = "#FFFFFF",
    musicPlayerFill = "#000000",
    musicPlayerText = "#000000",
    musicPlayerTrack = "#00000042",
    musicPlayerTrackProgress = "#000000",
    closeBackground = "#0000003D",
    closeBorder = "#0000001C",
    closeFill = "#000000",
    characterSelectedBackground = "#00000033",
    inputBorder = "#00000026",
    inputPlaceholder = "#00000057",
    heredityBg = "#00000014",
    selectedHeredityBg = "#0000000D",
    heredityText = "#00000080",
}
```

* textColor / textColorSecondary: Primary and secondary text colors
* background: Overlay or panel background
* closeBackground, closeBorder, closeFill: Close-button styling
* characterSelectedBackground: Highlight for selected character slot
* inputBorder / inputPlaceholder: Styling for input fields

***

### Shortcuts

Styles for on-screen key hints and shortcut prompts.

```lua
shortcuts = {
    default = "#FFFFFF5C",
    active = "#FFFFFF",
    textColor = "#00000066",
    activeTextColor = "#00000099",
}
```

* default / active: Inactive vs. active key color
* textColor / activeTextColor: Label colors

***

### Stories

If you use multi-step creation with story prompts, these control the buttons and highlights.

```lua
story = {
    buttonBackground = "#FFFFFF24",
    buttonBorder = "#FFFFFF1C",
    buttonFill = "#FFFFFF",
    buttonText = "#FFFFFFCC",
}
```

* buttonBackground / buttonBorder: Button container styling
* buttonFill / buttonText: Button icon/text colors

***

### Settings

Used in any internal settings panels (e.g., Loading Screen, Multicharacter etc.).

```lua
settings = {
    boxBackground = "#FFFFFF33",
    switchBackground = "#FFFFFF1C",
    switchCircle = "#FFFFFF",
    activeSwitchBackground = "#FFFFFF66",
    themeBackground = "#FFFFFF1C",
    svgFill = "#FFFFFF",
    dividerColor = "#0000001A",
}
```

* boxBackground: Panel container color
* switchBackground / activeSwitchBackground: Toggle switch styling
* switchCircle: The knob color on switches
* svgFill: Color for inline SVG icons

***

### Creating Your Custom Theme

1 - Duplicate either the light or dark block in Config.Themes.

2 - Rename the key (e.g., "custom").

3 - Adjust color codes per section.

{% hint style="warning" %}
**Important Notes**

* Colors must be valid hex codes (e.g., #FFFFFF) or rgba formats (e.g., rgba(0,0,0,0.5)).
* Shadows must follow valid CSS box-shadow syntax.
* You can freely create your own theme by duplicating an existing one (light, dark) and editing the colors.
  {% endhint %}

***

## Camera Configuration (camLocations.lua)

This file defines the locations, positions, and angles of the camera and ped during character selection or creation.

### Basic Options

```lua
Config.Cam.FOV = 30.0
Config.Cam.DefaultLocation = 'downtown'
```

* FOV: Camera Field of View (zoom level)
* DefaultLocation: The key of the default camera position used when opening the interface

***

### Camera Presets

You can define multiple camera locations for aesthetic or immersive effects.

```lua
Config.Cam.camLocations = {
    ['downtown'] = {
        ['Label'] = "Downtown",
        ['camCoord'] = vector4(69.11, -238.78, 48.50, 249.91),
        ['pedCoord'] = vector4(71.97, -239.84, 48.19, 59.53),
    },
    ['campSide'] = {
        ['Label'] = "Camp Side",
        ['camCoord'] = vector4(3604.75, 4733.33, 6.02, 325.13),
        ['pedCoord'] = vector4(3606.76, 4736.15, 5.65, 147.65),
    },
    ...
}
```

***

* Label: Display name on UI
* camCoord: Where the camera floats
* pedCoord: Where the ped (character) stands

> You can add as many locations as you want. All appear in a dropdown selector (if supported by the UI).

***

### Camera Movements

```lua
Config.Cam.Effect = {
    rotations = {
        x = 0.0,
        y = -10.0,
        z = -70.0,
    },
    offsets = {
        x = 1.0,
        y = 0.0,
        z = 0.5,
    }
}
```

* rotations: Adjust camera tilt/angle
* offsets: Slightly shift the camera from its base position (for dynamic camera effects)

***

## API Keys

Used to integrate third-party services like Spotify.

### Spotify Song Catcher Integration

```lua
APIKeys = {
    ['clientId']     = "YOUR_CLIENT_ID",
    ['clientSecret'] = "YOUR_CLIENT_SECRET",
}
```

* These keys allow integration with the Spotify Web API
* Use them to fetch songs and their artcovers.

Get your keys here:

🔗 <https://developer.spotify.com/dashboard>

> ⚠️  Never share this file publicly. Keep it server-side only!
