Every option of Koja Multicharacter in shared/config.lua: slots, identity, scene, cutscenes, seasons, audio, arrival, trash, CK, approval, party, spawn, relog and admin.

Configuration

All options live in shared/config.lua, spawn points in shared/spawns.lua and webhooks in server/config.lua.

General

Key	Default	Description
`Config.Debug`	`false`	Console logs
`Config.Locale`	`'en'`	`en` or `pl`. Add your own file in `locales/`
`Config.ServerName`	`'KOJA ROLEPLAY'`	Shown in the top bar
`Config.Logo`	`nil`	Image URL for the top bar
`Config.Currency`	`'$'`	Money prefix
`Config.ShowMoney`	`true`	Shows cash and bank on the character card
`Config.Theme`	see below	UI colours and corners, see Theme / UI colours

Theme / UI colours

shared/config.lua

Config.Theme = {
    accent = '#FF9B00',     -- primary colour: buttons, highlights, selected slot, sliders
    background = '#121212', -- base colour of the panels (tinted warm by the UI)
    text = '#F1ECE6',       -- main text colour (muted text and borders follow it)
    success = '#9BE22D',    -- positive states: free / available / online
    danger = '#FF5A4F',     -- negative states: delete, errors, unavailable
    corners = 'rounded',    -- 'rounded' (chamfered) or 'sharp'
}

Key	Default	What it colours
`accent`	`'#FF9B00'`	The primary colour: buttons, highlights, the selected slot and sliders
`background`	`'#121212'`	The base colour of the panels. The UI tints it warm
`text`	`'#F1ECE6'`	The main text colour. Muted text and borders follow it
`success`	`'#9BE22D'`	Positive states: free, available, online
`danger`	`'#FF5A4F'`	Negative states: delete, errors, unavailable
`corners`	`'rounded'`	`'rounded'` (chamfered corners) or `'sharp'`

Colours are hex only, #RGB or #RRGGBB. They are applied as CSS variables when the UI opens, so you do not need to rebuild the UI. Restart the resource after changing them. An invalid colour is ignored and the default from the table is used instead. Any corners value other than 'sharp' gives 'rounded'.

Slots

shared/config.lua

Config.Slots = {
    Default = 3,
    Max = 8,
    ShowLocked = true,
    ShopUrl = nil,
    ImportEsxSlots = true,
    Tiers = {
        { ace = 'koja.multicharacter.slots.vip', slots = 5 },
        { ace = 'koja.multicharacter.slots.staff', slots = 8 },
    },
    DiscordRoles = {},
}

Key	Description
`Default`	Slots for every player
`Max`	How many slots the UI shows. Extra ones are drawn as locked
`ShowLocked`	Show locked slots up to `Max`
`ShopUrl`	Link shown on locked slots, for example your Tebex
`ImportEsxSlots`	Reads `multicharacter_slots` from the old esx_multicharacter when the player has no own override
`Tiers`	`{ ace, slots }`. The highest matching tier wins. Overrides from `/charslots` win over tiers
`DiscordRoles`	`['role id'] = slots`. Needs `kmc_discord_token` and `kmc_discord_guild` in `server.cfg`; the bot must be a member of the guild. Roles are cached for 10 minutes

Identity

Key	Default	Description
`MinNameLength` / `MaxNameLength`	`2` / `16`	Length of first and last name
`Capitalize`	`true`	Upper-cases the first letter
`MinAge` / `MaxAge`	`18` / `90`	Allowed age
`Height`, `MinHeight`, `MaxHeight`, `DefaultHeight`	`true`, `150`, `210`, `178`	Height field in cm
`Nationality`, `Nationalities`	`true`, 20 entries	Nationality field. An empty list turns it into free text
`Backstory.Enabled / Required / MaxLength`	`true` / `false` / `600`	Backstory field
`UniqueNames`	`true`	Rejects a first and last name that already exists
`BlacklistedNames`	`admin`, `staff`, ...	Rejected names (first, last or full, case-insensitive)
`EsxDateFormat`	`'DD/MM/YYYY'`	Format of `users.dateofbirth` on ESX: `DD/MM/YYYY`, `MM/DD/YYYY` or `YYYY-MM-DD`

Names allow letters (including accented and Cyrillic), spaces, apostrophes and hyphens.

Delete, trash, CK and presets

Key	Default	Description
`Config.Delete.Enabled`	`true`	Players can delete their characters
`Config.Delete.ConfirmName`	`true`	Players must type the full name to delete
`Config.Trash.Days`	`7`	Days a deleted character stays restorable. `0` = delete is permanent
`Config.Trash.PurgeInterval`	`600`	Seconds between purge runs
`Config.CK.AllowDelete`	`true`	Players can delete a dead (memorial) character
`Config.CK.ReasonRequired`	`true`	Staff must give a reason for a CK
`Config.Presets.Enabled`	`true`	Appearance presets
`Config.Presets.Max`	`6`	Presets per account

