# Developer

> Developer API reference for ML PropsCarry

Category: ITEM CARRY · Source: https://miciomods.it/docs/ml-propscarry-developer · Last updated: 2026-07-13

## Overview

ML PropsCarry provides client exports for reading and managing carried props, server exports for position data, and handler hooks in the `open/` folder for custom logic. Props sync to other players via StateBags. Admins manage the live item catalog in-game with `/carryadmin`; changes persist to oxmysql and reach every player without a restart.

## Server Exports

```lua
local positions = exports.ml_propscarry:GetPlayerPositions(source)
```

- `GetPlayerPositions(source)`: Returns all custom positions for a player: `{ itemName = {x, y, z, rx, ry, rz}, ... }`

## Client Exports

### Prop State

```lua
local props = exports.ml_propscarry:GetCarriedProps()
local positions = exports.ml_propscarry:GetCustomPositions()
local otherProps = exports.ml_propscarry:GetOtherPlayersProps()
```

- `GetCarriedProps()`: Returns `{ itemName = propEntity, ... }` for the local player
- `GetCustomPositions()`: Returns `{ itemName = {x, y, z, rx, ry, rz}, ... }` for the local player
- `GetOtherPlayersProps()`: Returns `{ serverId = { itemName = propEntity, ... }, ... }` for nearby players

### Prop Management

```lua
exports.ml_propscarry:AddCarriedProp(itemName, propEntity)
exports.ml_propscarry:RemoveCarriedProp(itemName)
exports.ml_propscarry:RefreshProps()
exports.ml_propscarry:ForceBroadcast()
```

- `AddCarriedProp(itemName, prop)`: Registers a prop entity as carried
- `RemoveCarriedProp(itemName)`: Removes a carried prop. Returns the entity handle
- `RefreshProps()`: Deletes all props and recreates them (full reset)
- `ForceBroadcast()`: Forces a StateBag update to sync with other players

### Weapon Entity

```lua
local entity, hadComponents = exports.ml_propscarry:CreateWeaponEntity(itemConfig)
```

- `CreateWeaponEntity(itemConfig)`: Creates a weapon object for a `Config.Items` entry, with components and tint resolved from inventory metadata. Returns the entity and whether any components/tint were applied

## Client Handlers

Located in `open/client.lua`.

**open/client.lua**

```lua
function Handlers.CanShowProp(itemConfig)
    return true -- return false to prevent spawning
end

function Handlers.OnPropSpawned(itemName, entity)
end

function Handlers.OnPropRemoved(itemName)
end

function Handlers.CanUseEditor(itemName)
    return true -- return false to block editor
end
```

- `CanShowProp`: Gate prop visibility. Return `false` to hide (e.g. while cuffed or in a vehicle).
- `OnPropSpawned`: Fires after a prop is created and attached to the player.
- `OnPropRemoved`: Fires after a prop is deleted.
- `CanUseEditor`: Gate editor access per item.

## Server Handlers

Located in `open/server.lua`.

**open/server.lua**

```lua
function Handlers.CanSavePosition(src, itemName, position)
    return true -- return false to block save
end

function Handlers.OnPositionSaved(src, itemName, position)
end

function Handlers.IsAdmin(src)
    return nil -- return true/false to override, nil for default
end
```

- `CanSavePosition`: Validate position before saving to KVP. Return `false` to reject.
- `OnPositionSaved`: Fires after a position is saved.
- `IsAdmin`: Override the admin check used by `/carryadmin` and the live catalog callbacks. Return `nil` for default (`Bridge.HasPermission`, then ACE `ml_propscarry.admin`/`admin`).

## Examples

**Hide props while cuffed**

**open/client.lua**

```lua
function Handlers.CanShowProp(itemConfig)
    if LocalPlayer.state.isCuffed then
        return false
    end
    return true
end
```

**Read carried weapons from another script**

**your_script/client.lua**

```lua
local carried = exports.ml_propscarry:GetCarriedProps()
for itemName, entity in pairs(carried) do
    print(itemName .. ' is visible on player')
end
```