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
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).

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.