TesseraUI

TesseraUI

TesseraUI是一个轻量级的HTML/CSS UI框架，专为NeoForge设计，让模组开发者能够使用运行时解析的HTML模板、CSS样式、flexbox/grid布局、数据绑定、动画、国际化、拖放、物品槽、虚拟列表来构建Minecraft界面。

基础库

TesseraUI预览查看大图

Wabbanode 合作伙伴

TesseraUI

TesseraUI 是一个面向 NeoForge 的轻量级 UI 框架，允许模组开发者使用 HTML 模板、CSS 样式以及原生 Minecraft 渲染来构建游戏界面。

它专为那些希望获得更丰富的客户端界面，而又不想为每个界面手动构建布局、样式、交互和渲染逻辑的开发者而设计。使用类似 HTML 的模板和 CSS 文件定义 UI，将其绑定到 Java 数据和回调函数，然后让 TesseraUI 将其渲染为真实的 Minecraft GUI 控件。

TesseraUI 不嵌入浏览器，也不运行 JavaScript。模板和样式会在运行时解析并转换为在 Minecraft 客户端内运行的原生 UI 组件。

为什么使用 TesseraUI？

Minecraft GUI 开发很快就会变得重复繁琐：定位元素、处理悬停状态、调整布局尺寸、连接按钮、翻译文本、渲染物品槽位，以及让大型动态列表保持响应，这些都需要耗费时间。

TesseraUI 为您提供了一个受 Web 开发启发、但仍在 Minecraft 渲染栈内部的结构化 UI 层。您可以更快地构建界面，将展示层与 Java 逻辑分离，并在您的模组中复用 UI 模式。

它适用于：

  • 配置菜单
  • 指南书和文档界面
  • 仪表板和后台管理面板
  • 背包式界面
  • 物品选择界面
  • 设置页面
  • 模组管理工具
  • 动态列表和数据密集型 UI
  • 自定义游戏内编辑器或调试界面

主要特性

  • 适用于 Minecraft GUI 界面的 HTML 模板渲染
  • 支持 flexbox 和 grid 布局的 CSS 样式
  • CSS 变量和媒体查询
  • 悬停过渡和关键帧动画
  • 通过 {{ }}、v-for 和 v-if 进行数据绑定
  • 组件模板和插槽
  • 通过 data-i18n 和翻译绑定提供的本地化辅助
  • 拖放支持
  • 物品槽位和物品栏选择器支持
  • 适用于大型数据集的虚拟列表
  • 标签页和交互式 UI 组件
  • 支持热重载以加快 UI 开发
  • 面向代码优先界面的完整程序化 Java API

HTML 和 CSS 模板

在你的模组资源中创建 UI 文件并从 Java 中加载它们：

<col>
  <h2 data-i18n="ui.example.title">设置</h2>
  <p>你好，{{ player.name }}！</p>

  <row>
    <button onclick="save">保存</button>
    <button onclick="cancel">取消</button>
  </row>
</col>

col {
  background: #1A1208;
  padding: 12px;
  gap: 8px;
}

button {
  background: #5C3A1E;
  color: #F0B27A;
  width: 80px;
  height: 16px;
  transition: background 200ms ease-out;
}

button:hover {
  background: #7C5A2E;
}

这使得美术、设计和开发人员能够迭代布局和样式，而无需将每个视觉决策都埋在 Java 代码中。

包含 Java API

如果你更喜欢直接用代码构建界面，TesseraUI 也提供了一个完整的 Java API。你可以使用与模板相同的布局和渲染系统，以编程方式创建面板、标签、按钮、列表、动画、物品槽位和交互组件。

你也可以混合使用两种方式：使用模板处理大部分 UI 结构，然后在需要的地方附加 Java 回调、动态模型和自定义组件。

为模组开发而构建

TesseraUI 专注于 Minecraft 模组 UI 的实际需求：

  • 客户端界面渲染
  • 支持物品的控件
  • 物品栏选择器支持
  • 支持本地化的文本
  • 可复用组件
  • 适应不同 GUI 缩放的响应式布局
  • 开发期间热重载
  • 无 Web 运行时依赖

目标是让复杂的模组界面更容易构建、维护和随时间重新设计样式。

游戏内示例界面

TesseraUI 包含多个开发/演示界面，可在游戏中打开以查看框架的实际运行效果。它们对于测试功能、截取屏幕截图以及理解 HTML/CSS 模板如何映射到 Minecraft UI 控件非常有用。

推荐的演示界面：

  • /tessera test-v18 — 工具提示、响应式状态和 Toast 通知
  • /tessera test-v19 — 标签页、模态对话框、表单、滑块和键盘焦点
  • /tessera test-v20 — 虚拟列表和 CSS 过渡
  • /tessera test-v21 — 可复用组件、上下文菜单和调试叠加工具
  • /tessera test-v22 — 拖放、物品槽位和物品格
  • /tessera test-v23 — CSS 过渡和关键帧动画

这些界面是作为模组开发者的实用示例，而非游戏内容。它们展示了 TesseraUI 如何用于构建真实的模组菜单、配置面板、背包式界面、仪表板和动态客户端界面。

运行环境要求

  • Minecraft 1.21.1
  • NeoForge 21.1.x
  • Java 21

文档

文档可在 GitHub Wiki 上获取：

https://github.com/Blushister/TesseraUI/wiki

Wiki 包含入门指南、支持的 HTML 标签、CSS 参考、数据绑定、布局行为、本地化、拖放、物品槽位、热重载以及程序化 API。

许可证

TesseraUI 使用 LGPL-3.0 许可证。