README

EasyUIBuilder v2.0.0

A PHP library for generating Minecraft Bedrock Edition JSON UI files using a fluent builder pattern. Build complex UI screens with clean, readable code — and output Minecraft-compatible resource packs automatically.

Features

Fluent API — chainable methods for all UI elements
Auto-generation of _ui_defs.json and server_form.json
All Bedrock UI types — Label, Panel, Button, Image, Grid, StackPanel, Toggle, Slider, EditBox, ScrollView, Dropdown, InputPanel, Screen, CustomRender
Binding system — global, view, collection and visibility bindings
Animation system — alpha, offset, size, color, clip, flip_book with 30+ easings
Variable system — conditional variables for platform/input-specific layouts
Modification system — non-intrusive edits to vanilla UI elements (insert, remove, replace, swap, move)
JSON validation — automatic schema validation of generated files against Bedrock UI rules
Utility elements — CloseButton, PlayerRender (pre-built components)
Color utilities — predefined colors, RGB, random, pastel, complementary
Anchoring system — 9-point anchor positioning with offsets
Sizing modes — pixel, percentage, custom array sizes
RootBuild system — register screen definitions and auto-generate packs

Installation

Requirements: PHP 8.0 or higher

Via Composer

composer require refaltor/easy-ui-builder

Manual

Clone the repository and include the autoloader:

spl_autoload_register(function (string $classname): void {
    if (str_contains($classname, "refaltor\\")) {
        require_once("./src/" . str_replace("\\", "/", $classname) . ".php");
    }
});

Quick Start

use refaltor\ui\builders\Root;
use refaltor\ui\elements\Label;
use refaltor\ui\colors\BasicColor;

$root = Root::create("my_namespace");
$root->addElement(
    Label::create("hello", "Hello Minecraft!")
        ->setFontSize(Label::FONT_EXTRA_LARGE)
        ->setShadow()
        ->setColor(BasicColor::yellow())
);
$root->generateAndSaveJson("ui/my_screen.json");

UI Elements

Core Elements

Element	Description
Label	Text with font size/type/scale, shadow, color
Panel	Container with visibility, alpha, clipping, scissor
Button	Interactive button with 4-state textures, factory system
Image	Texture with UV, 9-slice, tiling, clip, grayscale
Grid	Dynamic grid layout with templates and fill direction
StackPanel	Auto-layout container (vertical/horizontal)

Extended Elements

Element	Description
Toggle	Checkbox/switch with radio groups, checked/unchecked controls
Slider	Value cursor with steps, direction, box/track controls
EditBox	Text input with placeholder, max length, text types
ScrollView	Scrollable container (vertical/horizontal)
Dropdown	Dropdown menu with items
InputPanel	Input handling with focus navigation, button mappings, modal
Screen	Screen root element with render flags, input absorption
CustomRender	Native renderers (paper_doll, inventory_item, panorama...)

Utility Elements

Element	Description
CloseButton	Pre-built close button extending Bedrock's common dialog
PlayerRender	Pre-built player skin viewer

Component Systems

Component	Description
Binding	Data bindings (global, view, collection, visibility)
Animation	UI animations with 30+ easings and chaining
Variable	Conditional variables for adaptive layouts
Modification	Non-intrusive edits to vanilla UI (insert, remove, replace, swap, move)

Modifications System (v2.0)

The modifications system lets you edit vanilla Bedrock UI elements without replacing entire files. This improves compatibility across resource packs.

All Operations

Operation	Description
`insert_back`	Insert at end of array
`insert_front`	Insert at start of array
`insert_after`	Insert after a target element
`insert_before`	Insert before a target element
`move_back`	Move target to end of array
`move_front`	Move target to start of array
`move_after`	Move target after another element
`move_before`	Move target before another element
`swap`	Swap two elements
`replace`	Replace an element
`remove`	Remove an element

Element-Level Modifications

Add modifications directly to any element:

use refaltor\ui\components\Modification;

$panel = Panel::create("my_panel")
    ->addModification(
        Modification::insertBack(Modification::ARRAY_CONTROLS)
            ->setValue([
                ["new_child@common.empty_panel" => []]
            ])
    )
    ->addModification(
        Modification::remove(Modification::ARRAY_BINDINGS, [
            "binding_name" => "#obsolete_binding"
        ])
    );

Vanilla Element Modifications

Target vanilla UI elements using path syntax on the Root builder:

use refaltor\ui\components\Modification;

$root = Root::create("my_namespace");

// Hide the HUD title when text matches a value
$root->modifyVanillaElement("hud_title_text/title_frame/title", [
    Modification::insertBack(Modification::ARRAY_BINDINGS)
        ->setValue([
            [
                "binding_type" => "view",
                "source_property_name" => "(not (#text = 'hidden'))",
                "target_property_name" => "#visible",
            ]
        ]),
]);

// Add a custom element to the HUD screen
$root->modifyVanillaElement("hud_screen", [
    Modification::insertBack(Modification::ARRAY_CONTROLS)
        ->setValue([
            ["my_element@my_namespace.my_panel" => []]
        ]),
]);

// Replace a binding in a vanilla element
$root->modifyVanillaElement("start_screen/play_button", [
    Modification::replace(Modification::ARRAY_BINDINGS, [
        "binding_name" => "#old_binding"
    ])->setValue([
        "binding_name" => "#new_binding",
        "binding_type" => "global",
    ]),
]);

