Exports & Events

Server and client exports and events for showing uz_MugShot photos in MDTs, ID cards, phones and character selectors.

Every export returns a base64 data:image/png;base64,... string that goes straight into an <img src> in your NUI, or nil when there is no photo yet. Show your own placeholder in that case.

Add uz_MugShot to your script's dependencies in fxmanifest.lua to make sure it starts first:

dependencies { 'uz_MugShot' }

Server Exports

GetPhotoDataURI

Returns the stored photo of a character.

local uri = exports['uz_MugShot']:GetPhotoDataURI(identifier)

Parameter	Type	Description
`identifier`	string \| number	`citizenid` (Qbox / QBCore), `identifier` (ESX) or a player's server ID

Works for offline characters too when you pass the citizenid.

HasPhoto

Returns true when the character has a stored photo.

if exports['uz_MugShot']:HasPhoto(citizenid) then
    -- ...
end

CaptureAndReturn

Takes a new photo right now and returns it once it is processed. Use it when an item needs a fresh photo, such as an ID card being issued.

local uri = exports['uz_MugShot']:CaptureAndReturn(identifier, opts, timeoutMs)

Parameter	Type	Description
`identifier`	string \| number	citizenid / identifier or server ID of an online player
`opts`	table?	`{ curtain = false }` hides the curtain during the shot (shown by default)
`timeoutMs`	number?	Maximum wait, default `15000`

Blocks until the photo is ready. Returns nil if the player is offline or the capture times out.

local uri = exports['uz_MugShot']:CaptureAndReturn(citizenid)
if uri then
    item.metadata.image = uri
end

ForceRecapture

Retakes the photo in the background without waiting for it. Returns true if the capture was dispatched.

exports['uz_MugShot']:ForceRecapture(identifier)

Use it after changes the fingerprint cannot see, such as a tattoo-only change (GTA has no getter for ped decorations).

TriggerInitialCapture

Optional. Call it from your spawn completion hook once the player is really in the world. The fingerprint watch already covers login; this only skips its settle time.

exports['uz_MugShot']:TriggerInitialCapture(source)

-- or as an event
TriggerEvent('uz_mugshot:initialCapture', source)

Captures only when the character has no photo or the look changed while offline, so it is safe to call on every login. Duplicate calls for the same character in one session are ignored. uz_Multicharacter already calls it.

Client Exports

Client exports wait for the server's answer, so call them from a thread, an event handler or an NUI callback, not from the top level of a file. Requests are rate limited per player (Config.RequestLimit).

GetPhotoDataURI

local uri = exports['uz_MugShot']:GetPhotoDataURI(ped)

Parameter	Type	Description
`ped`	number	A player ped entity, for example `PlayerPedId()` or `GetPlayerPed(id)`

Returns nil for NPC peds.

GetPhotoByCitizenId

local uri = exports['uz_MugShot']:GetPhotoByCitizenId(citizenid)

For screens where the character has no ped yet, such as a multicharacter selector.

GetMugShotBase64

Compatibility export for scripts written for MugShotBase64. Prefer GetPhotoDataURI in new code.

local uri = exports['uz_MugShot']:GetMugShotBase64(ped, transparent)

Returns the stored photo scaled to Config.Compat.size (128×128 by default). Peds without a photo get GTA's native headshot, and an empty string if that fails. Never returns nil. transparent is ignored.

Events

uz_mugshot:captured

Server event, fired after a new photo is saved and cached. A GetPhotoDataURI call right after it returns the new image.

Argument	Type	Description
`citizenid`	string	Character whose photo changed
`variant`	string	Always `'mugshot'`

Live Updates

If your UI can already be open when a photo is retaken (an officer viewing an MDT profile while the suspect visits the barber), refresh it from the uz_mugshot:captured event:

-- server side of your resource
AddEventHandler('uz_mugshot:captured', function(cid)
    local uri = exports['uz_MugShot']:GetPhotoDataURI(cid)
    TriggerClientEvent('my_mdt:photoUpdated', -1, cid, uri)
end)

// NUI side
window.addEventListener('message', (e) => {
    if (e.data.action === 'photoUpdated' && e.data.cid === currentCitizen) {
        document.getElementById('mugshot').src = e.data.uri
    }
})

If your UI fetches the photo every time it opens, you don't need this. Photos baked into item metadata (ID cards, licenses) stay frozen on purpose, like a real ID card.

Exports & Events

On this page