Back to mods
x4ui project artwork

CurseForge · Minecraft mod

x4ui

Is a UI framework for my mods.

Choose a version Pick your version below, then grab the matching file.

Quick answer

Which x4ui release should I use?

Updated today
beta file x4ui-r1.0b6.jar
Game version 1.12.2
Loader Forge

x4ui-r1.0b6.jar targets 1.12.2 with Forge. The project page does not say whether this file belongs on the client, dedicated server, or both. No extra mods listed for this file.

Where it goes

Is x4ui required on the client, server, or both?

The project page does not say whether this file belongs on the client, dedicated server, or both.

Client Source doesn’t say
Dedicated server Source doesn’t say
Loader for this release Forge
Required install it here Optional supported, not mandatory Not supported do not install here Source doesn’t say do not assume

The source does not explicitly classify this release as client-only or server-only.

What else does x4ui-r1.0b6.jar need?

x4ui-r1.0b6.jar. Change the file and its required mods may change too.

No extra mods listed for this file

This file does not list any required mods. Do not add a library just because a different file uses it.

This file does not list any required or optional mods.

Before you install it

Add x4ui without breaking your instance.

Built for x4ui-r1.0b6.jar. Pick another file and the loader, install side or required mods may change.

  1. 01

    Stick to this file

    Use x4ui-r1.0b6.jar. It targets 1.12.2 with Forge; another release may have different loader, side or dependency requirements.

  2. 02

    Bring the mods it needs

    This file does not list any required mods. Do not add a library just because a different file uses it.

  3. 03

    Put it on the correct side

    The project page does not say whether this file belongs on the client, dedicated server, or both.

  4. 04

    Pick the file you checked

    Use the “Get this file” button beside x4ui-r1.0b6.jar. It opens that exact file at the source.

About this project

What does x4ui add?

X4UI Framework

Retained-mode UI, reactive state, and server–client framework for Minecraft Forge 1.12.2 & CleanroomMC.

English • Español


English

What X4UI Solves

Vanilla GuiScreen and GuiContainer rely on immediate-mode drawing inside drawScreen(), manual pixel coordinates, raw OpenGL state mutation, and tight coupling between rendering and game logic. Interfaces built directly on vanilla primitives break under GUI Scale 3–4, leak listeners or native resources, and fail across Forge 1.12.2 (Java 8 + LWJGL 2) and CleanroomMC (Java 25 + LWJGL 3).

X4UI (r1.0b6) replaces ad-hoc GUI code with a deterministic, retained-mode UI framework engineered around strict runtime portability, reactive state management, and decoupled server–client communication.

Core Paradigm & Design Decisions

  • Retained-Mode Component Tree: Every UI is a hierarchy of GuiComponent nodes rooted in rootPanel. Layout and render-order sorting execute lazily via dirty flags (requestLayout(), requestRender()), rather than recalculating geometry on every frame.
  • API / Implementation Isolation: Public interfaces (IGraphics, IFont, IMediaService) live in com.x4yi.x4ui.api.*, while OpenGL, TrueType rasterization, and FFmpeg/JCodec backends reside in com.x4yi.x4ui.impl.*.
  • Dual-Runtime Abstraction (PlatformBridge): Packaged as a Multi-Release JAR (Java 8 base + META-INF/versions/21/) so Cleaner, I/O executors, KeyCodes, UIInput, and IGraphics run transparently on both Forge 1.12.2 (Java 8) and CleanroomMC (Java 25).
  • Reactive State with Lifecycle Cleanup: State<T> and UIStateBus (Scope.SCREEN, Scope.SESSION, Scope.GLOBAL) decouple views from data sources; component.bindState(...) unsubscribes automatically on destroy().
  • Server-Optional Networking: UINetwork provides remote screen opening (ScreenRegistry), batched state sync (PacketStateBatch), request–response RPC (PacketGuiRpc), and multi-player channels (UIChannels) protected by ActionGuard and per-action rate limiting, while allowing client-only operation on vanilla servers.

Architecture & Systems Overview

