FormsHandler

FormsHandler is a PocketMine-MP plugin that completely redefines how forms are handled and managed on your server.

PocketMine forms are poorly implemented ; allowing players to move, open inventories, or interact while a form is open, and even respond to forms after closing them.

It solves all of these issues by providing a robust, secure, and extensible form management system designed for reliability.

Planned upcoming features include an optional JSON-UI texture pack providing custom form layouts close to the vanilla aesthetic, as well as DDUI (Data-Driven UI) support.

Overview

General

FormsHandler gives you full control over the form lifecycle through a secure and state-aware management layer:

• Automatic event cancelling when a player moves, interacts, or performs actions while a form is open
• Smart validation ensures responses are only accepted when the form is active and the player is connected
• Prevents players from responding to old or invalid forms, closing them automatically if inconsistencies are detected

Additionally, FormsHandler provides a clean and fluent API, making form creation elegant, safe, and easy for all types of forms.

While FormsHandler is designed to work best with forms created using its own API, it can also handle forms not built through FormsHandler.

However, these external forms have limited support and functionality:

• It's not possible to distinguish between a form being closed and a button being clicked (you have to do it yourself)
• UI enhancements are not available

For the best experience, it's strongly recommended to create forms through the FormsHandler API:

• More complete and secure handling, especially for CustomForms
• Custom layouts will be available in a future update — no JSON-UI knowledge required

Fixed Multi CustomForms Handling (JSON-UI compatibility)

When using JSON-UI on the client side, it’s possible to generate multiple CustomForms at once, each one being shown or hidden dynamically depending on the interface title or bindings.

In most PocketMine form APIs, this behavior causes mismatches between client-side elements and server-side validation: the client sends extra values for hidden CustomForms, while the server expects only the fields from the visible form.

For example:
If a CustomForm defines 5 elements, but the currently visible UI only shows 2 clickable inputs, the player would correctly send responses for these 2 visible elements — but also include data from 3 hidden elements that belong to other hidden CustomForms.

This caused malformed data and API issues when multiple CustomForms coexisted in the same texture pack.

The new validation layer now properly filters, maps, and normalizes responses, ensuring that only visible and active form elements are processed server-side.

Features

Project TODO Progress

• Base implementation of SimpleForm, CustomForm, and ModalForm classes
• Automatically closes forms when a player attempts forbidden actions (movement, inventory use, etc.)
• Ensures that only responses from the currently active form are processed
• Accepts external (non‑FormsHandler) forms with limited functionality
• Logging for form anomalies
• Adds headers, dividers, and labels in CustomForms
• Adds headers, dividers, and labels in SimpleForms
• DDUI support
• JSON-UI texture pack with custom form layouts
• Configurable rules for advanced form behavior

Clean and Expressive API

Form creation becomes simple and readable.

Supported form types:

• Simple Form
• Custom Form
• Modal Form

Simple Form

Without visual elements:

use pocketmine\player\Player;
use FormsHandler\elements\simpleform\Button;
use FormsHandler\types\SimpleForm;

// Create a new SimpleForm
$form = (new SimpleForm())
    ->setTitle("FormsHandler SimpleForm Demo")
    ->setContent("Hey there! This is a Simple Form created with FormsHandler.\nChoose one of the options below:")
    ->addButton(new Button("Say Hello"))
    ->addHeader("Header")
    ->addDivider()
    ->addButton(new Button("How are you?"))
    ->addLabel("Label")
    ->addButton(new Button("I love Minecraft!"))
    ->onSubmit(function(Player $player, mixed $response) {
        $player->sendMessage("You selected option #$response!");
    })
    ->onClose(function(Player $player) {
        $player->sendMessage("You closed the form.");
    });

// Send the form to the player
$player->sendForm($form);

Preview:

Custom Form

use FormsHandler\elements\customform\{Dropdown,Input,Slider,StepSlider,Toggle};
use FormsHandler\types\CustomForm;
use pocketmine\player\Player;

// Create a new CustomForm
$form = (new CustomForm())
    ->setTitle("FormsHandler CustomForm Demo")
    ->addHeader("Welcome to the CustomForm Demo")
    ->addLabel("Hey there! This is a Custom Form created with FormsHandler.\nThis form demonstrates multiple element types provided by FormsHandler.")
    ->addDivider()

    ->addElement(new Input("Your nickname", "Enter your name...", "Steve"))
    ->addElement(new Toggle("Enable notifications"))
    ->addDivider()

    ->addHeader("Preferences")
    ->addElement(new Dropdown("Choose your favorite block", ["Grass Block", "Diamond Block", "TNT", "Crafting Table"]))
    ->addElement(new Slider("Select your skill level", 1, 10, 1, 5))
    ->addElement(new StepSlider("Pick a difficulty", ["Peaceful","Easy","Normal","Hard"]))
    ->addDivider()
    ->addLabel("End of form")

    ->onSubmit(function(Player $player, array $response) {
        // ...
    })
    ->onClose(function(Player $player) {
        $player->sendMessage("You closed the form.");
    });

// Send the form to the player
$player->sendForm($form);

Preview:

Modal Form

use pocketmine\player\Player;
use FormsHandler\types\ModalForm;
use FormsHandler\elements\modalform\Button;

// Create a new ModalForm
$form = (new ModalForm())
    ->setTitle("FormsHandler ModalForm Demo")
    ->setContent("Hey there! This is a Modal Form created with FormsHandler.\nChoose one of the options below:")
    ->setTopButton(new Button("Top button"))
    ->setBottomButton(new Button("Bottom button"))
    ->onSubmit(function(Player $player, bool $response) {
        $player->sendMessage("You selected option #" . (int) $response . "!");
    })
    ->onClose(function(Player $player) {
        $player->sendMessage("You closed the form.");
    });

// Send the form to the player
$player->sendForm($form);

Preview:

JSON-UI Texture Pack (coming soon)

Minecraft Bedrock's native form UI is functional but visually limited — layouts are fixed and offer no customization beyond what the game exposes by default.

To address this, FormsHandler will ship with an optional JSON-UI texture pack that provides custom form layouts designed to blend seamlessly with the vanilla Minecraft aesthetic, while offering a level of polish that is not achievable with the default UI.

The goal is to deliver interfaces that feel native to the game while clearly showcasing the added value of using FormsHandler on your server.

The resource pack will be included directly in the plugin under the /resources directory, automatically copied to the server's resource_packs/ folder on load, and togglable via the configuration file.

Installation

Requirements

Before installing FormsHandler, make sure you have:

• A PocketMine-MP server installed
• The server is up-to-date and capable of running plugins

Installing the plugin

1. Navigate to your server’s plugins/ directory:

   cd plugins
   

2. Clone the repository:

   git clone https://github.com/SwouitAzia/FormsHandler.git
   

3. (Optional) Before starting or restarting your server, you can edit the config.yml to customize features such as the enhanced UI texture pack or other plugin settings.

4. Start or restart your PocketMine server using start.cmd (Windows) or start.sh (Linux/macOS).

The plugin will automatically load, and the default configuration will be applied if no changes are made.

Credits and License

Credits

This project draws inspiration from FormRecode (by Zwuiix), adapting ideas for secure and flexible form handling.

The approach has been extended to provide a robust, clear, and controlled system for managing forms on PocketMine-MP servers.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).

CC BY-NC 4.0