GhiaccioScripts

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

KeyDefaultWhat it does
Config.Locale'it''it' or 'en' (more files in locales/ are picked up automatically)
Config.Framework'auto''auto', 'esx', 'qbcore', 'qbox'
Config.DebugfalseExtra logging
Config.Modulesall trueselect, identity, spawn, pause: each can be turned off. With select = false players join with their last character
Config.Rpc.clientTimeoutMs25000Client to server call timeout. Must be at least Config.ESX.joinTimeoutMs + 5000 (checked by the selftest)

#Theme

lua
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

lua
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

lua
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

lua
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

lua
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

lua
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

KeyDefaultDescription
Config.Transition.fadeOutMs750Fade out (400..1500)
Config.Transition.fadeInMs700Fade in (300..1500)
Config.Transition.sceneWaitMs3500Longest wait for the scene on a black screen
Config.Loadscreen.watchdogSec90The loadscreen closes anyway after this many seconds (10..600)
Config.Loading.music / .ambientdisabledenabled, file (in web/public, then rebuild the UI), volume, fades. music.duringSelect = true

#config_server.lua

KeyDefaultDescription
Config.Slots.default1Base slots of every new account
Config.Slots.max8Absolute cap (max 15)
Config.Slots.showLockedtrueWith 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.widenColumnstrueWiden the identifier / owner varchar columns like esx_multicharacter did
Config.ESX.joinTimeoutMs15000ESX character load timeout
Config.Staff.command'gmc'Staff command name
Config.Staff.confirmTimeoutSec60Time to confirm a destructive action
Config.Staff.groups{ admin = {}, mod = {} }Framework groups for people without ACE
Config.Backup.retentionDays14Backup retention
Config.Wipesee fileWhat a wipe resets (money, inventory, job, position, vehicles, starting money, extra tables)
Config.DeleteExtraTables{}Extra tables cleaned on delete
Config.Loggingconsole + db, 180 daysWebhook 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.