// Swap two bindings
$root->modifyVanillaElement("inventory_screen/root_panel", [
    Modification::swap(
        Modification::ARRAY_BINDINGS,
        ["binding_name" => "#binding_a"],
        ["binding_name" => "#binding_b"]
    ),
]);

Available Target Arrays

Use the constants for array_name:

Constant	Value
`Modification::ARRAY_CONTROLS`	`controls`
`Modification::ARRAY_BINDINGS`	`bindings`
`Modification::ARRAY_VARIABLES`	`variables`
`Modification::ARRAY_ANIMS`	`anims`
`Modification::ARRAY_BUTTON_MAPPINGS`	`button_mappings`

JSON Validation (v2.0)

Generated JSON files are automatically validated against Bedrock UI rules before writing. The validator checks:

Element types (14 valid Bedrock types)
Property names per element type (strict mode)
Anchor values (9-point system)
Size/offset format and color ranges
Binding structure (type, required fields per binding type)
Animation types (9 types), easings (32 values), duration, from/to
Variable structure (requires field, values)
Modification operations (11 types) and required fields
_ui_defs.json structure and duplicates
Custom renderer names (20 known renderers)

Configuration

$entry = new Entry();

// Disable validation entirely
$entry->setValidationEnabled(false);

// Enable strict mode (warns about unknown properties)
$entry->setStrictValidation(true);

Standalone Usage

use refaltor\ui\validators\JsonValidator;

$validator = new JsonValidator(strict: true);
$result = $validator->validate($jsonData);

foreach ($result->getErrors() as $error) {
    echo "ERROR: $error\n";
}
foreach ($result->getWarnings() as $warning) {
    echo "WARNING: $warning\n";
}

echo $result->isValid() ? "Valid!" : "Invalid.";

RootBuild System

To create a new UI screen, implement the RootBuild interface:

class MyScreen implements RootBuild
{
    public function root(): Root
    {
        $root = Root::create();
        $root->addElement(
            Label::create("title", "My Screen")
                ->setFontSize(Label::FONT_EXTRA_LARGE)
                ->setShadow()
        );
        return $root;
    }

    public function getNamespace(): string { return "my_screen"; }
    public function getPathName(): string { return "./resources/pack_example/"; }
    public function titleCondition(): string { return "MY_SCREEN"; }
}

Examples

The tests/ directory contains complete examples for every feature:

File	Description
`LabelExample.php`	Font sizes, types, colors, shadows, scaling
`PanelExample.php`	Nested panels, background images, alpha, clipping
`ButtonExample.php`	Custom textures, visibility conditions, factory
`ImageExample.php`	Tiling, nineslice, UV mapping, grayscale, fill
`GridExample.php`	Grid dimensions, item templates, fill direction
`StackPanelExample.php`	Vertical and horizontal layouts
`FullMenuExample.php`	Complete game menu combining all elements
`ColorExample.php`	All BasicColor functions
`ToggleExample.php`	Toggle, radio groups, checked/unchecked controls
`SliderExample.php`	Horizontal/vertical sliders, steps, controls
`EditBoxExample.php`	Text/number input, placeholder, locked fields
`ScrollViewExample.php`	Vertical/horizontal scroll, chat jump-to-bottom
`DropdownExample.php`	Gamemode, difficulty, language dropdowns
`InputPanelExample.php`	Modal dialog, focus nav, gesture tracking
`ScreenExample.php`	Modal/HUD/cached screens, close on hurt
`CustomRenderExample.php`	Paper doll, item renderer, gradient, vignette
`BindingExample.php`	Global, view, collection bindings, visibility
`AnimationExample.php`	Fade, slide, pulse, bounce, elastic, chain, clip
`VariableExample.php`	Platform, input-mode, screen-size conditionals
`ModificationExample.php`	All modification operations, vanilla element targeting

Running

php start.php

Generated files are output to resources/pack_example/:

ui/_ui_defs.json — UI definitions registry
ui/server_form.json — Server form configuration
ui/custom_ui/<namespace>.json — Individual UI screen files

Validation results are displayed during generation:

===== Building my_screen =====
[INFO] [VALIDATION] my_screen/_ui_defs: no issues found
[INFO] File ./resources/pack_example/ui/_ui_defs.json ready
[INFO] File ./resources/pack_example/ui/server_form.json ready
[INFO] [VALIDATION] my_screen: no issues found
[INFO] File ./resources/pack_example/ui/custom_ui/my_screen.json ready, resource pack built

[INFO] Validation complete: no issues found.

Changelog

v2.0.0

Modifications system — 11 operations to edit vanilla UI elements non-intrusively
Vanilla element targeting — path syntax (hud_screen/hud_title_text) via Root::modifyVanillaElement()
JSON validation — automatic schema validation with JsonValidator (types, bindings, animations, modifications)
Strict validation mode — detect unknown properties per element type
English log output — all build/validation messages in English
JSON_UNESCAPED_SLASHES — proper path output in generated JSON

v1.1.0

JSON schema validation — initial validation system

v1.0.0

Initial release with 14 element types, bindings, animations, variables

Wiki

For full API documentation: https://github.com/Refaltor77/EasyUIBuilder/wiki

refaltor / easy-ui-builder

Maintainers

Package info

Statistics

Security