> For the complete documentation index, see [llms.txt](https://cylexdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cylexdev.gitbook.io/docs/cylex_mdt/features/evidence-stash-and-forensics.md).

# Evidence Stash  & Forensics

\
 **Forensics** — field collection of blood pools and bullet casings, with lab processing that reveals DNA matches and weapon serial numbers. 

**Evidence Stashes** — physical lockers at precinct locations where officers deposit seized items and weapons tied to a specific case. Understanding the distinction is important: forensics happens at the crime scene and the lab, stashes happen at the precinct. Both feed into the same incident report.

### Forensics: field collection and lab processing <a href="#id-2e5053ff-62d4-49c3-b52f-18545dc4aaa3" id="id-2e5053ff-62d4-49c3-b52f-18545dc4aaa3"></a>

The forensics system tracks blood pools and bullet casings spawned automatically in the world when players are shot or fire weapons. Officers collect physical samples using evidence bags and submit them to the Forensic Lab for analysis. Results feed directly into the MDT's Forensics page and can be linked to an open incident report.

#### Evidence visibility <a href="#id-21c7374c-2cc6-4129-afc5-6b4c6e5fa4b8" id="id-21c7374c-2cc6-4129-afc5-6b4c6e5fa4b8"></a>

By default, evidence markers are only visible when you hold a flashlight (`weapon_flashlight`) and aim with the right mouse button. This makes evidence gathering feel deliberate and immersive. You can disable this restriction in `evidence_config.lua`:

```lua
-- true  → evidence only visible with weapon_flashlight + right mouse
-- false → all eligible officers always see evidence markers
EvidenceConfig.FlashlightMode = true
```

Evidence markers render within 25 metres of your position:

```lua
EvidenceConfig.RenderDistance = 25.0   -- metres
```

#### Evidence types and markers <a href="#id-3d97e500-f195-462c-ab95-d25edd1d4c9a" id="id-3d97e500-f195-462c-ab95-d25edd1d4c9a"></a>

| Type          | Marker color | Item received     |
| ------------- | ------------ | ----------------- |
| Blood pool    | Red          | `blood_evidence`  |
| Bullet casing | Yellow       | `casing_evidence` |

Blood pools spawn when a player is shot (100% chance by default, subject to a per-player cooldown). Bullet casings spawn near the shooter on each shot fired (25% chance by default). Both types disappear after 30 minutes if uncollected.

```lua
EvidenceConfig.SpawnChance = {
    blood  = 100,  -- every hit leaves blood
    casing = 25,   -- ~25% of shots leave a casing
}

EvidenceConfig.CooldownMinutes = {
    blood  = 2,
    casing = 2,
}

EvidenceConfig.RemoveTimer = {
    blood  = 30,  -- minutes
    casing = 30,
}
```

Jobs listed in `EvidenceConfig.ExemptJobs` do not leave blood when shot — useful for preventing on-duty officers from generating evidence at their own incidents. Jobs listed in `EvidenceConfig.CanCollectJobs` are the ones allowed to collect evidence in the field.

#### Collecting evidence <a href="#f9eb5fa9-d27d-40ab-94a6-077a5a9c5ec3" id="f9eb5fa9-d27d-40ab-94a6-077a5a9c5ec3"></a>

Walk within 1.5 metres of a marker and press **E** to collect. You must have an `empty_evidence_bag` in your inventory. On collection, the bag is consumed and you receive the corresponding evidence item.

```lua
EvidenceConfig.CollectionItem = 'empty_evidence_bag'   -- required to collect
EvidenceConfig.BloodItem      = 'blood_evidence'       -- received for blood
EvidenceConfig.CasingItem     = 'casing_evidence'      -- received for casings
EvidenceConfig.CollectDistance = 1.5                   -- metres
```

#### Processing at the Forensic Lab <a href="#fe2852fa-9db6-4a93-89b3-d4da77035e67" id="fe2852fa-9db6-4a93-89b3-d4da77035e67"></a>

After collecting evidence, travel to a `ProcessingLocation` and interact with the station. Processing takes 30 seconds by default, after which you receive a `processed_evidence` item and the result appears in the MDT.

```lua
EvidenceConfig.ProcessingTime = 30  -- seconds

EvidenceConfig.Evidence.ProcessingLocations = {
    {
        coords = vector3(443.51, -975.0, 30.69),
        label  = 'Forensic Lab',
        jobs   = {
            ['police']  = true,
            ['leo']     = true,
            ['sheriff'] = true,
            ['sandys']  = true,
            ['bcso']    = true,
            ['harmony'] = true,
            ['state']   = true,
            ['davison'] = true,
        },
    },
}
```

{% stepper %}
{% step %}

### Collect samples in the field

Equip a flashlight, aim, and walk up to a red (blood) or yellow (casing) marker. Press **E** with an `empty_evidence_bag` in your inventory.
{% endstep %}

{% step %}

### Travel to the Forensic Lab

Drive to a configured `ProcessingLocation`. The blue processing marker appears at 1.5 metres.
{% endstep %}

{% step %}

### Interact with the station

Press **E** to begin processing. Wait 30 seconds for the analysis to complete.
{% endstep %}

{% step %}

### Review results in the MDT

Open the **Forensics** page in the MDT. The record appears with full chain of custody.
{% endstep %}

{% step %}

### Link to an incident report

From the Forensics detail page — or from the incident report using the **Link Forensic Record** button — attach the lab result to your case.
{% endstep %}
{% endstepper %}

#### Lab results <a href="#id-91eac64d-1315-467b-81e7-7aac5b02558d" id="id-91eac64d-1315-467b-81e7-7aac5b02558d"></a>

| Evidence type | Result revealed                             |
| ------------- | ------------------------------------------- |
| Blood sample  | Citizen name and ID (DNA match)             |
| Bullet casing | Weapon serial number and ballistic analysis |

#### Chain of custody <a href="#id-55dfcf99-0d39-436b-b12e-38899e5927dd" id="id-55dfcf99-0d39-436b-b12e-38899e5927dd"></a>

Every forensic record tracks three timestamped stages visible on the Forensics MDT page:

1. **Collected** — officer and location recorded at time of field collection
2. **Submitted to Lab** — timestamp when the officer processed at the lab station
3. **Analysis Complete** — timestamp when results became available

#### Configuration reference <a href="#d400929e-7079-4cc6-968a-dfe4830aa8f6" id="d400929e-7079-4cc6-968a-dfe4830aa8f6"></a>

```lua
-- Flashlight requirement
EvidenceConfig.FlashlightMode = true

-- Drop probabilities (0–100)
EvidenceConfig.SpawnChance = {
    blood  = 100,
    casing = 25,
}

-- Per-player cooldown between drops (minutes)
EvidenceConfig.CooldownMinutes = {
    blood  = 2,
    casing = 2,
}

-- Time before uncollected evidence disappears (minutes, 0 = never)
EvidenceConfig.RemoveTimer = {
    blood  = 30,
    casing = 30,
}

-- Lab processing duration (seconds)
EvidenceConfig.ProcessingTime = 30

-- Render and interaction distances (metres)
EvidenceConfig.RenderDistance  = 25.0
EvidenceConfig.CollectDistance = 1.5
EvidenceConfig.ProcessDistance = 1.5

-- Item names
EvidenceConfig.CollectionItem = 'empty_evidence_bag'
EvidenceConfig.BloodItem      = 'blood_evidence'
EvidenceConfig.CasingItem     = 'casing_evidence'
EvidenceConfig.ProcessedItem  = 'processed_evidence'
```

<details>

<summary>Adding or removing forensic lab locations</summary>

Edit the `ProcessingLocations` table in `evidence_config.lua`. Each entry needs a `coords` vector3, a `label` string, and a `jobs` table listing which job names can use that location.

```lua
EvidenceConfig.Evidence.ProcessingLocations = {
    {
        coords = vector3(443.51, -975.0, 30.69),
        label  = 'Forensic Lab',
        jobs   = { ['police'] = true },
    },
}
```

</details>

<details>

<summary>Controlling which jobs leave blood or collect evidence</summary>

Set a job to `true` in `ExemptJobs` to prevent it from leaving blood. Set a job to `true` in `CanCollectJobs` to allow it to collect field evidence.

```lua
EvidenceConfig.ExemptJobs = {
    ['police']    = false,  -- police officers DO leave blood
    ['ambulance'] = true,   -- paramedics do NOT leave blood
}

EvidenceConfig.CanCollectJobs = {
    ['police']  = true,
    ['sheriff'] = true,
}
```

</details>