An inventory plugin that never lies: transactional add, equip and use in a vanilla JS 2D engine

Description and use

BeeInventory provides atomic inventory operations for 2D games, preventing item loss and inconsistent states. It returns precise add results, rolls back on use errors, and stores only loadable data.

Problem

Typical 2D game inventories often end up in inconsistent states: items disappear silently when the bag is full, equip operations fail halfway leaving items in neither slot nor hand, and use callbacks can throw after the item has been removed.

Outcome

The plugin ensures inventory operations are atomic and transparent, preventing silent failures and state corruption while keeping the engine core untouched.

Workflow

• 1. Create a BeeEngine instance and register the BeeInventory plugin with desired slots and equipSlots.
• 2. Define item types with properties like name, maxStack, consumable, and onUse callbacks.
• 3. Use inventory.add(itemId, quantity) to add items; it returns {added, left} indicating how many were added and how many could not fit.
• 4. Use inventory.use(slotIndex, target) to consume an item; the operation rolls back if onUse throws or returns false.
• 5. Use inventory.move, equip, unequip for atomic transfers between slots and equipment.
• 6. Query inventory.get, list, equipped for read‑only copies of state.
• 7. Persist inventory state via inventory.toJSON(), which stores only slots and equipment.
• 8. Handle UI and game logic (e.g., showing “Bag full” messages) based on the returned leftovers or operation success.
• 9. Run provided Node tests to verify correctness.
• 10. Extend the engine with additional plugins without modifying core engine code.

Evidence

Every 2D game ends up with an inventory. And almost every first inventory looks the same: an items[] array living in the scene, a few push calls, and a growing pile of if statements around it.

Source

add fills existing stacks first, then empty slots. If there's no room left, it doesn't throw the extra items away. It returns them as left.

Source

These three either succeed completely or leave the state exactly as it was. No half‑moved stacks, no item that vanished between the bag and the hand.

Source

if onUse throws, the error is not swallowed: it propagates to the caller, and the inventory is restored to a snapshot taken before the call

Source

get, list and equipped return copies. Code outside can't mutate the inventory by accident by editing an object it got back.

Source