System Key Classes Responsibility
Component Tree & Screens GuiBaseScreen, GuiBaseContainer, GuiComponent, GuiPanel Deterministic lifecycle, event bubbling, z-layer sorting, centered modal windows
Responsive Layout FlexLayout, FlexDirection, FlexAlign, GuiScrollPanel Flexbox alignment, percentage sizing, hugContent, automatic scrollbar reservation
Graphics Abstraction IGraphics, GLGraphics Matrix/alpha/tint/scissor stack, rounded primitives, clearDepthBuffer(), BGRA textures
Vector Typography IFont, TrueTypeFont, VanillaFont, FontRegistry TrueType/OpenType glyph atlas, vanilla § formatting, LRU width cache, F3+T reload
Reactive State State<T>, UIStateBus Thread-safe observable values with SCREEN/SESSION/GLOBAL scopes and namespaces
Networking & Security UINetwork, ScreenRegistry, UIChannels, ActionGuard Handshake, remote screens, RPC, Pub/Sub channels, distance/OP guards, rate-limiting
Media Pipeline MediaPipeline, MediaManager, SecurityUtils, GuiVideo, GuiImage Async downloads, SSRF/path guards, OS ffmpeg discovery (Linux/macOS/Win) + JCodec fallback
Runtime Compatibility PlatformBridge, KeyCodes, UIInput Java 8/25 Multi-Release support, LWJGL 2/3 key & wheel normalization, displayWidth == 0 guard
Overlays & Integration GuiOverlayManager, OverlayDockManager, IGuiOverlay, JeiPlugin Non-intrusive screen injection, container anchoring, JEI exclusion areas

Installation

Requirements:

  • Runtime: Minecraft Forge 1.12.2 (14.23.5.2847+, Java 8) or CleanroomMC (Java 25)
  • Consumer Build Target: sourceCompatibility = 1.8, targetCompatibility = 1.8

Add the dependency from GitHub Releases or JitPack in build.gradle:

repositories {
    maven { url "https://jitpack.io" }
}

dependencies {
    deobfCompile "com.github.x4yi:X4UI:r1.0b6"
}

Quick Start

package com.example.mymod.client.gui;

import com.x4yi.x4ui.client.gui.base.GuiBaseScreen;
import com.x4yi.x4ui.client.gui.component.GuiButton;
import com.x4yi.x4ui.client.gui.component.GuiLabel;
import com.x4yi.x4ui.client.gui.component.GuiPanel;
import net.minecraft.client.gui.GuiScreen;

public class ExampleScreen extends GuiBaseScreen {

    public ExampleScreen(GuiScreen parent) {
        super(parent, "Example");
    }

    @Override
    protected void initComponents() {
        GuiPanel window = createCenteredWindow(360, 220);

        GuiPanel header = GuiPanel.row(8);
        header.addChild(new GuiLabel(0, 0, "Control Panel", 0xFFFFFFFF));
        header.addChild(GuiPanel.spacer());
        header.addChild(new GuiButton(0, 0, 20, 20, "X", this::closeScreen));

        GuiPanel body = GuiPanel.card(10, 6);
        body.addChild(new GuiButton(0, 0, 0, 22, "Execute Action", () -> {
            sendActionOrLocal("mymod:ping", null, () -> {});
        }).withPercentWidth(1.0f).withVariant(GuiButton.Variant.PRIMARY));

        window.addChild(header);
        window.addChild(body);
        rootPanel.addChild(window);
    }
}

Documentation

Note: Only the X4UI documentation was drafted with AI (Gemini); all technical specifications and examples were reviewed and approved through human testing (X4yi).

Document Scope
00 - Getting Started Requirements, installation, package map, GuiBaseScreen, GuiBaseContainer, fluent API
01 - Core Concepts Retained-mode paradigm, component tree, lifecycle, State<T>, UIStateBus, themes, dirty flags
02 - Remote Assets MediaPipeline, OS ffmpeg discovery, JCodec fallback, SecurityUtils, supported formats
03 - Networking & Sync Sidedness, UINetwork, ScreenRegistry, PacketGuiRpc, UIChannels, ActionGuard, Container sync
04 - Responsive Layout ScaledResolution, GUI Scale 1x–4x standard, FlexLayout, FlexAlign, GuiScrollPanel
05 - Graphics & Rendering IGraphics abstraction, state stack, scissor clipping, drawing primitives, depth & BGRA textures
06 - Typography & Fonts IFont, TrueTypeFont, VanillaFont, FontRegistry, F3+T hot-reload, VRAM discipline
07 - GUI Overlays & Injection IGuiOverlay, GuiOverlayManager, OverlayDockManager, ContainerAnchor
08 - Integrations & Best Practices JEI integration, naming conventions, decoupled views, memory safety, anti-pattern reference
09 - Forge & CleanroomMC Compatibility Java 8 ↔ Java 25 portability, PlatformBridge, KeyCodes, UIInput, reobfJar rules
Buttons & Inputs GuiButton, GuiTextInput, GuiToggle, GuiSliderInt / Float / Double
Containers & Panels GuiPanel, GuiCard, GuiScrollPanel, GuiSlot
Multimedia GuiImage (URL, ResourceLocation, 9-slice), GuiVideo (async player & error handling), GuiAudio, GuiSprite
Advanced Components GuiVirtualList, GuiDropdown, GuiMarkdown, GuiModelRender, GuiTooltip

