forge/docs/LOCKER_USAGE_GUIDE.md

Locker Usage Guide

The locker module stores physical player inventory items by classname. It is separate from the virtual arsenal unlock module documented in Owned Storage Usage Guide.

Storage Model

Locker data is persisted through SurrealDB by the server extension.

{
  "arifle_MX_F": {
    "category": "weapon",
    "classname": "arifle_MX_F",
    "amount": 1
  }
}

Rules validated by the Rust service:

• A locker can contain up to 25 unique classnames.
• category and classname cannot be empty.
• amount must be greater than 0.
• locker:add creates an empty locker automatically when one does not exist.
• locker:get, locker:patch, and locker:remove require an existing locker.
• locker:remove takes the classname directly, not a JSON object.

Multiple Locker Objects

Editor-placed locker objects are templates and access points, not separate durable inventories. During server post-init, any mission namespace object whose variable name contains locker is hidden globally. During client setup, each client reads the hidden object's classname, ASL position, vector direction, and vector up, then creates a matching local locker object with createVehicleLocal.

The local clone is the object the player actually opens. On ContainerOpened, the client clears the clone and fills it from the player's UID-owned locker state. On ContainerClosed, the client reads the clone's cargo and sends a full locker override back to the server.

There is no explicit maximum number of editor-placed locker access points. The practical limit is mission performance and how many local container objects are reasonable for the scenario.

All locker access points load and save the same player locker, keyed by player UID. Opening locker, locker_hq, or locker_outpost_1 does not create separate persistent inventories; those objects are separate local access clones for the same underlying player locker.

Store Grants and Duplicate Inventory

The store checkout path grants items to the UID-owned locker hot state, not to a specific placed locker object. Item grants are merged by classname:

• buying a new classname adds one new locker entry
• buying an existing classname increases that entry's amount
• checkout fails if the result would exceed 25 unique classnames

Having more than one locker object on the map does not duplicate store grants. Duplicate quantities can only come from repeated checkout requests or repeated manual locker writes, not from the number of placed locker access points.

Commands

All commands are called on the locker group.

Command	Arguments	Returns
locker:create	uid	Empty item map as JSON.
locker:get	uid	Item map as JSON.
locker:add	uid, item_json	Updated item map as JSON.
locker:update	uid, items_json	Replaced item map as JSON.
locker:patch	uid, patch_json	Updated item map as JSON.
locker:remove	uid, classname	Updated item map as JSON.
locker:delete	uid	OK.
locker:exists	uid	true or false.

Error Handling

Every command returns a string payload. Always check for the Error: prefix before parsing JSON.

private _result = "forge_server" callExtension ["locker:get", [getPlayerUID player]];
private _payload = _result select 0;

if (_payload find "Error:" == 0) exitWith {
    systemChat format ["Locker error: %1", _payload];
};

private _locker = fromJSON _payload;

Add an Item

locker:add creates or overwrites one classname entry.

private _item = createHashMapFromArray [
    ["category", "weapon"],
    ["classname", "arifle_MX_F"],
    ["amount", 1]
];

private _result = "forge_server" callExtension ["locker:add", [
    getPlayerUID player,
    toJSON _item
]];

private _payload = _result select 0;
if (_payload find "Error:" == 0) exitWith {
    hint format ["Failed to store item: %1", _payload];
};

private _locker = fromJSON _payload;

Patch an Amount

locker:patch currently patches the amount field for an existing classname.

private _patch = createHashMapFromArray [
    ["classname", "arifle_MX_F"],
    ["amount", 5]
];

private _result = "forge_server" callExtension ["locker:patch", [
    getPlayerUID player,
    toJSON _patch
]];

Remove an Item

locker:remove takes the classname as the second argument.

private _result = "forge_server" callExtension ["locker:remove", [
    getPlayerUID player,
    "arifle_MX_F"
]];

Retrieve an Item

fnc_retrieveLockerItem = {
    params ["_classname"];

    private _result = "forge_server" callExtension ["locker:get", [getPlayerUID player]];
    private _payload = _result select 0;

    if (_payload find "Error:" == 0) exitWith {
        hint format ["Failed to load locker: %1", _payload];
        false
    };

    private _locker = fromJSON _payload;
    private _item = _locker getOrDefault [_classname, createHashMap];
    if (_item isEqualTo createHashMap) exitWith {
        hint "Item was not found in your locker.";
        false
    };

    private _amount = _item getOrDefault ["amount", 0];
    if (_amount <= 0) exitWith {
        hint "Item is out of stock.";
        false
    };

    if !(player canAdd _classname) exitWith {
        hint "Not enough inventory space.";
        false
    };

    player addItem _classname;

    if (_amount > 1) then {
        private _patch = createHashMapFromArray [
            ["classname", _classname],
            ["amount", _amount - 1]
        ];
        "forge_server" callExtension ["locker:patch", [getPlayerUID player, toJSON _patch]];
    } else {
        "forge_server" callExtension ["locker:remove", [getPlayerUID player, _classname]];
    };

    true
};

Replace the Whole Locker

locker:update replaces the whole item map. Use it for explicit bulk syncs, not single-item changes.

private _items = createHashMapFromArray [
    ["arifle_MX_F", createHashMapFromArray [
        ["category", "weapon"],
        ["classname", "arifle_MX_F"],
        ["amount", 1]
    ]]
];

private _result = "forge_server" callExtension ["locker:update", [
    getPlayerUID player,
    toJSON _items
]];

Hot State

The locker:hot:* commands keep a runtime copy of a player's locker and write it back only when locker:hot:save runs.

Command	Arguments	Returns
locker:hot:init	uid	Item map as JSON.
locker:hot:get	uid	Item map as JSON.
locker:hot:override	uid, items_json	Item map as JSON.
locker:hot:save	uid	Current hot item map as JSON.
locker:hot:remove	uid	OK.

Use hot state for session-heavy locker workflows. Use the durable commands for simple item deposits and withdrawals.

Best Practices

• Keep categories normalized, for example weapon, magazine, item, or backpack.
• Use locker:patch for quantity changes.
• Use locker:remove when quantity reaches zero.
• Treat the locker response as a hash map keyed by classname.
• Check capacity before bulk operations that may exceed 25 unique items.