# Installation

> Setup guide for ML Trap

Category: TRAP · Source: https://miciomods.it/docs/ml-trap-installation · Last updated: 2026-07-28

## Overview

ML Trap adds placeable snap traps and cage traps that lure, hold and kill wild animals, with optional player capture. Traps persist through restarts in the database. The interaction panel and the floating in-world tag are rendered in the game.

## Quick Start

1. Download from [CFX Portal](https://portal.cfx.re)
2. Extract to your `resources` folder as `ml_trap`
3. Add to `server.cfg`:

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ml_bridge
ensure ml_trap
```

> **WARNING:** Load Order
>
> `ml_trap` must start AFTER `ml_bridge`.

## Stream Assets

The trap, cage and bait models ship in the resource `stream/` folder and load automatically. No manual import is required.

## Database

The persistence table is created automatically on first start:

`ml_traps`: Stores persistent traps: type, owner, position, state, bait, capture and durability

Traps are persistent by default and saved to this table. Set persistent to false on a trap type to keep it in memory only.

> **TIP:** Manual Provisioning
>
> `_INSTALL/schema.sql` contains the same table if you prefer to create it by hand or disable automatic schema init.

## Item Registration

Register the following items in your inventory. The defaults live in `_INSTALL/items.lua`, ready to copy.

- `snap_trap`: Walk-on ground trap
- `cage_trap_small`: Small cage trap
- `cage_trap_large`: Large cage trap
- `meat_bait`: Lures carnivores and omnivores
- `vegetable_bait`: Lures herbivores
- `white_meat_bait`: Lures scavengers and small predators
- `rope`: Repair material
- `wood`: Repair material
- `metal_scrap`: Repair material

Item names are configurable in `Config.TrapTypes`. Any rename here must match the inventory item and, for existing servers, the `trap_type` and `bait_type` values stored in `ml_traps`.

> **INFO:** Item Images
>
> Ready-made icons ship in `_INSTALL/images`, named to match the item keys. Copy them into your inventory image folder (for ox_inventory that is `ox_inventory/web/images`). The panel falls back to a generic icon when an image is missing.

## Verify

Place a snap trap item from the inventory, then place it in the world. The trap prop appears with its interaction option, and a floating tag shows above it.

To confirm persistence, place a cage trap and check that a row appears in `ml_traps`.

**Troubleshooting**

- No interaction on the trap: Confirm `Config.InteractionMethod` matches an available target system, or switch to `'textui'`.
- Trap items do nothing when used: The item name in the inventory does not match a key in `Config.TrapTypes`.
- Cage traps disappear on restart: `Config.Persistence.enabled` is `false`, or oxmysql is not running.
- Animals ignore the bait: The bait `animals` list does not include the species spawning near the trap, or the bait expired.