# Developer

> Developer API reference for ML LootProps

Category: LOOT PROPS · Source: https://miciomods.it/docs/ml-lootprops-developer · Last updated: 2026-07-05

## Overview

ML LootProps exposes server exports for reading prop and category data, and handler hooks in the `open/` folder for integration with other resources. Handlers return default values, override only the ones you need.

## Server Exports

**your_script/server.lua**

```lua
local config  = exports['ml_lootprops']:GetPropConfig(propHash)
local category = exports['ml_lootprops']:GetCategory('animals')
local allProps = exports['ml_lootprops']:GetAllProps()
local allCats  = exports['ml_lootprops']:GetAllCategories()
```

- `GetPropConfig(propHash)`: Returns the prop's config table, or `nil`
- `GetCategory(categoryId)`: Returns a category config, or `nil`
- `GetAllProps()`: Array of `{ hash, model }` for all configured props
- `GetAllCategories()`: Array of `{ id, label }` for all categories

## Server Handlers

Defined in `open/handlers_server.lua`.

### Loot Flow

**open/handlers_server.lua**

```lua
Handlers.OnBeforeClaim = function(source, propHash, coords, config)
    return true -- return false to block
end

Handlers.OnAfterClaim = function(source, propHash, coords, items, config)
end

Handlers.ModifyLoot = function(source, propHash, fixedLoots, probabilityLoots, config)
    return fixedLoots, probabilityLoots
end

Handlers.GetLootMultiplier = function(source, propHash, config)
    return 1.0 -- 2.0 = double loot
end

Handlers.GetBonusLoot = function(source, propHash, config)
    return nil -- return { {name='item', amount=1} } for extra items
end
```

- `OnBeforeClaim`: Called before loot is given. Return `false` to block the claim.
- `OnAfterClaim`: Called after items are distributed.
- `ModifyLoot`: Intercept and modify the loot tables before they roll.
- `GetLootMultiplier`: Multiply item amounts. `2.0` = double loot.
- `GetBonusLoot`: Return extra items to add on top of the normal loot.

### Cooldowns

**open/handlers_server.lua**

```lua
Handlers.GetCooldownOverride = function(source, propHash, baseCooldown, config)
    return nil -- return seconds to override
end

Handlers.CanBypassCooldown = function(source, propHash)
    return false -- true = skip cooldown
end
```

- `GetCooldownOverride`: Override the personal cooldown. Return seconds, or `nil` for the configured value.
- `CanBypassCooldown`: Return `true` to let the player skip the cooldown.

### Access Control

**open/handlers_server.lua**

```lua
Handlers.CanPlayerLoot = function(source, propHash, config)
    return true, nil -- false, 'reason' to block
end

Handlers.CanPlayerLootInArea = function(source, coords)
    return true, nil
end
```

- `CanPlayerLoot`: Gate access to a prop. Return `false` and a reason string to block.
- `CanPlayerLootInArea`: Gate access by coordinates, for territory checks.

### Dispatch

**open/handlers_server.lua**

```lua
Handlers.ShouldTriggerDispatch = function(source, propHash, config)
    return nil -- true/false to override, nil for default
end
```

- `ShouldTriggerDispatch`: Override the dispatch trigger. `nil` uses the default chance.

## Client Handlers

Defined in `open/handlers_client.lua`.

### Interaction

**open/handlers_client.lua**

```lua
Handlers.CanInteractWithProp = function(propHash, entity, coords)
    return true -- false hides the target
end

Handlers.GetCustomTargetLabel = function(propHash, entity, config)
    return nil -- string to override the label
end

Handlers.GetCustomTargetIcon = function(propHash, entity, config)
    return nil -- e.g. 'fas fa-skull'
end

Handlers.GetCustomTargetDistance = function(propHash, entity, config)
    return nil -- number to override the interaction distance
end

Handlers.AddCustomTargetOptions = function(propHash, entity, config)
    return {} -- extra target menu options
end
```

- `CanInteractWithProp`: Return `false` to hide the target option on a prop.
- `GetCustomTargetLabel`: Override the target label. `nil` keeps the default.
- `GetCustomTargetIcon`: Override the target icon. `nil` keeps the default.
- `GetCustomTargetDistance`: Override the interaction distance for a prop.
- `AddCustomTargetOptions`: Add extra options to the prop's target menu.

### Loot Lifecycle

**open/handlers_client.lua**

```lua
Handlers.CanLootProp = function(propHash, entity, config)
    return true, nil
end

Handlers.OnBeforeLoot = function(propHash, entity, config)
end

Handlers.OnAfterProgress = function(propHash, entity, config)
    return true -- false cancels the claim
end

Handlers.OnLootFailed = function(propHash, entity, reason)
end
```

- `CanLootProp`: Gate looting after interaction. Return `false` and a reason to block.
- `OnBeforeLoot`: Fires before the loot progress bar starts.
- `OnAfterProgress`: Fires after the progress bar completes. Return `false` to cancel.
- `OnLootFailed`: Fires when a loot attempt fails, such as a failed minigame.

### Prop Tracking

**open/handlers_client.lua**

```lua
Handlers.OnPropDetected = function(entity, propHash, coords)
end

Handlers.OnPropLost = function(entity, propHash)
end
```

- `OnPropDetected`: Fires when the scanner registers a configured prop in range.
- `OnPropLost`: Fires when a tracked prop leaves range.

## Examples

**Double loot on weekends**

**open/handlers_server.lua**

```lua
Handlers.GetLootMultiplier = function(source, propHash, config)
    local day = os.date('*t').wday
    if day == 1 or day == 7 then return 2.0 end
    return 1.0
end
```

**VIP cooldown bypass**

**open/handlers_server.lua**

```lua
Handlers.CanBypassCooldown = function(source, propHash)
    local job = Bridge.GetJob(source)
    return job and job.name == 'vip'
end
```

**Block looting during events**

**open/handlers_server.lua**

```lua
local eventActive = false

Handlers.CanPlayerLoot = function(source, propHash, config)
    if eventActive then
        return false, 'Looting disabled during events'
    end
    return true
end
```