Approval and name changes

Key	Default	Description
`Config.Approval.Enabled`	`false`	New characters wait for staff approval before the first spawn
`Config.Approval.NotifyStaff`	`true`	Online staff get a notification
`Config.NameChange.Enabled`	`true`	Players can request a new name from the character card
`Config.NameChange.ReasonRequired` / `MaxReason`	`true` / `300`	Reason field
`Config.NameChange.ShowDeniedDays`	`7`	How long a denied request stays visible

set kmc_webhook_approval "https://discord.com/api/webhooks/..." posts new characters waiting for approval.

Appearance

Key	Default	Description
`Resource`	`'auto'`	Tries koja-appearance / illenium-appearance, fivem-appearance, then qb-clothing and esx_skin. Or set a resource name
`AllowPedChange`	`false`	New characters can pick any ped model in the editor
`ForceSave`	`true`	The editor reopens until the player saves
`Menu`	all `true`	Editor sections for new characters: `headBlend`, `faceFeatures`, `headOverlays`, `components`, `props`, `tattoos`

Scene

Key	Default	Description
`Random`	`true`	Random location each time, otherwise the first one
`Lineup`	`false`	All characters stand next to each other and the camera slides between them
`LineupSpacing`	`1.15`	Distance between characters in the line-up
`Hour`, `Weather`	`19`, `'EXTRASUNNY'`	Default time and weather. A location can override them
`Camera`		`Distance`, `MinDistance`, `MaxDistance`, `Height`, `Side`, `LookHeight`, `Fov`, `Interp` (ms)
`Scenarios`	5 scenarios	Random idle scenarios for the preview characters
`Locations`	Vinewood Hills, Michael's House	`{ label, ped = vec4(...), hour?, weather? }`. `ped` is where the character stands, the camera is placed in front of it
`AutoFrame`	`true`	Snaps the character to the ground and turns it in 45° steps when a wall blocks the camera or the walk path

Opening shot

shared/config.lua

Intro = {
    Enabled = true,
    Duration = 3200,
    Distance = 7.5,
    Side = 2.5,
    Height = 2.2,
},

The camera starts wide (Distance, Side and Height are added to the normal pose) and glides in over Duration ms.

Character switch cutscene

shared/config.lua

Transition = {
    Enabled = true,
    WalkDistance = 2.8,
    WalkSpeed = 1.0,
    ExitTime = 2600,
    CameraOut = 700,
    CameraIn = 1900,
    CameraWide = 1.2,
    CameraSwing = 1.1,
    CameraRise = 0.2,
    Gestures = {
        { dict = 'clothingshirt', anim = 'try_shirt_positive_d' },
        { dict = 'clothingtie', anim = 'try_tie_positive_a' },
        { dict = 'clothingspecs', anim = 'try_glasses_positive_a' },
        { dict = 'anim@mp_player_intupperthumbs_up', anim = 'idle_a' },
    },
},

Key	Description
`Enabled`	`false` swaps characters instantly
`WalkDistance`, `WalkSpeed`	How far and how fast the new character walks in
`ExitTime`	Ms before the old character is removed
`CameraOut`, `CameraIn`	Ms for the camera to swing out and back
`CameraWide`, `CameraSwing`, `CameraRise`	How far the camera pulls back, moves sideways and rises during the swing
`Gestures`	Animations the new character plays on arrival, one picked at random. A missing animation is skipped

Scene per character

shared/config.lua

PerCharacter = {
    Enabled = true,
    Fade = 450,
    Jobs = {
        police = { label = 'Mission Row PD', ped = vec4(428.23, -984.28, 30.71, 3.5), hour = 21 },
        ambulance = { label = 'Pillbox Hospital', ped = vec4(298.6, -584.5, 43.26, 70.0), hour = 18 },
        mechanic = { label = 'Benny\'s', ped = vec4(-205.62, -1310.66, 31.29, 0.0), hour = 17 },
    },
    Gangs = {},
},

Single mode only; the line-up keeps one location. A sceneLocation hook (houses, motels) wins over Jobs and Gangs. Characters without a match use Locations. Fade is the fade time in ms when the scene moves.

Car in the scene

