# Developer

> Developer API reference for ML Clothing System

Category: INVENTORY · Source: https://miciomods.it/docs/ml-inventory-developer · Last updated: 2026-07-13

# Developer

Integration happens two ways. The `open/` files hold owner hooks you edit in place: functions that ML Clothing calls at defined points (punishment, item gating, gear breaking and repairing, appearance adapters). Everything else is exposed through resource exports on the server and client. Only the exports and hooks that exist in the source are listed here.

## Server exports

### Wear and durability

```lua
exports.ml_clothing:GetWornDurability(src, slot)
```

Returns the `durability` value from the item metadata in the given inventory slot, or `nil` if the slot is empty or has no metadata.

```lua
exports.ml_clothing:IsGearBroken(src, slot)
```

Returns `true` if the worn piece in that slot is currently flagged broken, otherwise `false`.

```lua
exports.ml_clothing:RepairGear(src, slot, amount?)
```

Repairs the worn piece in that slot by `amount` (clamped 1 to 100, default 100). Returns `false` if the arguments are not numbers or the slot is not wear-managed, otherwise the result of the repair.

### Equipment stashes

```lua
exports.ml_clothing:RegisterEquipmentStash(stashType, uniqueId, slots, maxWeight, cols?)
```

Registers a plate carrier or bag stash. `stashType` is `'plateCarrier'` or `'bag'`; the ID is built from the matching prefix in `Config.Stash` plus `uniqueId`. Returns the full stash ID.

```lua
exports.ml_clothing:GetEquipmentStashId(stashType, uniqueId)
```

Returns the stash ID that `RegisterEquipmentStash` would produce for the same arguments, without registering it.

### Reserved slots

```lua
exports.ml_clothing:GetReservedSlots()
```

Returns the sorted list of clothing slot numbers (`Config.ClothesSlotID`, slots 11 to 25). Use this to keep other scripts from writing into reserved clothing slots.

## Client exports

### Appearance

```lua
exports.ml_clothing:getCurrentAppearance()
```

Returns the current ped appearance snapshot (components and props).

```lua
exports.ml_clothing:applyAppearance(appearanceData)
```

Applies an appearance table to the local ped, setting components and props.

```lua
exports.ml_clothing:saveAppearance()
```

Captures the current ped appearance and sends it to the server to persist.

```lua
exports.ml_clothing:syncFromNUI(appearanceData)
```

