Introduction
Automatic transparent player mugshots for FiveM. Captured in a chroma studio whenever the player's look changes, served to any script with one export.
Free & Open Source | Dependencies: screenshot-basic, yarn | License: Apache 2.0
uz-scripts/uz_MugShot
1
Overview
uz_MugShot takes a mugshot of every character and keeps it up to date. When a player changes clothes, visits the barber or finishes character creation, a clone of their ped is photographed in an underground chroma studio, the background is removed server-side, and the result is saved as a 512×512 transparent PNG. Any script (MDT, ID card, phone, multicharacter selector) gets the photo with a single export.
It works with any clothing, barber or skin script without adding code to it, and runs on Qbox, QBCore and ESX.
Why not GTA's headshot?
Most scripts get their photo from GTA's RegisterPedheadshot, directly or through MugShotBase64. uz_MugShot was built to replace that:
| Native headshot / MugShotBase64 | uz_MugShot | |
|---|---|---|
| Size | 64×64 from RegisterPedheadshot, the one MugShotBase64 uses. The hi-res and transparent variants give 128×128 | 512×512 |
| Background | Black. RegisterPedheadshotTransparent fails often (citizenfx/fivem#2611), and when it works it leaves a dark haze and a white outline. MugShotBase64's transparent mode loads a body-pix model in NUI on every call and cuts a hard on/off mask | Chroma studio, keyed on the server with soft edges |
| Framing | A tight head crop you cannot change | Camera, lights and framing set in config.lua, the same on every photo |
| When | Taken again on every call, waiting up to 2 seconds each time | Taken once when the look changes, served from disk after that |
| Whose | Only peds that exist on the calling client | Any character by citizenid, offline too, from client or server |
| Storage | None. Each script saves its own copy, which goes stale | One photo per character, uz_mugshot:captured fires when it changes |
Features
Installation
Download
Download uz_MugShot.zip from the latest release and put the uz_MugShot folder in your resources directory.
The folder must be named exactly uz_MugShot (case-sensitive on Linux). Other scripts call it as exports['uz_MugShot'], so under any other name the resource prints an error and stops. GitHub's Download ZIP button unpacks as uz_MugShot-main; rename it.
Grant the admin command
add_ace group.admin command.remugshot allowStart the Server
Node dependencies install automatically on first start through FiveM's built-in yarn. Photos are saved to shots/ inside the resource folder. No database setup.
Commands
| Command | Description |
|---|---|
/remugshot | Retake your own mugshot |
/remugshot [id] | Retake the mugshot of the player with that server ID |
The command is ACE-restricted. From the server console the ID is required (remugshot 5). The command name can be changed with Config.AdminCommand.
Replacing MugShotBase64
Remove MugShotBase64 from your resources and put uz_MugShot in its place. The manifest declares provide 'MugShotBase64' and ships a GetMugShotBase64(ped, transparent) client export, so existing calls keep working without changes.
-- Old call, still works
local b64 = exports['MugShotBase64']:GetMugShotBase64(ped, true)
-- Native call, full 512×512 photo, nil when there is none
local uri = exports['uz_MugShot']:GetPhotoDataURI(ped)What the compat export returns:
- Players with a stored photo get it scaled to
Config.Compat.size, 128×128 by default. That is twice the width of GTA's 64×64 headshot and keeps the string around 20 KB for scripts that save it in item metadata (the full photo is 160-270 KB, the original's headshot about 5 KB). Set it to64to match the original's size, or512for the full photo. - NPCs, preview peds and players not captured yet get GTA's native headshot, like the original. If that fails too, an empty string. Never
nil. - The
transparentflag is ignored. Stored photos are always transparent, the native fallback never is.