x4ui

x4ui

这是我的模组的UI框架。

X4UI 框架

一个为 Minecraft Forge 1.12.2 打造的现代化、高性能、面向对象的 GUI 框架。

English • Español

🇬🇧 English

关于 X4UI

厌倦了处理硬编码坐标、混乱的 drawScreen 重写，以及古老的原版 Minecraft 1.12.2 GUI 系统中无穷无尽的 Bug 了吗？

X4UI 是一个从 Hammers Unbound 中提取出来的独立、灵活且动态的用户界面框架。它将现代网页式开发范式（如 FlexBox 布局、DOM 树结构和事件冒泡）直接带入了 Forge 1.12.2。

我什么时候应该使用 X4UI？

如果你正在构建以下内容，你应该使用 X4UI：

  • 交互式指南或手册： 需要渲染格式化文本？X4UI 包含一个原生的 GuiMarkdown 解析器，可自动将 Markdown 文本转换为美观、结构化的 UI 元素（标题、块引用、项目符号和图像）。
  • RPG 技能树与复杂菜单： 嵌套面板、按钮、开关和滑块均会自动处理。
  • 动态物品栏 / 自定义锻造台： GuiScrollPanel 提供了开箱即用的 OpenGL 裁剪（GL_SCISSOR_TEST），使您能够创建平滑、可滚动的物品列表，且物品不会渲染到边界框之外。

主要特点

  • DOM 架构： 通过嵌套组件（rootPanel.addChild(new GuiButton(...))）来构建您的 UI。
  • FlexBox 布局： GuiPanel 支持具有间距和边距的自动 VERTICAL 和 HORIZONTAL 堆叠。不再需要手动计算 UI 位置！
  • 高性能（脏标记系统）： 仅在组件实际发生变化时才重新计算布局，从而节省大量 CPU 资源，即使在拥有数百个元素的界面中也能防止 FPS 下降。
  • 事件冒泡： 点击和滚动事件精确地遵循 Z 轴顺序。点击一个重叠的按钮将触发最顶层的按钮并停止向下传播。
  • 微动画： 内置 lerp 逻辑，实现极其顺滑的悬停和点击过渡效果。

安装（面向开发者）

将以下内容添加到您的 build.gradle 中：

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

dependencies {
    // 将 r1.0b1 替换为最新的发布标签
    compile 'com.github.X4yi:X4UI:r1.0b1'
}

快速开始

要使用 X4UI，只需继承 GuiBaseScreen 而不是原版的 GuiScreen：

public class MyCustomScreen extends GuiBaseScreen {
    
    public MyCustomScreen() {
        super(null, "My Title");
    }

    @Override
    protected void initComponents() {
        // rootPanel 由 GuiBaseScreen 自动创建
        rootPanel.setFlexDirection(FlexDirection.VERTICAL);
        rootPanel.setGap(5);
        
        GuiLabel titleLabel = new GuiLabel(0, 0, "Welcome to X4UI!");
        GuiButton closeButton = new GuiButton(0, 0, 100, 20, "Close", () -> this.closeScreen());
        
        rootPanel.addChild(titleLabel);
        rootPanel.addChild(closeButton);
    }
}

🇪🇸 Español

Sobre X4UI

¿Cansado de lidiar con coordenadas estáticas (hardcodeadas), sobreescrituras desordenadas de drawScreen e infinitos bugs en el arcaico sistema de interfaces de Vanilla Minecraft 1.12.2?

X4UI es un framework de interfaces de usuario dinámico, flexible e independiente, extraído del mod Hammers Unbound. Trae consigo los paradigmas de desarrollo web modernos (como diseños FlexBox, estructuras en árbol DOM y propagación de eventos) directamente a Forge 1.12.2.

¿Cuándo debería usar X4UI?

Deberías considerar usar X4UI si estás creando:

  • Guías o Manuales Interactivos: ¿Necesitas renderizar texto con formato? X4UI incluye un analizador nativo GuiMarkdown que convierte automáticamente texto en elementos de UI estructurados y hermosos (Encabezados, citas, viñetas e imágenes).
  • Árboles de Habilidades RPG y Menús Complejos: Los paneles anidados, botones, interruptores y deslizadores (sliders) se manejan automáticamente.
  • Inventarios Dinámicos / Forjas Customizadas: GuiScrollPanel proporciona recorte OpenGL nativo (GL_SCISSOR_TEST), permitiéndote crear listas de ingredientes desplazables y suaves sin que los ítems se rendericen fuera de la caja.

Características Principales

  • Arquitectura DOM: Construye tu interfaz anidando componentes (rootPanel.addChild(new GuiButton(...))).
  • Diseños FlexBox: GuiPanel soporta apilamiento automático VERTICAL y HORIZONTAL con márgenes y separaciones. ¡Se acabó calcular matemáticas manuales para posicionar interfaces!
  • Alto Rendimiento (Dirty Flag System): Los diseños sólo se recalcularán matemáticamente cuando un componente cambia físicamente. Esto ahorra inmensas cantidades de procesamiento y previene caídas de FPS, incluso en menús con cientos de elementos.
  • Propagación de Eventos: Los clics y el desplazamiento (scroll) respetan con precisión el índice Z. Hacer clic en un botón superpuesto activará el que esté por encima y detendrá la propagación a los de abajo.
  • Micro-Animaciones: Lógica de interpolación (lerp) integrada para transiciones de "hover" (pasar el ratón por encima) y clics extremadamente fluidas.

Instalación (Para Desarrolladores)

Añade lo siguiente a tu build.gradle:

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

dependencies {
    // Reemplaza r1.0b1 con la versión más reciente
    compile 'com.github.X4yi:X4UI:r1.0b1'
}

Inicio Rápido

Para usar X4UI, simplemente extiende GuiBaseScreen en lugar del clásico GuiScreen de Vanilla:

public class MyCustomScreen extends GuiBaseScreen {
    
    public MyCustomScreen() {
        super(null, "Mi Título");
    }

    @Override
    protected void initComponents() {
        // rootPanel es creado automáticamente por GuiBaseScreen
        rootPanel.setFlexDirection(FlexDirection.VERTICAL);
        rootPanel.setGap(5);
        
        GuiLabel titleLabel = new GuiLabel(0, 0, "¡Bienvenido a X4UI!");
        GuiButton closeButton = new GuiButton(0, 0, 100, 20, "Cerrar", () -> this.closeScreen());
        
        rootPanel.addChild(titleLabel);
        rootPanel.addChild(closeButton);
    }
}

X4UI 是开源项目，并根据 GNU 通用公共许可证 v3 (GPL-3.0) 提供。