Skip to main content

GUI

The GUI Extension is the central menu system for Typewriter. It provides 9 configurable layout engines (plus API-only components), 23 inventory types, keyboard/mouse interactions, persistent item storage, and full MiniMessage formatting. Almost all other extensions depend on it for their menus.

Coming soon: a web-based WYSIWYG editor with drag & drop, live in-game-accurate preview, CSS-flexbox auto-layout, menu states, tilemaps and multi-provider resource pack support.

Features​

  • 9 Layout Engines — Simple, Composite, Scrollable, Paginated, Frame, Flex, Storage, Book, Merchant — plus Iterator, Slider and ReactiveSlot via the Kotlin API.
    • 23 Inventory Types — Chest, Furnace, Anvil, Enchanting, Smithing, Merchant, Book, and more.
    • Scrolling & Navigation — Scrollable layouts with configurable up/down/left/right buttons. Scroll buttons are anchored to viewport. Multi-frame with independent zones.
    • Persistent Storage — Item storage backed by artifacts — per-player or group-based. Accumulation mode for progress tracking. Configurable click actions.
    • Storage Placeholders — Dynamic {stored_name}, {stored_amount}, {stored_max} placeholders in slot names and lore.
    • MiniMessage — Full MiniMessage support for titles, item names, and lore. Colors, gradients, hover/click events.
    • Click Interactions — LEFT, RIGHT, SHIFT, DOUBLE_CLICK, DROP, SWAP_OFFHAND, NUMBER_KEY, SCROLL — per slot or global.
    • Animations — Smooth slot transitions with configurable easing (linear, ease-in, ease-out).
    • Input Dialogs — Text input prompts during menu interaction via Paper dialog API.

Architecture​

Entry Library​

Actions​

  • Open GUI — The main entry point. Defines an inventory GUI with title, layout, items, interactions, and storage.

Configuration​

  • GUI Settings — Global defaults: audio configuration, storage click behavior mapping, skill tree nodes.

Guides​

  • Introduction — How the system works, vocabulary, and your first menu step by step.
    • Layout Types — Every layout engine with complete examples and when to use each.
    • Commands & Interactions — Click types, internal gui: actions, cooldowns, input dialogs.
    • Cookbook — Ready-to-adapt recipes: scrollable list, shop, confirmation, quota deposit.

Artifacts​

  • GUI Storage — Persistent storage artifact. Per-player or group-based item persistence with accumulation support.

Quick Start​

  • 1. Create an Open GUI Entry — Create an Open GUI action entry. This single entry defines everything about one menu: Core setup: - title — Inventory title (MiniMessage + PlaceholderAPI) - guiType — Inventory type: CUSTOM, CHEST, MERCHANT, BOOK, ANVIL, etc. (23 types) - size — For CUSTOM type: SIZE_9 to SIZE_54 Layout (choose one): - simple — Explicit x,y coordinates, with count/direction/gap/repeatY for grid patterns - scrollable — Viewport with scroll buttons, inner layout scrolls - frame — Multiple independent zones, each with its own child layout - paginated — Discrete pages with next/previous navigation - composite — Stacked children in Z-order - book — MiniMessage pages as a written book - merchant — Villager trades with custom items Items & Interactions: - Define slots with item, displayName, lore — use x/y/count/direction for positioning - Attach interactionList per slot: LEFT, RIGHT, SHIFT_LEFT, SHIFT_RIGHT, DOUBLE_CLICK, DROP, etc. - Attach triggers to fire Typewriter actions on click Storage (optional): - Add storage to any slot to persist items - Use {stored_name}, {stored_amount}, {stored_max} placeholders → Open GUI Entry Reference

  • 2. Link from Other Extensions — Once your GUI entry exists, reference it from any other extension that needs a menu: - QuestCodex — quest_codex_settings uses GUI layout for quest browsing - Shops — Shop menus use GUI layouts for item display - BattlePass, Crates, Pets, Party, Profiles, Cosmetics, Dungeon, BTCSky... — All use GUI Extension for their menus Simply reference the Open GUI action entry ID in the other extension's menu config. > The GUI Extension is a required dependency for 20+ other extensions.

