Docs / Server / InventoryService V1.2

Server API

All available methods for inventory management

Method Parameters Description
AddItem player, itemId, amount, metadata? Add to hotbar first, then storage. Auto-stacks.
AddToBackpack NEW player, itemId, amount?, metadata? Add directly to storage (bypasses hotbar).
RemoveItem player, uuid, amount? Remove item by UUID. Partial removal supported.
SwapSlots player, fromType, fromSlot, toType, toSlot Swap any two slots (Hotbar/Storage).
StackTwoSlots NEW player, fromType, fromSlot, toType, toSlot Merge two stacks (rarely needed - add auto-stacks).
EquipSlot player, slotType, slot Equip item from Hotbar or Storage.
UnequipSlot player Unequip current tool.
DropItem player, slotType, slot Drop item into world.
UpdateMetadata player, uuid, updates Update item metadata (delta sync).
ReloadClient NEW player, config Triggers a client-side UI/Hook reload. Config: { configSettingName, RefreshData }
GetState player Get player's inventory state.
Server Usage Example Luau 
-- Initialize
local InventoryService = require(game.ServerScriptService.StowayServerV1_2)
InventoryService.Init()

-- Add items
InventoryService.AddItem(player, "Sword", 1)

-- Add directly to backpack
InventoryService.AddToBackpack(player, "Potion", 5)

Network Protocol

Bidirectional communication standards

🔒 Anti-Exploit Features:
  • Per-player operation lock prevents remote spam
  • Spammed calls return { success = false, reason = "OPERATION_IN_PROGRESS" }
  • Lock auto-releases on completion (success or error)
  • pcall wrapper prevents server crashes

1. Client Requests (Input)

Sent via InventoryAction RemoteEvent.

Operation Arguments (Table) Description
"Swap" { fromType, fromSlot, toType, toSlot } Swap item locations. Validates ownership and bounds.
"Stack" { fromType, fromSlot, toType, toSlot } Merge stack from source to target.
"Equip" { slotType?, slot } Equip item. slotType defaults to "Hotbar".
"Unequip" {} Unequip currently held item.
"Remove" { uuid, amount? } Delete item. Removes entire stack if amount is nil.
"Drop" { slotType, slot } Drop item into the world (spawns pickup).

2. Server Replication (Output)

Received via InventoryUpdate RemoteEvent. The server sends delta updates.

Action Payload Structure Description
"Init" { Items, Hotbar, Storage, EquippedUUID } Full state sync. Overwrites local state.
"Add" { Slots: [{ UUID, SlotType, Slot, Item }] } List of items added. Item contains full data.
"Remove" { UUID, SlotType, Slot } Single item removal from a specific slot.
"Swap" { From: {Type, Slot}, To: {Type, Slot} } Confirm swap (Client may predict this).
"Equip" { UUID: string? } Update equipped item UUID (or nil).
"UpdateMeta" { UUID, Updates: {} } Partial metadata update for an item.
"Reload" { UiType, Data? } Instructions to reload UI/Hooks and optional full state resync.

3. Initial Sync

Sent via AskForStoway RemoteFunction.

Handshake Luau 
-- Client Request
local result = Remotes.AskForStoway:InvokeServer()

-- Server Response
{
    success = true,
    data = {
        Items = {...},
        Hotbar = {...},
        Storage = {...},
        Settings = {...}
    }
}

Per-Player Settings

Runtime-configurable settings stored in state.Settings

Setting Default Description
Limit 15 Weight limit (0 = infinite)
CanStack true Enable/disable stacking
MaxStackSize 5 Max items per stack
MaxHotbarSlots 9 Hotbar slot count

Debug Commands

Test commands (remove in production!)

⚠️ Remove Debug/ChatCommands.luau in production! These commands bypass normal validation.
Command Description
/inv Display inventory state
/add [id] [amt?] Add item (hotbar first)
/addback [id] [amt?] Add directly to backpack
/remove [uuid] [amt?] Remove item by UUID
/swap [t1] [s1] [t2] [s2] Swap slots
/stack [t1] [s1] [t2] [s2] Stack items together
/equip [slot] Equip from hotbar
/unequip Unequip current
/drop [type] [slot] Drop item
/clear Clear inventory
/toggle_stack Toggle stacking
/set_limit [n] Set weight limit