Quick Start

This guide gives you a quick overview of how CommandPanels panel files work, their main parts, and how to get started creating your own custom GUIs. Use /pa [args] for the main plugin command to begin.

Generating Panels

You can use the /pa generate command to quickly create a new panel from a chest's contents.

Once you run the command:

You enter generate mode.
While in generate mode, right-click any chest.
A new panel file will be created using the chest’s layout and items.

This method is perfect for getting an initial layout created for inventory panels in-game, without needing to write YAML manually.

Panel File Basics

Each panel is defined by a YAML file inside the panels folder.
The filename is used as the panel's unique name.
Panels support three types:
- inventory — traditional chest-style GUI with slots.
- dialog — menus using the dialogs feature for Java edition players.
- floodgate — specialised for Bedrock edition players.

Each type has slightly different configuration options, but the core structure remains similar.

Main Panel File Parts

type: The panel type (inventory, floodgate, or dialog).
title: The window title, can use placeholders.
conditions: Logic that determines if the panel should open.
command: Command to open the panel, optionally with arguments.
commands: Commands run before the panel opens.
update-delay: Define how often the panel updates in ticks in Inventory Panels (zero to disable updating).
rows: Number of rows (only for Inventory Panels).
layout: Defines what slots items appear for Inventory Panels and which order components display in for Dialog and Floodgate Panels.
items: Defines the items for the Inventory Panel or the Components for Dialog and Floodgate Panels

Example Panel Files

Example Inventory Panel

Simple Panel with an item in one slot that sends a message when clicked.

title: 'Template Inventory Panel'
type: 'inventory'

rows: 1

layout:
  fill:
    - 'example_empty_item'
  4:
    - 'example_item'

items:
  example_empty_item:
    material: 'BLACK_STAINED_GLASS_PANE'

  example_item:
    material: 'REDSTONE'
    name: 'Example Item'
    animate: 'frame_1'
    left-click:
      commands:
        - '[msg] Hello you clicked me!'

Example Dialog Panel

Displays a custom Dialog Panel for Java Edition players.

title: 'Template Dialog Panel'
type: 'dialog'

columns: 1
has-exit-button: false
escapable: true

layout:
  0:
    - 'welcome_text'
  1:
    - 'confirm_button'

items:
  welcome_text:
    type: 'text'
    name: '&6Welcome to the Dialog Panel!'

  confirm_button:
    type: 'button'
    name: 'Click to Confirm'
    actions:
      commands:
        - '[msg] Thanks for clicking!'

Example Simple Floodgate Panel

Will only open for Bedrock Edition players, a simple Floodgate Form used for buttons.

title: 'Template Floodgate Panel'
type: 'floodgate'

floodgate-type: 'simple'

layout:
  0:
    - 'example_button'

items:
  example_button:
    name: 'Click me!'
    icon:
      type: 'PATH'
      texture: 'textures/items/redstone_dust.png'
    actions:
      commands:
        - '[msg] Hello from a Floodgate panel!'

Example Custom Floodgate Panel

Will only open for Bedrock Edition players, a custom Floodgate Form used for inputs.

title: 'Template Floodgate Panel'
type: 'floodgate'

floodgate-type: 'custom'

layout:
  0:
    - 'inputexample'
  1:
    - 'sliderexample'

items:
  inputexample:
    type: 'input'
    name: 'Text box below'
    placeholder: 'Type here'
    default: ''
    actions:
      commands:
      - '[msg] You said: %commandpanels_session_inputexample%'
  
  sliderexample:
    type: 'slider'
    name: 'Slide the Slider'
    min: 1
    max: 10
    step: 1
    default: 5
    actions:
      commands:
      - '[msg] You chose: %commandpanels_session_sliderexample%'

Understanding Actions and Conditions

CommandPanels uses a powerful and flexible Click Action system that works across all panel types. Understanding how actions and conditions work is key to building interactive and dynamic menus. There are document pages that go into detail on all of these features.

Click Actions

Click Actions are used when a player interacts with a component (like clicking a button or item). These actions support:

Requirement Tags: Optional checks that must pass before commands run.
Command Tags: The actual commands run, such as sending messages, executing server commands, or opening other panels.

This allows for conditional behavior. For example, showing a message if a player doesn't meet the requirement, or opening another panel if they do.

Conditions

Conditions control visibility and behavior. They are used in:

Panels: To determine if a player can open a panel.
Components: To show or hide specific items or buttons.

Conditions are logic, placeholder comparisons, permissions, world checks, and more. This makes panels highly dynamic and customisable per player, world, or server state.

Summary

Feature	Purpose	Where it's Used
Command Tags	Special commands that perform different actions	Inside Command Actions
Requirement Tags	Optional checks before commands run	Inside Command Actions
Conditions	Logic for component or panel visibility	Across all Panel components and Items

Tips

Use placeholders to make your panels dynamic.
Organise your items separately from slots for easier maintenance.
Utilise conditions to customise logic per player or context.
Experiment with animate frames to create visual feedback.
This should help you get started building your first panel quickly!

Generating Panels​

Panel File Basics​

Main Panel File Parts​

Example Panel Files​

Example Inventory Panel​

Example Dialog Panel​

Example Simple Floodgate Panel​

Example Custom Floodgate Panel​

Understanding Actions and Conditions​

Click Actions​

Conditions​

Summary​

Tips​