Layout Types​

SimpleLayout​

Items placed at explicit (x, y) coordinates on a virtual grid. Best for static menus, decorations, and backgrounds. Supports count, direction, gap, and repeatY for grid patterns.

ScrollableLayout​

Wraps a child layout with scroll support. Custom scroll buttons (UP/DOWN/LEFT/RIGHT) are anchored to the viewport — they do not move when content scrolls. Best for long item lists.

FrameLayout​

Divides the screen into independent zones. Each frame has its own position, size, and child layout (typically scrollable). Best for dashboards, sidebars, and multi-pane panels. Each scrollable zone must have a unique ID for proper scroll isolation.

PaginatedLayout​

Discrete pages with next/previous navigation buttons. Best for multi-page menus and large collections.

CompositeLayout​

Layers multiple child layouts in Z-order. Best for overlays and complex UI.

BookLayout​

Renders MiniMessage pages as a written book. Best for lore, guides, and dialogue.

MerchantLayout​

Defines villager trades with input items and a result. Best for shops and trading.

Interactions Reference​

All Supported Interactions
InteractionTrigger
LEFTLeft mouse button
RIGHTRight mouse button
SHIFT_LEFTShift + Left click
SHIFT_RIGHTShift + Right click
MIDDLEMiddle mouse button
DOUBLE_CLICKDouble click
NUMBER_KEY_1..9Hotbar keys 1-9
DROPQ key
DROP_ALLCtrl+Q
SWAP_OFFHANDF key

Usage: interactionList per slot for click actions, globalInteractions for menu-wide keybinds.

GUI Types Reference​

All 23 Supported Inventory Types
TypeDescription
CUSTOMConfigurable chest (1-6 rows)
CHESTStandard chest
FURNACEFurnace
BLAST_FURNACEBlast furnace
SMOKERSmoker
BEACONBeacon
ENCHANTING_TABLEEnchanting table
GRINDSTONEGrindstone repair
CARTOGRAPHY_TABLEMap modification
ANVILAnvil repair/rename
LOOMBanner pattern loom
SMITHING_TABLESmithing table
STONECUTTERStonecutter
CRAFTING_TABLEWorkbench
BREWING_STANDBrewing stand
HOPPERHopper
DROPPERDropper
DISPENSERDispenser
BARRELBarrel
SHULKER_BOXShulker box
ENDER_CHESTEnder chest
MERCHANTMerchant trading
BOOKWritten book

Storage & Accumulation​

  • Standard storage: Click to deposit/withdraw items. All click behaviors are globally configurable via GUI Settings.
  • Storage placeholders: {stored_name}, {stored_amount}, {stored_max} resolve dynamically in slot displayName and lore
  • forceStorage: true (default): Non-stackable items (swords, tools, armor) can be stored
  • Accumulation mode: Set requiredItem + requiredAmount — items are consumed, onReachRequired triggers fire at threshold
  • Group storage: Share storage between players (e.g., island team) via group entry
  • Temporary slots: Items removed after close (temporary = true)
  • onFill / onEmpty triggers: Fire Typewriter actions on slot state changes

See GUI Storage Artifact for full details.

Placeholders​

Storage Placeholders​

Resolved in storage slot displayName and lore:

PlaceholderDescription
{stored_name}Display name of the stored item
{stored_amount}Current item count in the slot
{stored_max}Maximum capacity of the slot

Engine Placeholders​

GUI titles and item lore also support Typewriter Engine placeholders and PlaceholderAPI through @Placeholder fields.

Commands​

This extension provides no standalone commands. All menu interactions are through Typewriter entries.

Permissions​

No custom permissions. GUI access is controlled through the entries that reference Open GUI actions.

Dependencies​

ExtensionRequiredUsage
(none)-This is a foundational extension. 20+ other extensions depend on it.
PlaceholderAPIOptionalFor @Placeholder fields in titles, names, and lore.