Skip to main content

​
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

FieldTypeDefaultDescription
artifactIdStringauto-generatedUnique 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:
FieldTypeDefaultDescription
entryRef<gui_storage>requiredReference to the GUI Storage artifact
maxAmountInt64Maximum item stack size in this slot
forceStorageBooltrueAllow non-stackable items (swords, tools)
temporaryBoolfalseItems are lost when the menu closes
groupRef<GroupEntry>nullGroup for shared storage (e.g., islands)
placeholderVar<Item>AIRItem shown when the slot is empty
requiredItemVar<Item>nullOnly allow this specific item type
requiredAmountInt0Amount needed to trigger onReachRequired
onFillRef[][]Triggers when slot becomes non-empty
onEmptyRef[][]Triggers when slot becomes empty
onReachRequiredRef[][]Triggers when requiredAmount is reached
consumeOnReachBooltrueConsume deposited items when requiredAmount is met

​
Storage Placeholders

These placeholders are resolved in storage slot displayName and lore at render time:
PlaceholderDescription
{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.