License

X4UI is licensed under the GNU General Public License v3 (GPL-3.0).


Español

Qué Soluciona X4UI

El sistema nativo de GuiScreen y GuiContainer depende de renderizado en modo inmediato dentro de drawScreen(), coordenadas absolutas en píxeles, mutación directa de OpenGL y acoplamiento entre vista y lógica. Las interfaces construidas directamente sobre vanilla se rompen en GUI Scale 3–4, filtran listeners o memoria nativa y fallan entre Forge 1.12.2 (Java 8 + LWJGL 2) y CleanroomMC (Java 25 + LWJGL 3).

X4UI (r1.0b6) reemplaza el código ad-hoc por un framework de modo retenido diseñado con portabilidad dual de runtime, estado reactivo con limpieza automática y comunicación servidor–cliente desacoplada.

Paradigma y Decisiones de Diseño

  • Árbol de Componentes en Modo Retenido: Toda interfaz es una jerarquía de nodos GuiComponent bajo rootPanel. El cálculo de diseño y el ordenamiento de capas se ejecutan bajo demanda mediante banderas sucias (requestLayout(), requestRender()), evitando recálculos por fotograma.
  • Separación api / impl: Las interfaces públicas (IGraphics, IFont, IMediaService) residen en com.x4yi.x4ui.api.*, mientras que OpenGL, rasterización TrueType y backends FFmpeg/JCodec se aíslan en com.x4yi.x4ui.impl.*.
  • Abstracción Dual de Runtime (PlatformBridge): Empaquetado como Multi-Release JAR (Java 8 base + META-INF/versions/21/) para que Cleaner, executors de I/O, KeyCodes, UIInput e IGraphics operen de forma transparente en Forge 1.12.2 (Java 8) y CleanroomMC (Java 25).
  • Estado Reactivo Ligado al Ciclo de Vida: State<T> y UIStateBus (Scope.SCREEN, Scope.SESSION, Scope.GLOBAL) desacoplan la vista de los datos; component.bindState(...) desuscribe los listeners automáticamente al ejecutar destroy().
  • Red Server-Optional: UINetwork ofrece apertura remota de pantallas (ScreenRegistry), lotes de estado (PacketStateBatch), RPC request–response (PacketGuiRpc) y canales multi-jugador (UIChannels) protegidos con ActionGuard y rate-limiting, sin impedir la ejecución client-only en servidores vanilla.

Resumen de Arquitectura y Sistemas

Sistema Clases Clave Responsabilidad
Árbol y Pantallas GuiBaseScreen, GuiBaseContainer, GuiComponent, GuiPanel Ciclo de vida determinista, propagación de eventos, orden Z, ventanas modales
Diseño Responsivo FlexLayout, FlexDirection, FlexAlign, GuiScrollPanel Alineación flexbox, tamaños porcentuales, hugContent, reserva de scrollbar
Abstracción Gráfica IGraphics, GLGraphics Pila de matrices/alfa/tinte/scissor, primitivas, clearDepthBuffer(), texturas BGRA
Tipografía Vectorial IFont, TrueTypeFont, VanillaFont, FontRegistry Atlas TrueType/OpenType, códigos §, caché LRU de anchos, recarga F3+T
Estado Reactivo State<T>, UIStateBus Contenedores thread-safe con alcances SCREEN/SESSION/GLOBAL y namespaces
Red y Seguridad UINetwork, ScreenRegistry, UIChannels, ActionGuard Handshake, pantallas remotas, RPC, canales Pub/Sub, guardas y rate-limiting
Pipeline Multimedia MediaPipeline, MediaManager, SecurityUtils, GuiVideo, GuiImage Descargas asíncronas, protección SSRF/path, ffmpeg en OS + fallback JCodec
Compatibilidad Dual PlatformBridge, KeyCodes, UIInput Soporte Java 8/25 Multi-Release, normalización LWJGL 2/3, guarda displayWidth == 0
Overlays e Inyección GuiOverlayManager, OverlayDockManager, IGuiOverlay, JeiPlugin Inyección no intrusiva, anclaje a contenedores, áreas de exclusión JEI

