CurseForge · Minecraft mod
x4ui
Is a UI framework for my mods.
Quick answer
Which x4ui release should I use?
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.
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.
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.
- 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.
- 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.
- 03
Put it on the correct side
The project page does not say whether this file belongs on the client, dedicated server, or both.
- 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
GuiComponentnodes rooted inrootPanel. 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 incom.x4yi.x4ui.api.*, while OpenGL, TrueType rasterization, and FFmpeg/JCodec backends reside incom.x4yi.x4ui.impl.*. - Dual-Runtime Abstraction (
PlatformBridge): Packaged as a Multi-Release JAR (Java 8base +META-INF/versions/21/) soCleaner, I/O executors,KeyCodes,UIInput, andIGraphicsrun transparently on both Forge 1.12.2 (Java 8) and CleanroomMC (Java 25). - Reactive State with Lifecycle Cleanup:
State<T>andUIStateBus(Scope.SCREEN,Scope.SESSION,Scope.GLOBAL) decouple views from data sources;component.bindState(...)unsubscribes automatically ondestroy(). - Server-Optional Networking:
UINetworkprovides remote screen opening (ScreenRegistry), batched state sync (PacketStateBatch), request–response RPC (PacketGuiRpc), and multi-player channels (UIChannels) protected byActionGuardand 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
GuiComponentbajorootPanel. 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 encom.x4yi.x4ui.api.*, mientras que OpenGL, rasterización TrueType y backends FFmpeg/JCodec se aíslan encom.x4yi.x4ui.impl.*. - Abstracción Dual de Runtime (
PlatformBridge): Empaquetado como Multi-Release JAR (Java 8base +META-INF/versions/21/) para queCleaner, executors de I/O,KeyCodes,UIInputeIGraphicsoperen de forma transparente en Forge 1.12.2 (Java 8) y CleanroomMC (Java 25). - Estado Reactivo Ligado al Ciclo de Vida:
State<T>yUIStateBus(Scope.SCREEN,Scope.SESSION,Scope.GLOBAL) desacoplan la vista de los datos;component.bindState(...)desuscribe los listeners automáticamente al ejecutardestroy(). - Red Server-Optional:
UINetworkofrece apertura remota de pantallas (ScreenRegistry), lotes de estado (PacketStateBatch), RPC request–response (PacketGuiRpc) y canales multi-jugador (UIChannels) protegidos conActionGuardy 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.
Check the dependencies, then try the file in a copied instance before changing a world you care about.
Recent files
x4ui versions and loaders
x4ui-r1.0b6.jar
16 Nov 2026
x4ui-r1.0b4.jar
4 Sept 2026
x4ui-r1.0b3a.jar
2 Sept 2026
x4ui-r1.0b3.jar
26 Aug 2026
x4ui-r1.0b2.jar
22 Aug 2026
x4ui-r1.0b1.jar
17 Aug 2026
Looking for an older file? The official CurseForge project page is in Resources.