Inventory System
Overview
A drop-in inventory system for any Roblox game. Server-authoritative across every operation. Two inventory models (Slot or List, switchable via one config flag). Drag-and-drop equip slots with mouse + touch support. Stat aggregation auto-sums equipped items into player attributes. 6 rarity tiers with per-tier border colors. DataStore-persistent with session locks. Auto-pairs with CoreShun Shop, Currency, Toast, Anti-Exploit, and Quest.
Drop in. One config file. Define items + slots + stats. Done.
Open source. Plain Luau. No obfuscation. Edit any file.
Two Inventory Models
- Slot model — fixed capacity (configurable). Three OnFullPolicy options:
reject(fail the add),swap(drop oldest),drop(spawn in world). Pairs naturally with capacity-upgrade gamepasses. Best for combat / RPG / survival. - List model — unlimited items. Simpler UX. Sort by Rarity / Name / Recent / Quantity. Better for cosmetic-heavy or showcase inventories.
Switch by editing one line:
Config.Inventory.Model = "Slot" or "List".Item Schema
Every item is a table in
Config.Items. Required: Id, Name. Optional everything else:- Rarity — key from Config.Rarities. Drives border color, glow, sort order.
- Tags — array of strings. Determines which equip slots accept this item (slot's Accepts array matches).
- MaxStack — 1 for equipment, 99-999 for consumables / resources. Stack-aware quantity badges.
- Stats — {Attack = 5, Defense = 3, ...}. Auto-summed across equipped items.
- Consumable + UseCooldown — Use decrements by 1 and fires OnUse hook. Cooldown timer prevents spam.
- SellValue — currency payout when sold back. Multiplied by SellValueMultiplier.
- Icon — emoji glyph OR
rbxassetid://for image icons (auto-detected).
Equip Slots + Drag-Drop
Define equip slots in
Config.Slots:- Per-slot Accepts — which item Tags can equip in this slot
- Per-slot Icon — emoji or image, shown when slot is empty
- Order — display order in the equip panel
Drag-drop supports mouse AND touch. Drag any item card to the matching equip slot. Server validates slot compatibility via
MoveRequest. Click an equipped slot to instantly unequip.6 Rarity Tiers
Built-in: Common · Uncommon · Rare · Epic · Legendary · Mythic. Each tier glows distinctly with configurable color, name, and sort order. Add your own tiers by extending
Config.Rarities.Stat System
Declare every stat your game cares about in
Config.Stats. Each item declares its Stats table. When equipped, those stats auto-sum into the player's total. Totals are cached on player attributes for cheap external reads:_G.CoreShunInventory_TotalStat(player, "Attack")— sum across equipped itemsplayer:GetAttribute("CoreShunInv_Stat_Attack")— same value, no function call overhead_G.CoreShunInventory_GetItemStat(itemId, "Attack")— one item's stat without ownership check
Attack / Defense / HP / Speed / Luck ship by default. Add any stat with Id, Name, Icon, Color. The Total Stats panel auto-renders all configured stats.
Fully Customizable
Every visible string, icon, size, and animation lives in one config with inline comments. Four sub-tables under
Config.UI:- Text — 29 strings for localization (title, button labels, badges, sort labels, confirmation modals, empty state, sell template)
- Icons — every icon supports emoji glyph OR Roblox image asset (auto-detected by
rbxassetprefix) - Sizes — grid cell size, list row height, equip slot size, detail panel width, modal dimensions
- Animation — every duration is a knob. Master
Enabled = falsedisables all animations (accessibility / low-end devices)
Server-Authoritative + Anti-Cheat
The client is a request layer. Every inventory operation is validated server-side:
- Rate limit — sliding window of 30 ops / 60s (configurable). Over-limit: drop or kick.
- Per-operation cap —
MaxSingleOperationQtycatches misconfigurations. - Equip validation — server checks ownership AND tag/slot compatibility on every request.
- Use cooldowns — server tracks last-use per item, rejects spam.
- Auto-pairs with Anti-Exploit Suite — all 12 Inventory remotes register with
_G.CoreShunAntiExploit_ReportRemote.
DataStore Persistence
Same battle-tested DataStore pattern that ships in CoreShun Shop + Currency, hardened further in v1.0:
- Session locks — prevent cross-server overwrites (60s TTL, 30s heartbeat refresh)
- Lock-steal protection — every save checks the lock is still ours
- Exponential backoff retries — up to 5 attempts before session-only fallback
- Save coalescing — rapid changes coalesce into one write after 2.5s
- Parallel BindToClose with snapshot — all canPersist players save + release locks simultaneously on shutdown. The snapshot is captured synchronously before any yield, so PlayerRemoving races cannot strand a lock.
- Auto-recovery — orphaned locks from server crashes expire in 60s; next session reclaims and reads the persisted data normally.
_G.CoreShunInventory_CanPersist(player)— query whether the current session has the lock, so your game logic can detect "session-only mode" and surface a UI badge.
API + 13 Buyer Hooks
One global namespace, 20 functions. Call from anywhere.
Open()/Close()/Toggle()/IsOpen()— modal visibilityAdd(p, id, qty)/Remove(p, id, qty)/Has(p, id)/GetQuantity(p, id)/GetAll(p)Equip(p, id, slot)/Unequip(p, slot)/GetEquipped(p, slot)/GetEquippedAll(p)Use(p, id)/Drop(p, id, qty)TotalStat(p, statId)/GetItemStat(id, statId)
Thirteen hooks (BeforeAdd, OnAdd, BeforeRemove, OnRemove, BeforeEquip, OnEquip, OnUnequip, BeforeUse, OnUse, OnFull, OnDrop, OnPickup, OnLoaded, plus OnOpen / OnClose for analytics) — wire your game logic to inventory events.
Pairs with the CoreShun Stack
Auto-detects sibling products at boot. No setup required.
- CoreShun Shop System — purchased items auto-flow into Inventory via OnItemGranted hook. Zero buyer wiring.
- CoreShun Currency System — "Sell" button credits currency via
_G.CoreShunCurrency_Add. Per-item SellValue + global multiplier. - CoreShun Toast Notifications — gain / use / equip events route to Toast. Falls back to built-in toast if not installed.
- CoreShun Anti-Exploit Suite — all 12 Inventory remotes auto-register for rate-limit + intrusion rules.
- CoreShun Quest System — "Collect N items" quests read
GetQuantity. Quest rewards grant items.
What's in the box
- CoreShunInventorySystem.rbxmx — drop-in model with installer
- InventoryServer.lua (1205 lines) — DataStore w/ session locks, equip/use/drop, stat aggregation, rate limit, hooks, _G API, Shop auto-pairing
- InventoryClient.lua (1643 lines) — full UI: 3 layouts × 2 inventory models, drag-drop equip slots, stat panel, item detail panel, confirmation modals, mobile bottom sheet
- InventoryConfig.lua (886 lines) — heavily commented schema with 13 sample items, 5 slots, 6 rarities, 5 stats, 4 customization sub-tables
- Installer.lua — auto-places everything
- Manual.pdf — full documentation
- Cheatsheet.pdf — one-pager reference
Drop in. Define items + slots. Done.
