Configuration

Every option in uz_MugShot's config.lua, from framework detection to capture timing and chroma key tuning.

All settings live in config.lua. The defaults are tuned for most servers; you usually only need Config.Framework and the admin ACE.

General

Setting	Default	Description
`Config.Framework`	`'auto'`	`'auto'`, `'qbox'`, `'qbcore'` or `'esx'`
`Config.AdminCommand`	`'remugshot'`	Name of the admin retake command
`Config.Compat.size`	`128`	Size of the photo `GetMugShotBase64` returns. `512` returns the full photo
`Config.Debug`	`false`	Prints why captures waited or were skipped, and keeps the unkeyed screenshot as `mugshot.raw.png`

Photo

Setting	Default	Description
`Config.Studio.coords`	`vector3(0.0, 0.0, -150.0)`	Where the studio is built, far below the map
`Config.Variants.mugshot`		Camera framing: `fov`, `dist`, `zPos` (height), `angleH`, `roll` and `facialMood`
`Config.Lighting`	4 lights	Studio lights. Each has an `offset` from the ped (`-Y` camera side, `+Y` behind, `+Z` up), `range`, `intensity` and `r`, `g`, `b`
`Config.OutputSize`	`512 × 512`	Size of the saved PNG

Every photo uses the same framing and lighting, so mugshots look consistent across the server.

Automatic Capture

Config.FingerprintWatch = {
    enabled = true,
    intervalMs = 1000,  -- how often the look is checked
    settleMs = 4000,    -- changes made outside a menu must hold this long
    retryMs = 15000,    -- resend a check the server did not answer
}

Changes made inside a menu are checked as soon as the menu closes. enabled = false leaves only the trigger events below.

Config.CaptureGuard = {
    settleMs = 0,       -- extra wait after a menu, camera or fade is gone
    timeoutMs = 60000,  -- give up after this long, the watch tries again later
}

Trigger Events

Optional. A listed save event runs the check right away instead of waiting for the watch.

Config.NaturalTriggers = {}          -- client events

Config.ServerNaturalTriggers = {     -- server events, relayed to the client that fired them
    'illenium-appearance:server:saveAppearance',
    'fivem-appearance:server:saveAppearance',
    'qb-clothing:saveSkin',
    'esx_skin:save',
}

Setting	Default	Description
`Config.NaturalTriggerCurtain`	`true`	Show the curtain during automatic captures
`Config.InitialCapture.enabled`	`true`	Accept `TriggerInitialCapture` calls
`Config.InitialCapture.delaySeconds`	`1`	Wait before the login check runs
`Config.RateLimitMs`	`5000`	Minimum time between automatic captures of the same character

Timing

Setting	Default	Description
`Config.Timing.streamingWait`	`30`	Milliseconds to let the clone's clothing stream in
`Config.Timing.stabilizationFrames`	`1`	Frames to wait before the screenshot
`Config.Timing.hatSettleFrames`	`8`	Extra frames when the character wears a hat, so hair is tucked under it
`Config.Timing.curtainFadeIn`	`50`	Milliseconds for the curtain to fade in
`Config.Timing.captureTimeout`	`10000`	Maximum wait for screenshot-basic

If clothing sometimes appears half-loaded in photos on a server with many streamed assets, raise streamingWait (for example to 150).

Performance & Limits

Setting	Default	Description
`Config.Queue.maxConcurrent`	`2`	Photos processed on the server at the same time
`Config.CacheMaxMB`	`64`	Memory budget for cached photos (one photo is about 0.2-0.3 MB)
`Config.RequestLimit.burst`	`20`	Photo requests a player can make at once (character selector, MDT list)
`Config.RequestLimit.perSecond`	`4`	How fast that budget refills
`Config.InputLimits`		Uploaded screenshots larger than these are rejected before decoding

Chroma Key

Config.ChromaProcessing = {
    threshold = 60,         -- distance to pure magenta that becomes transparent
    feather = 2,            -- width of the soft edge band (x20)
    matteSoftenRadius = 1,  -- edge blur, 0 disables it
    edgeResidual = 16,      -- cleans the magenta tint on the outer edge, 0 disables it
}

Raising feather gives softer edges but starts eating colours close to magenta, such as neon pink clothing. Lowering it does the reverse. With Config.Debug = true the unkeyed screenshot is kept so you can tune against real captures.