Key	Default	Description
`Vehicle.Enabled`	`true`	Shows one of the character's owned vehicles behind them (`owned_vehicles` on ESX, `player_vehicles` on QB)
`Vehicle.Pick`	`'best'`	`'best'` (class, then top speed) or `'first'`
`Vehicle.Candidates`	`6`	How many owned vehicles are sent to the client to pick from
`Vehicle.Back`, `Vehicle.Side`	`3.4`, `1.3`	Position behind the character in metres. Skipped when the spot is blocked

Seasons

Key	Description
`Seasons.Enabled`	Seasonal scenes
`Seasons.Force`	Season name to force (for testing), `nil` = by date
`Seasons.List`	`{ name, from = 'MM-DD', to = 'MM-DD', weather, hour?, snow?, music?, props = { { model, offset = vec3(right, forward, up), heading } } }`. Winter (`12-01` to `01-06`) and Halloween (`10-20` to `11-03`) ship by default

Audio

Key	Default	Description
`Config.Audio.Enabled`	`true`	All sounds and music
`Volume`, `MusicVolume`	`0.6`, `0.22`	0..1
`Music`	`true`	Default for players who never touched the music toggle
`Sounds`	15 sounds	Sound name to file in `web/build/sounds` (`false` turns one off)
`Tracks`	`default`, `winter`, `halloween`	Music per season `music` key

Players mute sounds and music with the two buttons in the top bar. The choice is saved on their PC.

Arrival

Key	Description
`Config.Arrival.Enabled`	Plays the arrival cutscene on a new character's first spawn at `NewCharacterSpawn`
`Mode`	`'plane'` or a name registered with `RegisterArrival`
`Skippable`	SPACE / ENTER skips
`Plane`	`Model`, flight `Heading`, `Length`, `StartHeight` and `EndHeight` above the spawn, `Duration` ms, `CameraBack`, `CameraHeight`
`Walk`	The character walks `Distance` m to the spawn point over `Duration` ms. Camera `CameraDistance` in front, `CameraHeight` up

Party

Key	Default	Description
`Config.Party.Enabled`	`true`	Party button in the selection
`MaxSize`	`6`	Members per party
`CodeLength`	`5`	Length of the join code
`SpawnDistance`	`1.6`	Distance from the party member when spawning next to them

Spawn

Key	Default	Description
`Selector`	`true`	Show the spawn selector, otherwise spawn at the last location
`UseKojaSpawnSelector`	`true`	When koja-spawnselector is started, use its map instead of the built-in screen
`NewCharacterSelector`	`false`	New characters also pick a spawn, otherwise they go to `NewCharacterSpawn`
`NewCharacterSpawn`	airport	Where new characters arrive
`LastLocation`	`true`	Offer the last location
`AllowBack`	`true`	Back button from the spawn selector to the characters
`TriggerPlayerSpawned`	`false`	Also fires the classic `playerSpawned` event
`Camera`		Sky camera `Height`, `Back`, `Interp` and `Fov`
`Protection`	10 s	`Enabled`, `Duration` (s), `Ghost`, `Invincible`, `DisableFiring`, `Alpha`

Spawn points in shared/spawns.lua use the same fields as the RegisterSpawn export.

Relog

Key	Default	Description
`Enabled`, `Command`	`true`, `'relog'`	The switch character command
`Cooldown`	`60`	Seconds after spawning before switching is allowed
`CombatSeconds`	`30`	Blocks switching for this long after damage was dealt or taken
`BlockWhenDead`, `BlockInVehicle`	`true`, `true`	Extra checks
`Progress`	`3000`	Progress bar length in ms. `0` is instant

Other

Key	Default	Description
`Config.Bucket.Enabled / Offset`	`true` / `5000`	Private routing bucket (`Offset + server id`) while choosing
`Config.Playtime.SaveInterval`	`300`	Seconds between playtime saves
`Config.StarterItems`	phone, water, bread	Items given to a new character on first spawn
`Config.Esx.Prefix`	`'char'`	ESX character prefix, `char1:license`
`Config.Esx.AutoResizeColumns`	`true`	Widens `identifier` / `owner` columns so the prefix fits
`Config.Admin`		Groups, ACE and command names, see Commands

Configuration

Configuration#

General#

Theme / UI colours#

Slots#

Identity#

Delete, trash, CK and presets#

Approval and name changes#

Appearance#

Scene#

Opening shot#

Character switch cutscene#

Scene per character#

Car in the scene#

Seasons#

Audio#

Arrival#

Party#

Spawn#

Relog#

Other#

Configuration

General

Theme / UI colours

Slots

Identity

Delete, trash, CK and presets

Approval and name changes

Appearance

Scene

Opening shot

Character switch cutscene

Scene per character

Car in the scene

Seasons

Audio

Arrival

Party

Spawn

Relog

Other