Skip to main content
The GUI Extension is the central menu system for Typewriter. It provides 8 layout engines, 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 visual layout design, real-time preview, Flexbox auto-layout, and multi-provider resource pack generation.

Source Code

View source on GitHub.

Download Releases

Get the latest JARs.

​
Features

8 Layout Engines

Simple, Scrollable, Frame, Paginated, Composite, Book, Merchant.

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.

​
Artifacts

GUI Storage

Persistent storage artifact. Per-player or group-based item persistence with accumulation support.

​
Guides

Understanding Menu Structure

Visual deep-dive into coordinates, layout types, item placement, and storage. Start here if you’re new.

Building Menus — Complete Guide

Step-by-step walkthroughs from simple to complex. All 7 layout types, interactions, storage, and best practices.

Ready-to-Use Demo Pages

Drop-in Typewriter page files — Storage Vault, Vanilla GUI showcase. Copy, paste, reload and play.

​
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
→ Full Guide: Building Menus → 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

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

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.