Vellum：在 Minecraft 里用 HTML 渲染模组 GUI 的 Web 引擎

CurseForge | Modrinth | 文档

Vellum 是 Minecraft 内部的一个小型 Web 引擎。用 HTML 编写你的界面、物品栏、HUD 等，Vellum 会使用常规的 GUI 渲染器处理布局、脚本和渲染。它支持 Minecraft 26.3、26.2 和 1.21.1，运行于 NeoForge 和 Fabric。

你大概不需要单独安装它；Vellum 是其他模组依赖的库。

Vellum 的灵感来自三个方面：

我是一名 Web 开发者，而我的 Minecraft GUI 一直很难看
LLM 在 Web 开发方面比在 Minecraft GUI 开发方面更擅长
跨 Minecraft 版本更新 GUI 一直很痛苦。有了 Vellum，你的 GUI 保持不变，只需更新库即可。

Vellum 在这两种情况下都有帮助。Opus 5.5 在 Vellum 的开发中被大量使用。

你能得到什么

大部分 CSS：支持 block、inline、flexbox 和 grid，过渡、选择器以及 @keyframes。它的目标是与完整浏览器相比达到 90-10 的解决方案。
元素默认使用原版精灵图。
对物品栏槽位使用 <slot index="0">，原版机制就会自动生效（Just Work™）：点击、拖拽、Shift 点击和提示框。
Minecraft 专属元素：<item>、<slot>、3D <entity> 和 <model>、精灵图、翻译和玩家头颅。
JavaScript 搭配 Vue 风格模板（v-for、v-if、v-model、@click）。
旁白/无障碍支持，以及一个带热重载的独立预览器，这样你（或你的智能体）无需启动游戏即可预览。
速度。几百个元素重新设置样式和重新布局只需远不到一毫秒。

<div class="mc-panel chest">
  <h2 class="mc-label">{{ title }}</h2>
  <div class="grid">
    <slot v-for="i in 27" :index="i - 1"></slot>
  </div>
  <button @click="vellum.send('sort')">Sort</button>
</div>
<style>
  .chest { width: 176px; margin: auto; }
  .grid { display: grid; grid-template-columns: repeat(9, 18px); }
  button { transition: transform .15s ease-out; }
  button:hover { transform: scale(1.05); }
</style>

面向模组开发者

Vellum 正在开发中。它位于 maven.maxleiter.com：

repositories { maven { url = "https://maven.maxleiter.com"; content { includeGroup("dev.vellum") } } }
dependencies { implementation("dev.vellum:vellum-neoforge-26.3:0.5.1") }   // or vellum-fabric-26.3, and the 1.21.1 ones

你可以随意将 Vellum 与你的模组打包在一起，或将其添加为依赖项。template/ 提供了小型的 NeoForge 和 Fabric 模组作为起点。文档涵盖 Java 侧，docs/SCRIPTING.md 涵盖 JavaScript 方言和模板，docs/MIGRATING.md 则介绍如何移植现有界面。

服务器

服务器模组可以在玩家的客户端上打开页面、向其推送数据并接收消息。由于服务器可能是恶意的，脚本运行在 Rhino 沙箱中，没有 Java 访问权限、没有网络访问权限、没有文件访问权限，并设有合理的上限。玩家始终可以用 Shift+Esc 关闭页面，config/vellum.properties 则让他们可以完全阻止服务器页面。

示例

完整页面，用 /vellum showcase <name> 在游戏内打开：

标题界面：带有视差风景的主菜单
转盘：以 3D 展示方块、物品和生物，由 CSS 旋转
生物图鉴：生物版的宝可梦图鉴，带有实时实体（Java 侧）
商人市场：带有背包和结账的商店
日志：一本任务书
HUD 套件：任务追踪器、指南针、Boss 血条和提示弹窗
控制台：一个机器人的聊天控制台

每个功能一个的小型演示，用 /vellum demo <name> 打开：设置、布局、动画、模板、地图、HUD 叠加层、聊天上方提示弹窗，以及一个由 <slot> 构建的原版箱子（服务器侧）。

/vellum open <resource id> 可打开任意页面，/vellum reload 可重新加载它们。在开发客户端中，保存 src/main/resources 下的页面会在已打开的界面中重新加载它。

预览器

你也可以不启动 Minecraft 就构建页面。预览器在 Swing 窗口中用引擎以及游戏的真实字体和精灵图（从你的 Minecraft jar 中读取）渲染页面，保存时重新加载，并有一个 F12 检查器，可勾勒出悬停元素的盒模型。

./gradlew :preview:run --args="path/to/page.html --scale 3 --size 427x240"
./gradlew :preview:run --args="page.html --snapshot out.png --frames 30"   # headless PNG

标志、按键以及它如何找到 jar 都在 preview/README.md 中。

构建

你需要 JDK 25 或更新版本以及 git；Gradle 会提供工具链（26.3 和 26.2 用 25，1.21.1 用 21）。

Vellum 使用打过补丁的 Rhino。构建过程会下载固定在 gradle.properties 中的上游源码（仅一次，并校验其 SHA-256），应用 rhino/patches 中的补丁并编译它，因此无需预先安装任何东西。 rhino/README.md 说明了这些补丁的作用以及如何修改它们。

./gradlew :engine:test                 # engine tests
./gradlew build                        # everything, every Minecraft version, including Fabric's headless GameTests
./gradlew :neoforge:26.3:runClient     # dev client (or :fabric:26.3, :neoforge:1.21.1, :fabric:1.21.1)
./gradlew :neoforge:26.3:runGameTestServer   # NeoForge's GameTests
./gradlew :preview:installDist         # previewer, at preview/build/install/preview/bin/preview

版本

Minecraft 26.3、26.2 和 1.21.1，支持 NeoForge 和 Fabric（Fabric 需要 Fabric API）。26.2 和 1.21.1 上有一些差异；docs/versions.md 列出了这些差异以及各版本是如何构建的。

使用 Vellum 的模组

TileFinder

许可证

Vellum 采用 MIT 许可证（LICENSE）。其 jar 包中捆绑了 Mozilla Rhino，后者采用 MPL-2.0：它由固定在 gradle.properties 中的上游提交（Rhino 1.9.1）构建，并应用了 rhino/patches 中的补丁，其许可证、声明以及关于该源码位置的说明随每个 jar 包一起发布在 META-INF/licenses/rhino/ 下。

Vellum 的开发过程中大量使用了 LLM。