# Developer

> Developer API reference for ML Recycler

Category: RECYCLER · Source: https://miciomods.it/docs/ml-recycler-developer · Last updated: 2026-06-10

## Overview

ML Recycler provides server-side event hooks for reacting to recycler actions and handler hooks in the `open/` folder for custom logic. Integration is primarily event-driven. Listen to the hook events from your other scripts.

## Server Event Hooks

The recycler fires named events at key points. Register handlers in any server script:

### Processing

**your_script/server.lua**

```lua
AddEventHandler('ml_recycler:hook:itemAdded', function(source, data)
    -- data: recyclerId, recyclerType, recyclerTier, slotIndex, itemName, itemCount, status
end)

AddEventHandler('ml_recycler:hook:processingComplete', function(data)
    -- data: recyclerId, recyclerType, recyclerTier, slotIndex, itemName, itemCount, owner
end)

AddEventHandler('ml_recycler:hook:lootCollected', function(source, data)
    -- data: recyclerId, recyclerType, slotIndex, loot (array of {item, count})
end)
```

### Maintenance

**your_script/server.lua**

```lua
AddEventHandler('ml_recycler:hook:refueled', function(source, data)
    -- data: recyclerId, recyclerType, fuelItem, quantity, newFuel
end)

AddEventHandler('ml_recycler:hook:repaired', function(source, data)
    -- data: recyclerId, recyclerType, repairItem, quantity, newDurability
end)

AddEventHandler('ml_recycler:hook:malfunction', function(source, data)
    -- data: recyclerId, recyclerType, durability
end)
```

### Upgrades

**your_script/server.lua**

```lua
AddEventHandler('ml_recycler:hook:upgradeInstalled', function(source, data)
    -- data: recyclerId, recyclerType, upgradeKey, upgrades (array)
end)

AddEventHandler('ml_recycler:hook:upgradeRemoved', function(source, data)
    -- data: recyclerId, recyclerType, upgradeKey, upgrades (array)
end)
AddEventHandler('ml_recycler:hook:upgradeBroken', function(data)
    -- data: recyclerId, recyclerType, upgradeKey  (no source; fires from the server loop when a worn upgrade hits zero)
end)
```

### Placement

**your_script/server.lua**

```lua
AddEventHandler('ml_recycler:hook:recyclerPlaced', function(source, data)
    -- data: recyclerId, recyclerType, coords, heading
end)

AddEventHandler('ml_recycler:hook:recyclerPickedUp', function(source, data)
    -- data: recyclerId, recyclerType
end)
```

## Server Handlers

Located in `open/server.lua`.

**open/server.lua**

```lua
function OpenServer.BeforeGiveItem(src, item, amount)
    return true -- return false to block
end

function OpenServer.OnActionComplete(src, actionType, data)
end
```

- `BeforeGiveItem`: Called before giving loot items to the player. Return `false` to block.
- `OnActionComplete`: Fires after any completed action.

## Shared Handlers

Located in `open/shared.lua`.

**open/shared.lua**

```lua
function OpenHandlers.OnPlayerAction(src, data)
    return true -- return false to block
end

function OpenHandlers.ValidateAction(src, actionType)
    return true -- return false to block
end
```

## Client Handlers

Located in `open/client.lua`.

**open/client.lua**

```lua
function OpenClient.BeforeOpenUI(data)
    return true -- return false to block UI
end
```

## Examples

**Grant XP on loot collection**

**your_script/server.lua**

```lua
AddEventHandler('ml_recycler:hook:lootCollected', function(source, data)
    exports.ml_skills:AddXp(source, 'crafting', 15)
end)
```

**Log rare drops to Discord**

**your_script/server.lua**

```lua
AddEventHandler('ml_recycler:hook:lootCollected', function(source, data)
    for _, loot in ipairs(data.loot) do
        if loot.rarity == 'legendary' then
            Bridge.Log({
                webhook = 'YOUR_WEBHOOK',
                title = 'Legendary Drop!',
                description = loot.item .. ' x' .. loot.count,
                player = source,
            })
        end
    end
end)
```

**Block placement in safe zones**

**open/shared.lua**

```lua
function OpenHandlers.ValidateAction(src, actionType)
    if actionType == 'place' then
        -- Add your zone check logic
    end
    return true
end
```