Skip to content

Using the built‐in API

Jump to bottom
Heliumdioxid edited this page Jul 14, 2026 · 6 revisions

Get a player's biometric data (server-only)

Fingerprints are uniquely generated strings for each player that look like "CBFEE5589A51C081". The API function returns this fingerprint string and generates a new one if the player does not already have one.

exports.evidences:getFingerprint(playerId)

A player's DNA is also a uniquely generated string from the letters T, G, C and A representing the four nucleotide bases (e.g. "TGGTTAGGGACGATAT"). The API function returns the player’s DNA string and generates a new one if the player does not already have one.

exports.evidences:getDNA(playerId)

Listen to analysation of an evidence item (server-only)

AddEventHandler("evidences:evidenceItemAnalysed", function(playerId, item)
    -- do something
end)

Create or delete evidences (and implement custom scenarios)

All api interactions are executed through a single entry point:

-- Use this export to create or delete evidences on server side:
---@param evidenceType Evidence|string The class of the evidence or the name of that class (by default "fingerprint", "blood", "saliva", "magazine")
---@param owner number|string The serverId of the related player or the owner of the evidence (fingerprint, dna key, weapon serial number)
---@param fun string The name of the function you want to execute (You can see all available functions below)
---@param ... any The arguments passed to this function
exports.evidences:syncEvidence(evidenceType, owner, fun, ...)

-- On client side you can trigger this event to create or delete evidences:
TriggerServerEvent("evidences:syncEvidence", evidenceType, owner, fun, ...)

Look at here for some usage examples:

Bind the evidence to an entity

You can bind the evidence to an entity. It can be destroyed or collected by targetting the entity. While destroying the evidence triggers the removeFromEntity() function, collecting the evidence also transfers it to an item created for that purpose.

---@param entity number The netId of the entity the evidence should be bound to
---@param metadata? table
exports.evidences:syncEvidence(evidenceType, owner, "atEntity", entity, metadata)
exports.evidences:syncEvidence(evidenceType, owner, "removeFromEntity", entity)

Bind the evidence to a vehicle seat

You can bind the evidence to a seat of a vehicle. Targetting the evidence requires the player to sit on this seat inside the vehicle.

---@param vehicle number The netId of the vehicle the evidence should be bound to
---@param seatId number The id of the seat (look at https://docs.fivem.net/natives/?_0x22AC59A870E6A669 for a list of seat indices)
---@param metadata? table
exports.evidences:syncEvidence(evidenceType, owner, "atVehicleSeat", vehicle, seatId, metadata)
exports.evidences:syncEvidence(evidenceType, owner, "removeFromVehicleSeats", vehicle, seatIds)

Bind the evidence to a vehicle door

You can bind the evidence to a door of a vehicle. If 0 < vehicle door count ≤ 4 targetting the evidence requires the player to look at exactly that door otherwise targetting the vehicle is sufficient.

---@param vehicle number The netId of the vehicle the evidence should be bound to
---@param doorId number The id of the door (look at https://docs.fivem.net/natives/?_0x93D9BD300D7789E5 for a list of door indices)
---@param metadata? table
exports.evidences:syncEvidence(evidenceType, owner, "atVehicleDoor", vehicle, doorId, metadata)
exports.evidences:syncEvidence(evidenceType, owner, "removeFromVehicleDoors", vehicle, doorIds)

Bind the evidence to a player

Binds the evidence to a player. It can be destroyed or collected by targetting the player. While destroying the evidence triggers the removeFromPlayer() function, collecting the evidence also transfers it to an item created for that purpose.

---@param playerId number The serverId of the player the evidence should be bound to
---@param metadata? table
exports.evidences:syncEvidence(evidenceType, owner, "atPlayer", playerId, metadata)
exports.evidences:syncEvidence(evidenceType, owner, "removeFromPlayer", playerId)

Bind the evidence to the ground

You can create an collectable evidence at specific coords. While destroying the evidence triggers the removeFromCoords() function, collecting the evidence also transfers it to an item created for that purpose.

---@param coords vector3 The coords of for that evidence
---@param metadata? table
exports.evidences:syncEvidence(evidenceType, owner, "atCoords", coords, metadata)
exports.evidences:syncEvidence(evidenceType, owner, "removeFromCoords", coords)

Bind the evidence to coords relative to an entity

Binds the evidence to a relative position of an entity. It can be destroyed or collected by targetting the location on the entity. While destroying the evidence triggers the removeFromRelativeEntityCoords() function, collecting the evidence also transfers it to an item created for that purpose.

---@param entity number The netId of the entity the evidence should be bound to
---@param coords vector3 The relative coords of the evidence on the entity
---@param metadata? table
exports.evidences:syncEvidences(evidenceType, owner, "atRelativeEntityCoords", entity, coords, metadata)
```

#### Bind the evidence to an item
You can bind the evidence to an item. Items can hold only one evidence of each type at a time. The currently stored evidence of this type on the item is overwritten. **Items holding evidences are listet in the DNA and Fingerprint Analysis App on the evidence laptop.** Items holding magazine type evidences are labeled with some of the given data.
```lua
---@param inventory table|string|number The inventory of the item holding the evidence (cf. https://coxdocs.dev/ox_inventory/Functions/Server#additem)
---@param slot number The slot of the item in the inventory
---@param data? table
exports.evidences:syncEvidence(evidenceType, owner, "atItem", inventory, slot, data)
exports.evidences:syncEvidence(evidenceType, owner, "atLastUsedItemOf", playerId, data) -- Binds the evidence to the last item a player used
exports.evidences:syncEvidence(evidenceType, owner, "atWeaponOf", attacker, data) -- Binds the evidence to the current weapon of a player

exports.evidences:syncEvidence(evidenceType, owner, "removeFromItem", inventory, slot)
```

<br>

### Create your own evidence type
You can even create your own evidence type, although this requires a little more effort:
1. Navigate to `server/evidences/classes/` (and if the new evidence type is based on DNA `dna/`) and create a new lua-file with the name of your evidence type. Note: Only DNA and fingerprint based evidences can be analyzed in the evidence laptop!
4. Add the following template code to the newly created file, read the comments and fill all placeholders:
    ```lua
    -- The parent class is located at server/evidences/classes/evidence
    -- or server/evidences/classes/dna/dna if this evidence type is based on DNA
    local parentClass <const> = require "path to the parent class"

    local evidenceType = lib.class("EVIDENCE_TYPE", parentClass)
    evidenceType.superClassName = "EVIDENCE_TYPE" -- or "DNA"
    
    function evidenceType:constructor(owner)
        self:super(owner)
    end
    
    return evidenceType
    ```
5. Navigate to `server/evidences/api.lua`. Add your newly created file to this list:
    ```lua
    7     api.evidenceTypes = {
    8         fingerprint= require "server.evidences.classes.fingerprint",
    9         blood= require "server.evidences.classes.dna.blood",
    10        saliva = require "server.evidences.classes.dna.saliva",
    11        magazine = require "server.evidences.classes.magazine",
              -- register your new evidence type here, e.g.
              -- eivdenceType = require "server.evidence.classes.(dna.)evidence_type"
    12    }
    ```
6.  Finally, you have to register your evidence_type at `/common/evidence_types.lua`. There you can choose messages, conditions for collecting and destroying evidences and decide how your evidence should be visualized when created "atCoords".

Clone this wiki locally