BedrockGUI v2

BedrockGUI Complete Guide

A comprehensive guide to creating SIMPLE, MODAL, and CUSTOM forms with actions, conditions, and advanced features.

Form Types Overview

BedrockGUI supports three main form types:

• SIMPLE: Button-based menus with multiple options

• MODAL: Yes/No confirmation dialogs (exactly 2 buttons)

• CUSTOM: Input forms with various components (text inputs, toggles, dropdowns, etc.)

General Overview

• Provides Bedrock-style forms on Paper and Velocity; integrates with Floodgate for Bedrock detection

• Unified action system with modern curly-brace syntax and placeholder support

• Supports multi-action sequences, delays, random selection, and conditional logic

• YAML-driven menus plus programmatic builders for dynamic forms

• Admin command to reload and open forms

Action System

• Syntax

  • Use: action_type { - "value1" - "value2" }

• Placeholders: {player}, {player_level}, ${vault_eco_balance} and values derived from form results

Actions

command

• Executes commands as the player

• Examples

  • command {
      - "me hello world"
      - "time query daytime"
    }

server

• Executes commands as the server console

• Examples

  • server {
      - "say {player} ran tests"
      - "time set day"
    }

broadcast

• Broadcasts messages globally or to targeted audiences (permission/world/radius)

• Examples

  • broadcast {
      - "Welcome everyone!"
      - "permission:vip.access:VIP notice"
      - "world:world_nether:Nether alert"
      - "radius:20:Nearby message"
    }

message

• Sends colorized chat messages; supports & and hex colors

• Examples

  • message {
      - "&#00ff99Welcome {player}!"
      - "&aBalance: ${vault_eco_balance}"
    }

sound

• Plays sounds with optional volume and pitch

• Examples

  • sound {
      - "ui.button.click"
      - "entity.experience_orb.pickup:0.8:1.2"
    }

economy

• Balance operations: add, remove, set, check, pay

• Examples

  • economy {
      - "check:500"
      - "add:250"
      - "pay:Friend:100"
    }

title

• Shows title/subtitle with timing fadeIn:stay:fadeOut

• Examples

  • title {
      - "Welcome!:Enjoy your stay:10:60:10"
    }

actionbar

• Shows short messages above the hotbar

• Examples

  • actionbar {
      - "&eLoading..."
      - "&aDone!"
    }

inventory

• Item operations: give:item:amount, remove:item:amount, clear:all|item, check:item

• Examples

  • inventory {
      - "give:diamond:3"
      - "check:diamond"
      - "clear:all"
    }

open

• Opens another form/menu

• Examples

  • open {
      - "main_hub"
      - "advanced_test_menu"
    }

delay

• Waits for milliseconds, then optionally runs a chained action

• Examples

  • delay {
      - "1000"
      - "message:After 1 second"
    }

random

• Selects and executes one action from a list; last colon may be weight

• Examples

  • random {
      - "message:Prize A:2.0"
      - "message:Prize B:1.0"
    }

url

• Sends HTTP(S) links to the player’s chat (clients render clickable)

• Examples

  • url {
      - "https://store.server.com/{player}"
    }

conditional

• Executes actions based on permission/placeholder checks

• Examples

  • conditional {
      check: "placeholder:${vault_eco_balance} >= 500"
      true:
        - "message:&aYou can afford it!"
        - "economy:add:100"
      false:
        - "message:&cNeed $500"
    }

bungee

