Bedrock & Floodgate Support

Cross-play servers powered by Geyser and Floodgate allow Minecraft Bedrock Edition players on iOS, Android, Xbox, PlayStation, Nintendo Switch, and Windows 10/11 to join standard Java Paper servers.

However, classic Java chest GUIs create significant friction on touchscreens and consoles: players must navigate emulated inventory slots with a sluggish virtual cursor, struggle with drag-and-drop actions, and endure inventory desynchronization.

Steal-A-Block resolves this by integrating direct support for Native Bedrock JSON Forms (Cumulus protocol). Bedrock players receive smooth, mobile-friendly modal windows, large clickable action tiles, and native toggle switches rather than virtual chest containers.

---

Why Native Bedrock Forms Matter

flowchart TD
    subgraph Traditional Java Chest GUI on Bedrock
        A1["Emulated 54-Slot Chest Window"] --> A2["Virtual Cursor Dragging Required"]
        A2 --> A3["High Misclick Rate on Mobile Screens"]
        A3 --> A4["Frequent Inventory Desync & Lag"]
    end
    subgraph StealABlock Native Bedrock Forms
        B1["Cumulus Native JSON Protocol"] --> B2["Full-Screen Native UI Dialogs"]
        B2 --> B3["Large Touch-Friendly Action Buttons"]
        B3 --> B4["Zero Container Desync • Instant Response"]
    end
    A1 -. Upgrade .-> B1

Interface Characteristic	Traditional Java Chest GUI	Steal-A-Block Native Bedrock Form
Mobile Touch Target Size	Tiny $16 \times 16$ pixel inventory slots	Large full-width native buttons
Controller Navigation	Slow virtual cursor dragging	Rapid directional D-pad snapping
Network Overhead	Continuous slot update packets	Single lightweight JSON form packet
Settings Toggles	Click to swap wool/dye item states	Native Bedrock toggle switches (on/off)
Client Appearance	Standard wooden chest container	Native Bedrock client theme and layout

---

Prerequisites & Architecture

Steal-A-Block requires no external bridges or extra addons. Its Bedrock engine hooks directly into the Floodgate API at runtime.

System Requirements

Component	Minimum Version	Role
Server Software	Paper or Purpur 1.21+	Primary server software running Steal-A-Block
Geyser-Spigot	Latest 1.21+ build	Translates Bedrock network packets to Java
Floodgate	2.2.0+	Handles Bedrock player authentication and native form transmission
PlaceholderAPI	2.11.0+ (Optional)	Expands dynamic server placeholders within Bedrock menus

Safe Soft-Dependency Architecture

Steal-A-Block employs an isolated adapter pattern (BedrockHook) to manage Bedrock integration:

flowchart LR
    Start["Server Boots"] --> Check{"Floodgate / Geyser Present?"}
    Check -- Yes --> LoadAdapter["Bind FloodgateAdapter<br>(Enables Cumulus JSON Forms)"]
    Check -- No --> LoadNoOp["Bind NoOpAdapter<br>(Zero Class Loading • Pure Java)"]

• Zero Class-Loading Overhead: If Floodgate is absent, the plugin initializes a silent NoOpAdapter. Floodgate classes are never referenced or linked by the JVM, preventing any ClassNotFoundException errors on pure Java setups.
• Dual Fallback Engine: The hook attempts to transmit forms through FloodgateApi.getInstance().sendForm() first. If running under standalone Geyser without Floodgate, it falls back gracefully to GeyserApi reflection.

---

Configuration Reference (bedrock-menu.yml)

The Bedrock menu interface is customized in plugins/StealABlock/bedrock-menu.yml. Edits can be applied live with /sab reload.

Global Menu Options

# Enable or disable native Bedrock form integration globally
enabled: true

# Form title displayed in the Bedrock client header
title: "&b&lStealABlock &8» &fMenu"

