GUI Storage Artifact

The GUI Storage Artifact persists items placed in storage slots across sessions and server restarts. Each slot in the layout can reference this artifact to save/load items.

Type: Artifact Entry Entry ID: gui_storage

Configuration

Field	Type	Default	Description
artifactId	String	auto-generated	Unique identifier for this storage instance.

Stored Data

Each artifact stores a JSON map per groupKey (player UUID or group ID), where keys are slot indices and values are Base64-encoded item data.

Data structure:

{
  "0": "rO0ABXNyABpvcmcuYnVr...",
  "1": "rO0ABXNyABpvcmcuYnVr...",
  "2": null
}

Usage

1. Create a gui_storage entry in your page
2. Reference it from storage slots via storage.entry
3. Items are automatically persisted when placed/taken

Storage Slot Configuration

When used in an open_gui layout, each slot can have:

Field	Type	Default	Description
entry	Ref<gui_storage>	required	Reference to the GUI Storage artifact
maxAmount	Int	64	Maximum item stack size in this slot
forceStorage	Bool	true	Allow non-stackable items (swords, tools)
temporary	Bool	false	Items are lost when the menu closes
dropOnClose	Bool	false	Remaining items are dropped at the player's feet when the menu closes
group	Ref<GroupEntry>	null	Group for shared storage (e.g., islands)
placeholder	Var<Item>	AIR	Item shown when the slot is empty
requiredItem	Var<Item>	null	Only allow this specific item type
requiredAmount	Int	0	Amount needed to trigger onReachRequired
onFill	Ref[]	[]	Triggers when slot becomes non-empty
onEmpty	Ref[]	[]	Triggers when slot becomes empty
onReachRequired	Ref[]	[]	Triggers when requiredAmount is reached
consumeOnReach	Bool	true	Consume deposited items when requiredAmount is met

Storage Placeholders

These placeholders are resolved in storage slot displayName and lore at render time:

Placeholder	Description
{stored_name}	Display name of the stored item (empty if slot is empty)
{stored_amount}	Current item count in the slot
{stored_max}	Maximum capacity (64, 10, etc.)

Group-Based Storage

Use the group field to share storage between multiple players:

storage:
  entry: "shared_chest_storage"
  group: "island_group_entry"
  maxAmount: 64

When a group is specified, all members share the same items. Without a group, storage is per-player (UUID-based).

What happens when the menu closes

Three independent outcomes, decided per slot:

Configuration	Outcome on close
neither flag	Items stay in the artifact and are there again next time the menu opens.
temporary: true	Items are destroyed, and onEmpty/temporaryTriggers fire.
dropOnClose: true	Items are dropped at the player's location.

dropOnClose applies on a real close: the Escape key, a close button, and a disconnect. A menu-to-menu transition is not a close and never drops anything. It is independent from temporary and from the click bindings — a slot that must never keep anything can set both, and dropOnClose wins.

备注

Both flags require OmniGUI v0.14 or later. Before that release temporary was inert for a slot declared through a storage layout, because the close pass never resolved that layout's slots.

Accumulation Mode

Set requiredItem and requiredAmount to create a progress-based storage slot:

storage:
  entry: "quest_turn_in"
  requiredItem: { material: DIAMOND }
  requiredAmount: 64
  onReachRequired: ["quest_complete_entry"]
  consumeOnReach: true

Players deposit matching items. When the threshold is reached, onReachRequired triggers fire, and items are consumed (if consumeOnReach is true). A progress bar appears in the item lore.