Interface MenuHandler<C>

Type Parameters:
C - the context type this menu is opened with

public interface MenuHandler<C>
  • Method Details

    • id

      MenuId<C> id()
      Identifies which menu this handler drives.
      Returns:
      the id this handler was registered under
    • onOpen

      void onOpen(MenuInstance instance, C context)
      Called once as the menu opens, before the first render.
      Parameters:
      instance - handle to the menu now opening
      context - the context object the caller opened the menu with
    • onClick

      void onClick(MenuInstance instance, String sectionId, ClickPayload payload)
      Called for a click the section's renderer delegated to this handler.
      Parameters:
      instance - handle to the open menu
      sectionId - id of the section that owns the clicked slot
      payload - what was clicked and how
    • onClose

      default void onClose(MenuInstance instance, CloseReason reason)
      Called once as the menu closes. Default does nothing.
      Parameters:
      instance - handle to the closing menu
      reason - why it is closing
    • onRefresh

      default void onRefresh(MenuInstance instance, C context)
      Called when something outside the menu asks for it to be redrawn (GuiService.refreshMenu(org.bukkit.entity.Player)), before the renderer reads the handler's state. A handler that caches derived state -- a sorted row list, a per-row status -- rebuilds it here; one that renders straight from its context needs nothing.
      Parameters:
      instance - the open menu
      context - the context the menu was opened with
    • templateItems

      default List<?> templateItems(C context, String sectionId)
      Items for a paginated-list section. Called every render.
      Parameters:
      context - the menu's context object
      sectionId - the paginated-list section being rendered
      Returns:
      the items to lay out; empty by default
    • storageContents

      default ItemStack[] storageContents(C context, String sectionId)
      Initial contents for a storage section. Called on open.
      Parameters:
      context - the menu's context object
      sectionId - the storage section being filled
      Returns:
      the contents to show on open; empty by default
    • persistStorage

      default void persistStorage(C context, String sectionId, ItemStack[] contents)
      Persist storage contents when the menu closes.
      Parameters:
      context - the menu's context object
      sectionId - the storage section being saved
      contents - what the viewer left in the section
    • sharedStorageKey

      default Object sharedStorageKey(C context)
      Identity of the mutable store this menu's storage sections read and write, or null (the default) for menus with no storage or none that another viewer can reach.

      Storage is copied into a per-viewer Inventory on open and written back wholesale on close, so two live menus over one backing store cannot both be correct: whichever closes last overwrites the store with its own copy, resurrecting whatever the other viewer removed. Handlers whose store is reachable by more than one viewer return that store here, and the dispatcher persists and closes the earlier viewer's menu before opening the new one.

      Compared by identity, so return the shared object itself — not a copy, a snapshot, or an id that merely equals another.

      Parameters:
      context - the menu's context object
      Returns:
      the shared backing store, or null when no other viewer can reach it
    • placeholders

      default TagResolver placeholders(C context, String sectionId, int itemIndex)
      Placeholders for one rendered item. For paginated-list templates, itemIndex is the page-relative index; for other sections it is -1.
      Parameters:
      context - the menu's context object
      sectionId - the section being rendered
      itemIndex - page-relative index for a paginated-list template, or -1 elsewhere
      Returns:
      resolvers for this item; empty by default
    • titlePlaceholders

      default TagResolver titlePlaceholders(C context)
      Placeholders resolved into the JSON title when the menu is built. Supply the dynamic part as an uncolored component (e.g. Placeholder.component("pet_title", Component.translatable("X.Title", Component.text(petName)))); the JSON wraps it with color. Lets dynamic titles keep their styling in JSON rather than in code.
      Parameters:
      context - the menu's context object
      Returns:
      resolvers for the menu title; empty by default
    • customizeTemplateItem

      default ItemAppearance customizeTemplateItem(C context, String sectionId, int itemIndex, ItemAppearance template)
      Customize a paginated-list template's item for one specific entry (e.g. swap the material / glow per-item based on the underlying data). Default returns the template unchanged. Only called for paginated-list sections; for other section types, the template is used as-is.
      Parameters:
      context - the menu's context object
      sectionId - the paginated-list section being rendered
      itemIndex - page-relative index of the entry
      template - the appearance as loaded from JSON
      Returns:
      the appearance to draw; the template unchanged by default
    • customizeSlotItem

      default ItemAppearance customizeSlotItem(C context, String sectionId, ItemAppearance appearance)
      Customize a slot section's item at render time (e.g. swap material per pet type, recolor potion bottle). Default returns the appearance unchanged. Called every render after state resolution for slot sections only.
      Parameters:
      context - the menu's context object
      sectionId - the slot section being rendered
      appearance - the appearance after state resolution
      Returns:
      the appearance to draw; unchanged by default
    • isSlotVisible

      default boolean isSlotVisible(C context, String sectionId)
      Per-render visibility check for a section. Returning false skips both rendering and click routing for that slot. The slot's underlying area is left to whatever lower-priority section painted there (border, fill, or empty). Default true.
      Parameters:
      context - the menu's context object
      sectionId - the section being considered
      Returns:
      true to render and route clicks for it; true by default
    • valueBarPosition

      default int valueBarPosition(C context, String sectionId)
      Current 0-indexed fill position for a value-bar section (0..width-1). Default 0 (renders as all-low). Clamped to range at render time.
      Parameters:
      context - the menu's context object
      sectionId - the value-bar section being rendered
      Returns:
      the 0-indexed fill position, clamped to the bar's width at render time
    • transformDefinition

      default MenuDefinition transformDefinition(C context, MenuDefinition base)
      Reshape the loaded MenuDefinition based on the open-time context. Use when row count or section regions depend on per-pet state (e.g. the backpack's upgrade-driven row count). Default returns base unchanged.
      Parameters:
      context - the menu's context object
      base - the definition as loaded
      Returns:
      the definition to open; base unchanged by default