Instalación

Requisitos:

  • Runtime: Minecraft Forge 1.12.2 (14.23.5.2847+, Java 8) o CleanroomMC (Java 25)
  • Target de compilación para mods consumidores: sourceCompatibility = 1.8, targetCompatibility = 1.8

Agrega la dependencia desde GitHub Releases o JitPack en build.gradle:

repositories {
    maven { url "https://jitpack.io" }
}

dependencies {
    deobfCompile "com.github.x4yi:X4UI:r1.0b6"
}

Inicio Rápido

package com.example.mymod.client.gui;

import com.x4yi.x4ui.client.gui.base.GuiBaseScreen;
import com.x4yi.x4ui.client.gui.component.GuiButton;
import com.x4yi.x4ui.client.gui.component.GuiLabel;
import com.x4yi.x4ui.client.gui.component.GuiPanel;
import net.minecraft.client.gui.GuiScreen;

public class ExampleScreen extends GuiBaseScreen {

    public ExampleScreen(GuiScreen parent) {
        super(parent, "Ejemplo");
    }

    @Override
    protected void initComponents() {
        GuiPanel window = createCenteredWindow(360, 220);

        GuiPanel header = GuiPanel.row(8);
        header.addChild(new GuiLabel(0, 0, "Panel de Control", 0xFFFFFFFF));
        header.addChild(GuiPanel.spacer());
        header.addChild(new GuiButton(0, 0, 20, 20, "X", this::closeScreen));

        GuiPanel body = GuiPanel.card(10, 6);
        body.addChild(new GuiButton(0, 0, 0, 22, "Ejecutar Acción", () -> {
            sendActionOrLocal("mymod:ping", null, () -> {});
        }).withPercentWidth(1.0f).withVariant(GuiButton.Variant.PRIMARY));

        window.addChild(header);
        window.addChild(body);
        rootPanel.addChild(window);
    }
}

Documentación

Nota: Únicamente la documentación de X4UI fue redactada con IA (Gemini), siendo revisada y aprobada mediante pruebas humanas (X4yi).

Documento Alcance
00 - Primeros Pasos Requisitos, instalación, mapa de paquetes, GuiBaseScreen, GuiBaseContainer, API fluida
01 - Conceptos Fundamentales Paradigma retenido, árbol de componentes, ciclo de vida, State<T>, UIStateBus, temas
02 - Recursos Remotos MediaPipeline, descubrimiento OS de ffmpeg, fallback JCodec, SecurityUtils, formatos
03 - Red y Sincronización Sidedness, UINetwork, ScreenRegistry, PacketGuiRpc, UIChannels, ActionGuard, Container
04 - Diseño Responsivo ScaledResolution, estándar GUI Scale 1x–4x, FlexLayout, FlexAlign, GuiScrollPanel
05 - Gráficos y Renderizado Abstracción IGraphics, pila de estados, scissor, primitivas, profundidad y texturas BGRA
06 - Tipografía y Fuentes IFont, TrueTypeFont, VanillaFont, FontRegistry, recarga F3+T, disciplina VRAM
07 - Overlays e Inyección IGuiOverlay, GuiOverlayManager, OverlayDockManager, ContainerAnchor
08 - Integraciones y Buenas Prácticas Integración JEI, convenciones de nombres, vistas desacopladas, memoria y antipatrones
09 - Compatibilidad Forge y CleanroomMC Portabilidad Java 8 ↔ Java 25, PlatformBridge, KeyCodes, UIInput, reglas reobfJar
Botones y Entradas GuiButton, GuiTextInput, GuiToggle, GuiSliderInt / Float / Double
Contenedores y Paneles GuiPanel, GuiCard, GuiScrollPanel, GuiSlot
Multimedia GuiImage (URL, ResourceLocation, 9-slice), GuiVideo (errores/carga), GuiAudio, GuiSprite
Componentes Avanzados GuiVirtualList, GuiDropdown, GuiMarkdown, GuiModelRender, GuiTooltip

Licencia

X4UI está licenciado bajo GNU General Public License v3 (GPL-3.0).

Project description from CurseForge.

Pick your setup

x4ui by Minecraft version and loader

Choose the version and loader you play, then open the matching release.

1 available setups

Check the dependencies, then try the file in a copied instance before changing a world you care about.

Recent files

x4ui versions and loaders

6 of 6 releases match

Looking for an older file? The official CurseForge project page is in Resources.