Inventory & Items
Universal items that work across worlds and runtimes, and the four-tier execution model that decides what the client may do and what the server must own.
Items in HELIX are universal: an item a player owns exists across worlds and renders on every
runtime (each item ships per-runtime renditions — e.g. a web GLB and an Unreal static mesh).
Helix.inventory is how a world reads and uses what a player owns.
Items, products, listings & collectibles — what's what
The one distinction to get right
A universal item is the thing a player owns. A marketplace listing and a world product are two different ways to sell something for LIX. A collectible is a scarce item that only trades peer-to-peer. They're easy to conflate — this table is the difference.
| Concept | What it is | Bought with | Price comes from |
|---|---|---|---|
| Universal item | The asset itself — placeable / wearable / tradeable, owned across every world & runtime. The noun everything else points at. | — (you own it) | its listing |
| Marketplace listing | A universal item offered for sale at its catalog price. | Helix.marketplace.purchaseItem(itemId) | the item's priceLix, server-side |
| World product | A purchasable a world registers (Roblox "developer product"): a price + a type, optionally granting an item. For world-defined goods, bundles, or pure gameplay consumables. | Helix.marketplace.purchaseProduct(productId) | the product's priceLix, server-side |
| Collectible | A scarce, serialized universal item. Trades peer-to-peer on the Marketplace — never sold via an in-world purchase. | the Marketplace (P2P) | the open offer |
Universal item — schema
Fields, kinds, categories, usage, status.
World product — schema
Types, price, linked item, maxPerUser.
The universal item
The shape every owned item, marketplace listing, and grant target shares. Items are created through
the publish pipeline (CLI / MCP / POST /api/v1/universal-items) and read by worlds via
Helix.inventory.
Prop
Type
Field enums
Universal = cross-world + cross-runtime
The same owned item works in every world and renders on every runtime via its per-runtime
renditions. hasItem(id) is true regardless of which world or creator asks — that's what makes
VIP / season passes work across creators.
Reading inventory
Prop
Type
if (await Helix.inventory.hasItem('vip_hat_001')) {
await Helix.inventory.equipItem('vip_hat_001');
}Execution tiers
The most important thing to understand about items is who is allowed to run their logic. Every item declares a tier:
Prop
Type
The golden rule, restated
If it affects inventory, currency, or ownership, the server is authoritative. If it only affects visuals or local gameplay, the client can be trusted. Tier 3 logic runs on the server, full stop.
Consuming an item (Tier 3)
Consumption is server-authoritative and idempotent — a retried network call can't double-spend:
// server-side (HelixServer / HelixInstance context)
const result = await Helix.inventory.consumeItem({
itemId: 'health_potion_001',
quantity: 1,
idempotencyKey: requestId,
});
// result.mintResults describes any items/currency atomically granted in returnItem lifecycle hooks
Interactive items implement lifecycle hooks the runtime calls for you:
onEquip, onUnequip, onPlace, onRemove, onInteract, onUpdate, onStateChangedReference
- Web SDK →
Helix.inventory - Server authority → How HELIX works
- Economy → LIX & Economy
Memory Store
Volatile, low-latency storage shared across all instances of a world. TTL-required. Great for leaderboards, matchmaking, and hot counters — never the source of truth.
Interactive Universal Items
Production implementation contract for portable items with authoritative behavior, typed state, character abilities, and default-on Vault publication.