• Sends a Plugin message thru the Bungeecord channel (Please reffer to this for more info: https://www.spigotmc.org/wiki/bukkit-bungee-plugin-messaging-channel/ )

• Examples

  • bungee {
          subchannel: "Connect"
          - "lobby"
        }
    
    bungee {
          subchannel: "ConnectOther"
          - "{player}"
          - "survival"
        }
    
    bungee {
          subchannel: "Message"
          - "{player}"
          - "§aWelcome to the server!"
        }
    
    bungee {
          subchannel: "KickPlayer"
          - "{player}"
          - "§cYou have been kicked!"
        }

Form Types

Simple Form

• Title, optional description, multiple buttons

• Configuration

  • forms:
      main_hub:
        type: "SIMPLE"
        title: "§a§lMain Hub"
        description: "Welcome, {player}!"
        buttons:
          open_shop:
            text: "Shop"
            onClick:
              - |
                open {
                  - "shop_menu"
                }
          ping:
            text: "Ping"
            onClick:
              - |
                message {
                  - "&aPong!"
                }

Modal Form

• Two buttons (Yes/No-style), optional description

• Configuration

  • forms:
      confirm_buy:
        type: "MODAL"
        title: "Confirm Purchase"
        description: "Buy the item for $250?"
        buttons:
          yes:
            text: "Yes"
            onClick:
              - |
                economy {
                  - "check:250"
                  - "remove:250"
                }
          no:
            text: "No"
            onClick:
              - |
                message {
                  - "&eCancelled"
                }

Custom Form

• Structured inputs and interactive components; optional global actions

• Components

  • input: text, placeholder, default, optional action

  • slider: text, min, max, step, default, optional action

  • dropdown: text, options, default, optional action

  • toggle: text, default, optional action

• Configuration

  • forms:
      feedback_form:
        type: "CUSTOM"
        title: "Feedback"
        components:
          name:
            type: "input"
            text: "Your name"
            placeholder: "Steve"
            default: ""
            action: |
              message {
                - "Thanks, $name!"
              }
          rating:
            type: "slider"
            text: "Rate 1–10"
            min: 1
            max: 10
            step: 1
            default: 5
          category:
            type: "dropdown"
            text: "Category"
            options: [ "Bug", "Suggestion", "Other" ]
            default: 0
          anonymous:
            type: "toggle"
            text: "Send anonymously?"
            default: false
        global_actions:
          - |
            message {
              - "Submitted by $name"
            }
          - |
            message {
              - "Category $category, Rating $rating, Anonymous $anonymous"
            }

Conditional Buttons (Simple/Modal)

• Show/hide or change text/image/onClick based on conditions

• Keys: show_condition, alternative_text, alternative_image, alternative_onClick, conditions.*

• Evaluated when the form is built

Tips

• Use placeholders to personalize messages and actions (e.g., {player}, ${vault_eco_balance})

• Combine actions for guided flows using multiple list items under a button’s onClick

Menu Configuration Quick Reference

• Under forms.<menu_name>

  • type: SIMPLE | MODAL | CUSTOM

  • title: text (color codes supported)

  • description: optional (Simple/Modal)

  • permission: optional required permission

  • buttons: for Simple/Modal (with text, optional image, onClick list)

  • components: for Custom (with fields per type)

  • global_actions: actions run after Custom submit

• Command binding example in config.yml

  • commands:
      gui:
        description: "Open the main BedrockGUI hub"
        permission: "bedrockgui.use"
        aliases: [ "menu", "hub", "main" ]
        form: "main_hub"

Placeholders

• Built-ins: {player}, {player_level}, {player_gamemode}, {player_world}, ${vault_eco_balance}

• Applied inside action handlers before execution; injected into ActionContext

Admin Command

• Paper: /bedrockgui with bedrockgui.admin permission

• Velocity: /bedrockgui reload, /bedrockgui open <menu> [player]

Composition Examples

• Guided sequence

  • message { - "&eStarting..." }
    sound { - "ui.button.click" }
    delay { - "1000" - "message:Step 2" }
    random { - "title:Prize A" - "title:Prize B" }

• Server operations

  • server { - "tp {player} spawn" - "gamemode survival {player}" }

Best Practices

1. Form Design

• Keep titles concise and descriptive

• Use color codes consistently

• Provide clear descriptions

• Use appropriate icons/images

2. Action Chaining

• Use delays between actions for better UX

• Provide feedback for every action

• Handle error cases gracefully

• Use sounds to enhance experience

3. Conditional Logic

• Always provide fallback actions

• Test edge cases thoroughly

• Use clear error messages

• Validate user permissions

4. Performance

• Avoid excessive action chains

• Use appropriate delay times

• Limit form complexity

• Cache frequently used data

5. User Experience

• Provide confirmation for destructive actions

• Use consistent navigation patterns

• Offer help/tutorial options

• Support different player types (new/experienced)

6. Security

• Validate all user inputs

• Check permissions thoroughly

• Sanitize placeholder values

• Limit resource-intensive operations

---

Placeholder Support

BedrockGUI supports various placeholder types:

Built-in Placeholders

• {player} - Player name

• {player_world} - Current world

• {player_health} - Player health

• {player_x}, {player_y}, {player_z} - Player coordinates

• {server_online} - Online player count

• {server_max} - Max player count

• {balance} - Player balance (if economy enabled)

PlaceholderAPI Support

All PlaceholderAPI placeholders are supported when the plugin is installed:

• %player_name% - Player name

• %player_world% - Current world

• %vault_eco_balance% - Economy balance

• And thousands more from various plugins

Note: PlaceholderAPI placeholders work in all contexts including:

• Action data (messages, commands, etc.)

• Conditional action conditions and values

• Form titles, descriptions, and button text

• Show conditions for buttons and forms

Form Result Placeholders

Results from custom forms can be used as placeholders:

• {component_name} - Value from form component

• {input_field} - Text input value

• {toggle_state} - Toggle true/false

• {dropdown_selection} - Selected dropdown option

---

This guide covers all major features of BedrockGUI. For more advanced configurations and custom implementations, refer to the source code and example configurations provided with the plugin.