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 distribution and a world product are two different ways to sell something. A collectible is a scarce, serialized edition of an item that resells 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. An item id is never a purchase reference. | — (you own it) | its distributions |
| Distribution | A creator's primary offer of an item: price in LIX or Coins, per-player cap, claim cap, optional window. Registered for one world (a dkey) or public. | Helix.marketplace.purchaseDistributionKey(key) / purchaseDistribution(id) | the distribution, server-side |
| World product | A purchasable a world registers (Roblox "developer product"): passes, world currencies and consumables. Never grants a universal item. | Helix.marketplace.purchaseProduct(productKey) | the product's priceLix, server-side |
| Collectible | A scarce, serialized edition of an item. First issued through a distribution up to its fixed supply, then resold peer-to-peer on the Marketplace. | a distribution, then a listing (purchaseListing(listingId)) | the distribution, then the seller's listing |
Universal item — schema
Fields, kinds, categories, usage, status.
World product — schema
Key, price, grants, 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
assets. 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
Outside the shell (a world opened directly) every read resolves empty: false, 0 or [].
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. HELIX reasons about it in four tiers. They are a design model, not a field: no item carries a tier value.
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)
Contract, not shipped API
The Web SDK's Helix.inventory is read and equip only: hasItem, getQuantity, getMyItems,
equipItem. Consuming a universal item is a designed contract, not a shipped route: neither the SDK
nor the backend exposes it today. For world-local balances use Helix.purchases.consume.
Consumption is server-authoritative and idempotent — a retried network call can't double-spend:
// designed contract only: not in the SDK or the backend today
const result = await Helix.inventory.consumeItem({
itemId: 'health_potion_001',
quantity: 1,
idempotencyKey: requestId,
});
// result.mintResults describes any items/currency atomically granted in returnItem behaviour
Interactive behaviour (state, interactions, abilities with onEquip / onUnequip) is specified in
Interactive Universal Items, which separates what is live
today from the target contract.
Reference
- 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.