Multicharacter
Configuration
The options of config.lua and config_server.lua.
Two plain-text files: config.lua (replicated to clients, no secrets) and config_server.lua (server only, never sent to clients). Invalid values are reported by gmc selftest.
#config.lua
| Key | Default | What it does |
|---|---|---|
Config.Locale | 'it' | 'it' or 'en' (more files in locales/ are picked up automatically) |
Config.Framework | 'auto' | 'auto', 'esx', 'qbcore', 'qbox' |
Config.Debug | false | Extra logging |
Config.Modules | all true | select, identity, spawn, pause: each can be turned off. With select = false players join with their last character |
Config.Rpc.clientTimeoutMs | 25000 | Client to server call timeout. Must be at least Config.ESX.joinTimeoutMs + 5000 (checked by the selftest) |
#Theme
Config.Theme = {
accent = '#5AD1FF', -- hex #RRGGBB
radius = 'cut', -- 'cut' | 'round' | 'square'
scale = 1.0, -- 0.85 - 1.25
contrast = 'normal', -- 'normal' | 'high'
font = 'archivo', -- 'archivo' | 'inter' | 'system'
logo = '', -- file in web/public
serverName = 'Ghiaccio',
}#Selection
Config.Select = {
autoPlay = false, -- true: skip the selection and play the last character
showDetails = true,
skipIntro = false,
alwaysAvailable = true, -- selection stays reachable even with Modules.select = false (via /relog)
command = 'personaggi', -- command to return to the selection ('' = none)
bucketBase = 5000, -- private routing bucket during selection/identity: bucketBase + server id
}#Scenes
Config.Scenes: selectScene (selection scene), studioScene (identity photo set), maxPeds (characters in the scene, max 10), quality, debug, introMs. The scenes themselves (position, time, weather, lights, formation) live in data/scenes.json and are reloaded with /gmc reload.
#Identity
Config.Identity = {
fields = { nationality = true, backstory = true, height = true },
nameMin = 2, nameMax = 20,
ageMin = 16, ageMax = 90,
heightMin = 140, heightMax = 220,
defaultHeight = 175,
dateFormat = 'DD/MM/YYYY', -- 'DD/MM/YYYY' | 'MM/DD/YYYY' | 'YYYY-MM-DD'
nationalities = 'free', -- 'free' or a list { 'Italian', 'American', ... }
uniqueNames = true, -- name + surname unique across all characters
blockedWords = {},
backstoryMax = 500,
photo = { enabled = true, transparent = true, timeoutMs = 4000 },
}#Appearance
Config.Appearance = {
adapter = 'auto', -- see Installation
previewMode = 'auto', -- 'auto' | 'ped' | 'player' | 'monogram'
forceCreatorOnNew = true,
defaultOutfits = { m = {}, f = {} },
}previewMode: if the script cannot dress a ped other than the player (esx_skin), the resource uses the player itself, hidden in their private bucket. The creator runs in the player's private routing bucket; bucket 0 is restored when the creator closes or on spawn.
#Spawn
Config.Spawn: mode, points (locations, with job / gang / ACE filters), first spawn, last position. onlyNewCharacter = true (default): the selector only appears on the first spawn of a newly created character; later logins enter at the last saved position. false = selector on every join. The aerial camera sits camera.height metres up (auto = 500, max 1500).
#Pause menu
Config.Pause = {
keyP = 'menu', -- 'menu' (our menu) | 'map' (native map)
portrait = true,
links = {}, -- { { label = 'Discord', url = 'https://...' } }
rules = '',
interceptMode = 'auto', -- 'auto' | 'controls' | 'frontend' | 'native'
block = { dead = true, cuffed = true, inVehicle = false, ragdoll = false, cutscene = true, ... },
blockedAction = 'ignore', -- 'ignore' | 'native'
changeCharacter = { cooldownSec = 300, blockIfDead = true, blockIfCuffed = true,
blockIfDamagedWithinSec = 60, blockInVehicle = true, allowedAce = nil },
}The pause menu shows the character card and server info with live data (money, job, hours, players, ping, time; light polling only while open) and has quick actions with shortcuts (M map, I server, S settings, G GTA settings, K keys, R relog, D disconnect). Player settings (scale, accent, language, audio...) apply instantly and are saved in KVP.
#Relog
Config.Relog = {
enabled = true,
command = 'relog', -- '' = no command
key = '', -- optional key, e.g. 'F10' (RegisterKeyMapping)
keyMapper = 'keyboard',
countdownSec = 5, -- seconds the ped stays frozen before the relog (1..60)
cooldownSec = nil, -- nil = Config.Pause.changeCharacter.cooldownSec
}The old confirm / confirmSec are inert. Config.Pause.changeCharacter.enabled no longer exists (an old value is ignored): the relog is the only way back to the selection and is turned off only by Config.Relog.enabled. The server owns the countdown: the client cannot shorten it. See Commands.
#Transition, loadscreen, loading
| Key | Default | Description |
|---|---|---|
Config.Transition.fadeOutMs | 750 | Fade out (400..1500) |
Config.Transition.fadeInMs | 700 | Fade in (300..1500) |
Config.Transition.sceneWaitMs | 3500 | Longest wait for the scene on a black screen |
Config.Loadscreen.watchdogSec | 90 | The loadscreen closes anyway after this many seconds (10..600) |
Config.Loading.music / .ambient | disabled | enabled, file (in web/public, then rebuild the UI), volume, fades. music.duringSelect = true |
#config_server.lua
| Key | Default | Description |
|---|---|---|
Config.Slots.default | 1 | Base slots of every new account |
Config.Slots.max | 8 | Absolute cap (max 15) |
Config.Slots.showLocked | true | With unlockUrl: show at most ONE locked slot (the next to unlock) |
Config.Slots.unlockUrl | '' | Tebex link of the "Unlock" button |
Config.Slots.rules | {} | ACE rules, e.g. { { ace = 'group.vip', add = 1 }, { ace = 'tebex.gold', add = 2 } } |
Config.Slots.stack | 'sum' | 'sum' or 'max' |
Config.ESX.prefix | 'char' | Same as esx_multicharacter: existing char1:<license> characters show up by themselves |
Config.ESX.widenColumns | true | Widen the identifier / owner varchar columns like esx_multicharacter did |
Config.ESX.joinTimeoutMs | 15000 | ESX character load timeout |
Config.Staff.command | 'gmc' | Staff command name |
Config.Staff.confirmTimeoutSec | 60 | Time to confirm a destructive action |
Config.Staff.groups | { admin = {}, mod = {} } | Framework groups for people without ACE |
Config.Backup.retentionDays | 14 | Backup retention |
Config.Wipe | see file | What a wipe resets (money, inventory, job, position, vehicles, starting money, extra tables) |
Config.DeleteExtraTables | {} | Extra tables cleaned on delete |
Config.Logging | console + db, 180 days | Webhook only via convar set ghiaccio_mc:webhook "https://..." |
On a server that is already running, no existing character is ever locked by the default: until staff sets the base, an account's slots are at least its characters. Characters are locked only with /gmc char lock (or /gmc slots remove|set, with confirmation).
#UI build
The UI (web/dist) is prebuilt. Rebuild it only if you change web/src or web/public: cd web && npm install && npm run build.