# Header description displayed directly above the action buttons
content: |
  &7Welcome back, &f{player}&7!
  &7Your stats at a glance:
  &8• &7Balance: &a${balance}
  &8• &7Rebirth: &d{rebirth} &8| &7Prestige: &6{prestige}
  &8• &7Credits: &b{credits}

  &7Select an option below:

Supported Dynamic Placeholders

The form generator parses both built-in tokens and PlaceholderAPI identifiers across all titles, descriptions, and button labels:

Placeholder Token	Replacement Value	Formats Available
{player}	Bedrock player's gamertag/username	Alex, Steve_Xbox
{balance} / {money}	Formatted player cash balance	$1.2K, $450.00, $12.4M
{rebirth}	Current rebirth level count	0, 3, 30
{prestige}	Current prestige tier count	0, 1, 2
{credits}	Stored premium credits balance	45, 120
%...%	Any registered PlaceholderAPI placeholder	%vault_eco_balance%, %server_online%

Color Code & Hex Palette Parsing

Bedrock clients do not parse standard Java MiniMessage tags or custom hex codes natively. Steal-A-Block features an automated translation pipeline (BedrockFormUtil):

1. Standard Color Codes: Codes from &0 through &f, along with format codes &l (bold) and &o (italic), are automatically translated into Bedrock section-sign tokens (§).
2. Hex RGB Downsampling: Any hex strings (&#RRGGBB or &x&r&r&g&g&b&b) are mapped to the closest legacy Bedrock color palette using weighted Euclidean distance matching:

$$\Delta E = \sqrt{0.30 \cdot (R_1 - R_2)^2 + 0.59 \cdot (G_1 - G_2)^2 + 0.11 \cdot (B_1 - B_2)^2}$$

This formula matches the human eye's natural sensitivity to green wavelengths, ensuring vivid brand accents (such as &#00FF12) render cleanly as vibrant emerald green on Bedrock screens.

---

Action Handlers & Button Structure

Each button in bedrock-menu.yml specifies a display label, an icon reference, and an action handler. Buttons render in the exact sequence they appear in the file.

buttons:
  rebirth:
    text: "&d&l✦ Rebirth\n&7Earn permanent multipliers"
    icon:
      type: "PATH"
      path: "textures/items/experience_bottle"
    action: "OPEN_REBIRTH"

  prestige:
    text: "&6&l✦ Prestige\n&7Unlock new floors & limits"
    icon:
      type: "PATH"
      path: "textures/items/nether_star"
    action: "OPEN_PRESTIGE"

  fusion:
    text: "&b&l✦ Fusion\n&7Upgrade 4x same block"
    icon:
      type: "PATH"
      path: "textures/ui/anvil_icon"
    action: "OPEN_FUSION"

  map:
    text: "&a&l✦ Map\n&7Pick an arena and join"
    icon:
      type: "PATH"
      path: "textures/items/map_empty"
    action: "OPEN_MAP"

  heist_board:
    text: "&2&l✦ Heist Board\n&7Daily contracts & rewards"
    icon:
      type: "PATH"
      path: "textures/items/emerald"
    action: "OPEN_CONTRACTS"

  index:
    text: "&e&l✦ Index\n&7Discovered / undiscovered blocks"
    icon:
      type: "PATH"
      path: "textures/items/book_written"
    action: "OPEN_INDEX"

  milestones:
    text: "&6&l✦ Milestones\n&7Collect & claim rewards"
    icon:
      type: "PATH"
      path: "textures/items/book_enchanted"
    action: "OPEN_MILESTONES"

  cosmetics:
    text: "&d&l✦ Cosmetics\n&7Armor trims & name colors"
    icon:
      type: "PATH"
      path: "textures/items/netherite_chestplate"
    action: "OPEN_COSMETICS"

  help:
    text: "&f&l✦ Help\n&7Commands & gameplay guide"
    icon:
      type: "PATH"
      path: "textures/items/sign"
    action: "OPEN_HELP"

  settings:
    text: "&8&l✦ Settings\n&7HUD, guide & event bars"
    icon:
      type: "PATH"
      path: "textures/items/comparator"
    action: "OPEN_SETTINGS"

  custom_spawn:
    text: "&e&l✦ Spawn\n&7Return to server lobby"
    icon:
      type: "PATH"
      path: "textures/items/ender_pearl"
    action: "COMMAND"
    command: "spawn"

  close:
    text: "&c&l✘ Close"
    icon:
      type: "PATH"
      path: "textures/ui/cancel"
    action: "CLOSE"

Complete Action Types Catalog

Action Identifier	Alternative Aliases	Description
OPEN_REBIRTH	REBIRTH	Opens the interactive Rebirth modal form with cost verification.
OPEN_PRESTIGE	PRESTIGE	Opens the Prestige modal form with vertical floor status.
OPEN_FUSION	FUSION	Opens the 4-to-1 block fusion chamber interface.
OPEN_GEAR	GEAR	Opens the tactical gear vendor shop.
OPEN_MAP	MAP, OPEN_ARENAS, ARENAS	Displays available arenas with live occupancy counts.
OPEN_CONTRACTS	CONTRACTS, OPEN_HEIST_BOARD	Opens the daily heist board and active job rewards.
OPEN_INDEX	INDEX	Displays cataloged and undiscovered block definitions.
OPEN_MILESTONES	MILESTONES	Tracks lifetime block collection milestones and rewards.
OPEN_COSMETICS	COSMETICS	Opens the wardrobe for armor trims and chat nametag colors.
OPEN_HELP	HELP	Dispatches the gameplay tutorial and command reference.
OPEN_SETTINGS	SETTINGS	Opens the Bedrock toggle switches form for client preferences.
COMMAND	—	Executes a custom server command as the clicking player (command: "...").
CLOSE	—	Closes the open Bedrock form window without further action.

---

Client Texture Paths & Custom Icons

Bedrock buttons can display icons loaded directly from the client's internal texture repository (type: "PATH") or from a public web server (type: "URL").

flowchart LR
    B["Button Definition"] --> T{"Icon Type?"}
    T -- "PATH" --> C["Bedrock Client Asset<br>(e.g. textures/items/nether_star)"]
    T -- "URL" --> W["Public Web Image<br>(e.g. https://domain.xyz/icon.png)"]

Recommended Client Texture Paths

Using native PATH references requires zero image downloads and renders instantly on all devices:

Texture Path	Visual Icon	Recommended Usage
textures/items/experience_bottle	Experience Bottle	Rebirth Station
textures/items/nether_star	Nether Star	Prestige System / Confirmation
textures/ui/anvil_icon	Anvil Graphic	Block Fusion Chamber
textures/items/map_empty	Empty Map	Arena Selector
textures/items/emerald	Emerald Gem	Daily Heist Board / Economy
textures/items/book_written	Written Book	Block Index Catalog
textures/items/book_enchanted	Enchanted Book	Milestones / Perks Guide
textures/items/netherite_chestplate	Netherite Armor	Cosmetics Wardrobe / Trims
textures/items/name_tag	Name Tag	Chat & Nametag Colors
textures/items/sign	Oak Sign	Help & Commands Guide
textures/items/comparator	Redstone Comparator	Settings Configuration
textures/blocks/iron_bars	Iron Bars	Prestige Ascension Confirm
textures/ui/cancel	Red Cross Barrier	Close Menu / Back Button

---

Sub-Menu Forms Configuration

In addition to the primary menu dashboard, bedrock-menu.yml defines the layout and text for specialized sub-windows:

1. Settings Toggle Form (sub-menus.settings)

Renders native Bedrock on/off slider switches for personal client preferences.

sub-menus:
  settings:
    title: "&8&lPlayer Settings"
    sounds-switch: "Scoreboard Sidebar"
    alerts-switch: "Event Bossbar"
    fastmode-switch: "Block Prices"
    autocollect-switch: "Income ($/s) Displays"
    steal-switch: "Theft Alerts"
    deposit-switch: "Deposit Alerts"

When a Bedrock player toggles these switches, their selections are saved directly to stealablock.db and display entities update instantly.

2. Rebirth Modal Form (sub-menus.rebirth)

Displays current progress, calculates requirements, and prompts confirmation.

sub-menus:
  rebirth:
    title: "&d&lRebirth Station"
    content: |
      &7Current Rebirth: &dLevel {rebirth} &7/ &f{max}
      &7Next Cost: &a${cost}
      &7Your Balance: &e${balance}
      &7Current Income Multiplier: &a{multiplier}x

      {status}
    confirm-button: "&a&lConfirm Rebirth\n&7Cost: ${cost}"
    confirm-icon: "textures/items/nether_star"
    perks-button: "&eRebirth Perks Info\n&7View all bonuses"
    perks-icon: "textures/items/book_enchanted"
    back-button: "&cBack to Menu\n&7Return to main menu"
    back-icon: "textures/ui/cancel"

  rebirth-perks:
    title: "&e&lRebirth Perks"
    content: |
      &e&lRebirth Multipliers:
      &7• Tier 1: &a+25% base block income
      &7• Tier 3: &a+75% income + unlocks Bank Vault
      &7• Tier 5: &a+125% income + Diamond gear access
      &7• Tier 10: &a+250% income + Netherite gear
      &7• Tier 20: &a+500% income + Special gear
    back-button: "&aBack to Rebirth"
    back-icon: "textures/ui/cancel"

3. Arena Selector & Milestones (sub-menus.arenas)

sub-menus:
  arenas:
    title: "&b&lArena Selector"
    content: "&7Choose an arena to enter:"
    entry-format: "&e{id} &7- {status}\n&7Players: {count}/{max}"
    status-full: "&c[FULL]"
    status-joinable: "&a[JOINABLE]"
    back-button: "&cBack to Menu"
    back-icon: "textures/ui/cancel"

  milestones:
    title: "&6&lMilestone Tracker"
    content: |
      &6&lYour Progress:
      &7• Total Blocks Stolen: &e{stolen}
      &7• Blocks Discovered: &b{discovered} / {total}

      &7Select a milestone to view or claim:
    back-button: "&cBack to Menu"
    back-icon: "textures/ui/cancel"

---

Troubleshooting & Common Questions

Form Fails to Open for Bedrock Players

1. Verify Floodgate Installation: Run /floodgate info from the server console. Confirm that Floodgate is running version 2.2.0 or higher.
2. Check Menu Status: Ensure enabled: true is set at the top of bedrock-menu.yml.
3. Player Identification: Confirm the player is connecting through Bedrock. Players using Java clients (even with controller mods) receive Java inventory GUIs instead.

Missing Texture Icons (Magenta & Black Squares)

• Ensure texture paths do not include .png extensions. Correct: textures/items/emerald. Incorrect: textures/items/emerald.png.
• Confirm that the client texture path exists in the current Bedrock client version. Modern items (such as trims) use textures/items/....

MiniMessage Tags Not Displaying Colors

• Bedrock forms communicate via Cumulus JSON, which does not interpret Kyori Adventure MiniMessage tags (e.g., <green>, <bold>).
• Always use standard ampersand formatting codes (&a, &6, &l) or hex tokens (&#00FF12) within bedrock-menu.yml. The plugin automatically translates them to Bedrock formatting.

Custom Commands Fail on Execution

• When using action: "COMMAND", the command executes directly as the player. Ensure Bedrock players have the required permission node for the command (e.g., essentials.spawn).
• Omit the leading slash: use command: "spawn" or command: "warp arena". Both formats are supported.