# Developer

> Developer API reference for ML Trap

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

## Overview

Integration happens through the `open/` folder. There are no exports. Each handler is a plain function with a default body; override it to extend or block a flow without touching the core. The handlers run on the side their file targets: `open/server.lua` on the server, `open/client.lua` on the client, `open/shared.lua` on both.

## Server Handlers

Located in `open/server.lua`.

### BeforeGiveItem

**open/server.lua**

```lua
function OpenServer.BeforeGiveItem(src, item, amount)
    return true
end
```

Fires before a trap is refunded to the player on pickup. Return `false` to block the give.

### BeforePlace

**open/server.lua**

```lua
function OpenServer.BeforePlace(src, trapTypeName, coords)
    return true
end
```

Fires after the core placement checks pass, before the trap is created. Return `false` to block placement.

### BeforeCapture

**open/server.lua**

```lua
function OpenServer.BeforeCapture(trap, targetModelHash, targetCitizenId)
    return true
end
```

Fires before a capture is finalized. `targetModelHash` is set for animal captures, `targetCitizenId` for player captures. Return `false` to reject the capture.

### OnActionComplete

**open/server.lua**

```lua
function OpenServer.OnActionComplete(src, actionType, trap)
end
```

Fires after any state change. `actionType` is one of `'place'`, `'bait'`, `'capture'`, `'kill'`, `'open'`, `'close'`, `'pickup'`, `'expire'`, `'break'`. `src` is `nil` for system events such as bait expiry.

> **WARNING:** Untrusted Capture
>
> `'capture'` and `'kill'` are reported by the client and are not proof an animal was present. If rewards are granted here, credit `trap.ownerCitizenId` rather than `src`, and add server-side checks of your own.

### OnCleanupDelete

**open/server.lua**

```lua
function OpenServer.OnCleanupDelete(trapId, trapRecord)
end
```

Fires when the cleanup scheduler removes an inactive persistent trap. `trapRecord` may be `nil` if the trap was already gone from memory.

## Client Handlers

Located in `open/client.lua`.

### Notify

**open/client.lua**

```lua
function OpenClient.Notify(message, type)
    Bridge.Notify(message, type)
end
```

Routes every notification. Override it to send notifications through a custom UI. `type` is `'info'`, `'success'`, `'warning'` or `'error'`.

### CanPlace

**open/client.lua**

```lua
function OpenClient.CanPlace(trapTypeName)
    return true
end
```

Fires before placement starts. Return `false` to cancel based on a custom condition such as a zone or job check.

### BeforeOpenMenu

**open/client.lua**

```lua
function OpenClient.BeforeOpenMenu(trapData)
    return true
end
```

Fires before the interaction panel opens. Return `false` to block it.

### AfterPlace / AfterCapture / AfterOpen / AfterKill

**open/client.lua**

```lua
function OpenClient.AfterPlace(trapData) end
function OpenClient.AfterCapture(trapData) end
function OpenClient.AfterOpen(trapData) end
function OpenClient.AfterKill(trapData) end
```

Each fires after the matching action resolves on the client, with the trap data. Use them to drive custom effects.

## Shared Handlers

Located in `open/shared.lua`.

### OnPlayerAction

**open/shared.lua**

```lua
function OpenHandlers.OnPlayerAction(src, data)
    return true
end
```

A generic guard the core calls on a player-initiated action. Return `false` to refuse. Use it for a server-wide block, for example during an event.

### ValidateAction

**open/shared.lua**

```lua
function OpenHandlers.ValidateAction(src, actionType)
    return true
end
```

Per-action validation called just before the action runs. `actionType` is `'place'`, `'bait'`, `'capture'`, `'kill'`, `'open'`, `'close'`, `'pickup'` or `'repair'`. Return `false` to silently refuse.

## Examples

**Block placement inside a safe zone**

**open/client.lua**

```lua
function OpenClient.CanPlace(trapTypeName)
    if InSafeZone(cache.ped) then
        OpenClient.Notify('You cannot place traps here.', 'error')
        return false
    end
    return true
end
```

**Reward the owner when an animal is killed**

**open/server.lua**

```lua
function OpenServer.OnActionComplete(src, actionType, trap)
    if actionType ~= 'kill' then return end
    local ownerSrc = GetSourceFromCitizenId(trap.ownerCitizenId)
    if ownerSrc then
        Bridge.GiveItem(ownerSrc, 'raw_meat', 1)
    end
end
```

**Disable all traps during an event**

**open/shared.lua**

```lua
function OpenHandlers.OnPlayerAction(src, data)
    return not EventActive
end
```