Sends an appearance table to the server as a new outfit to sync into inventory items. This is the call to add inside the appearance script wherever an outfit is saved; see [Clothing Integration](https://miciomods.it/docs/ml-inventory-cloth-integration) for the exact placement in `illenium-appearance` and `bl_appearance`.

```lua
exports.ml_clothing:syncFromPed()
```

Captures the live ped components and props and syncs them into inventory items. Use this instead of `syncFromNUI` when the appearance data is not at hand or its format has no adapter, for example in the save callbacks of `codem-appearance`.

```lua
exports.ml_clothing:clearSkin()
```

Resets the ped clothing components to their default state.

### Vest and plate carrier

```lua
exports.ml_clothing:useVest(item, data)
```

Equips or removes the plate carrier. Plays the tie animation, registers the carrier if needed, and sets ped armor from the sum of inserted plate health (capped at 100).

### Give mode and loot feedback

```lua
exports.ml_clothing:openGiveMode(data)
```

Starts hand-item-to-player targeting. The player aims at a nearby target and confirms to give the item.

```lua
exports.ml_clothing:lootTrapEffect()
```

Plays a trap reaction on the local ped: animation, screen effect, sound, and a small amount of damage.

```lua
exports.ml_clothing:PlayLootSound(data)
```

Plays a named front-end loot sound. `data` is an event name string, or a table with an `event` field. Recognized events include `container_open`, `scan_tick`, `slot_unlock`, `reveal_common`, `reveal_uncommon`, `reveal_rare`, `reveal_epic`, `reveal_legendary`, and `loot_all`.

### Preview ped positioning

```lua
exports.ml_clothing:OnPedScreenPosition(data)
exports.ml_clothing:OnPedZoom(data)
exports.ml_clothing:OnTargetPedScreenPosition()
```

Drive the on-screen preview ped placement and zoom for the inventory clothing preview. `OnTargetPedScreenPosition` is a no-op stub.

### Admin gizmo

```lua
exports.ml_clothing:UseGizmo(...)
exports.ml_clothing:StopGizmo()
exports.ml_clothing:IsGizmoActive()
```

Start, stop, and query the 3D placement gizmo used by the inventory admin panel.

## Owner hooks

These live in `open/` and are meant to be edited. They are called by the resource at fixed points.

### Server hooks (`open/server.lua`)

```lua
function OpenServer.PunishPlayer(source, reason) end
function OpenServer.BeforeGiveItem(src, item, amount) end
function OpenServer.OnActionComplete(src, actionType, data) end
function OpenServer.OnGearBroken(src, itemName, slot, key) end
function OpenServer.OnGearRepaired(src, slot) end
```

- `PunishPlayer(source, reason)`: called when a suspicious action is detected. Add your ban, kick, or log logic here. The default prints a debug line.
- `BeforeGiveItem(src, item, amount)`: return `true` to allow, or `false` to block, before an item is given. Default returns `true`.
- `OnActionComplete(src, actionType, data)`: called after an action completes.
- `OnGearBroken(src, itemName, slot, key)`: fired once when a worn piece reaches zero durability. The `key` is `c:<component>:<drawable>:<texture>` for components or `p:<prop>:<drawable>:<texture>` for props.
- `OnGearRepaired(src, slot)`: fired when a worn piece is repaired back above zero.

### Client hooks (`open/client.lua`)

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

- `Notify(message, type)`: notification entry point. Default routes to `Bridge.Notify`.
- `BeforeOpenUI(data)`: return `true` to allow the UI to open. Default returns `true`.

### Shared hooks (`open/shared.lua`)

```lua
function OpenHandlers.OnPlayerAction(src, data) end
function OpenHandlers.ValidateAction(src, actionType) end
```

- `OnPlayerAction` and `ValidateAction`: return `true` to allow the action. Both default to `true`.

### Appearance adapters (`open/adapters/`)

One file per appearance source: `illenium.lua`, `bl_appearance.lua`, and `native.lua`. Each defines a `Config.DataAdapters` function that takes the third-party appearance data and returns a standard list of `{ type, id, drawable, texture }` entries. To support another appearance format, add a new file in the folder, then run `refresh` and restart the resource so the new file is picked up.

## Statebag integration

A worn-out piece is exposed through a player statebag so other scripts can react.

```lua
local broken = LocalPlayer.state.ml_clothingBroken
```

`ml_clothingBroken` holds the broken worn drawables, keyed `c:<component>:<drawable>:<texture>` for components and `p:<prop>:<drawable>:<texture>` for props. For example, `ml_radiation` reads this to stop protection from a worn-out mask or suit when its `RespectWear` option is on.

## Examples

**Register a bag stash for a custom container**

```lua
local uniqueId = 'trunk_' .. plate
local slots, maxWeight, cols = 20, 40000, 5

local stashId = exports.ml_clothing:RegisterEquipmentStash('bag', uniqueId, slots, maxWeight, cols)
print('registered stash', stashId)
```

**Block writing into reserved clothing slots**

```lua
local reserved = exports.ml_clothing:GetReservedSlots()

local function isReserved(slot)
    for i = 1, #reserved do
        if reserved[i] == slot then return true end
    end
    return false
end
```

**Repair worn gear from another resource**

```lua
-- src is the player server id, slot is the clothing slot (11-25)
if exports.ml_clothing:IsGearBroken(src, slot) then
    exports.ml_clothing:RepairGear(src, slot, 100)
end
```

**React to a piece breaking**

```lua
-- in open/server.lua
function OpenServer.OnGearBroken(src, itemName, slot, key)
    -- your logic: log it, notify staff, spawn a replacement, etc.
end
```