HtmlCraft API
一个HTML/CSS渲染引擎，为Minecraft GUI提供基于Web的界面构建能力。
HtmlCraft API
适用于 Minecraft 1.20.1 Forge / Fabric 及 26.2 Fabric 的 HTML/CSS GUI 渲染引擎
介绍
HtmlCraft API 是一个轻量级 HTML/CSS 渲染引擎，将 Web 前端技术引入 Minecraft GUI 开发。开发者无需学习复杂的 Minecraft GUI API（GuiGraphics、Widget、AbstractContainerScreen 等），只需编写 HTML + CSS 即可构建精美的游戏界面。
功能特性
| 功能 | 描述 |
|---|---|
| HTML 解析 | 常用 HTML 标签、属性、嵌套结构、HTML 实体（命名/十进制/十六进制） |
| CSS 样式 | 类选择器、ID 选择器、标签选择器、内联样式 |
| 布局引擎 | 块级布局、Flexbox、CSS Grid |
| 视觉效果 | 线性渐变、圆角、阴影模拟、透明度 |
| 交互 | 按钮点击事件、鼠标滚轮滚动、命中测试 |
| 模板引擎 | {{变量}} 替换、数据绑定上下文 |
| 线程安全 | ConcurrentHashMap、CopyOnWriteArrayList |
环境要求
本 API 提供三个版本，请选择与你的加载器和 Minecraft 版本匹配的 jar 文件。
Forge 版本 (1.20.1)
| 依赖 | 版本 |
|---|---|
| Minecraft | 1.20.1 |
| Forge | 47.x |
| Java | 17 |
Fabric 版本 (1.20.1)
| 依赖 | 版本 |
|---|---|
| Minecraft | 1.20.1 |
| Fabric Loader | >=0.19.3 |
| Fabric API | 0.92.11+1.20.1 |
| Java | 17 |
Fabric 版本 (26.2)
| 依赖 | 版本 |
|---|---|
| Minecraft | 26.2 |
| Fabric Loader | >=0.19.3 |
| Fabric API | 0.156.0+26.2 |
| Java | 25 |
安装
作为模组依赖
- Forge 1.20.1：将
htmlcraftapi-1.0.0-1.20.1forge.jar放入mods文件夹 - Fabric 1.20.1：将
htmlcraftapi-1.0.0-1.20.1fabric.jar放入mods文件夹 - Fabric 26.2：将
htmlcraftapi-1.0.0-26.2fabric.jar放入mods文件夹
作为开发依赖
Forge 版本（Mojang 映射）：
dependencies {
implementation files('libs/htmlcraftapi-1.0.0-1.20.1forge.jar')
}
Fabric 版本（Yarn 映射，使用 Loom 复合构建）：
dependencies {
modImplementation 'com.htmlcraft.api:htmlcraftapi:1.0.0-1.20.1fabric'
}
对于 Fabric，推荐使用 includeBuild 引入源码项目以便调试：
// settings.gradle (1.20.1)
includeBuild '../HtmlCraftAPI/fabric'
// settings.gradle (26.2)
includeBuild '../HtmlCraftAPI/fabric/26.2'
快速开始
以下示例使用 Forge（Mojang 映射）API。Fabric 1.20.1 版本仅在类名上有所不同（例如
Component→Text、Minecraft→MinecraftClient、GuiGraphics→DrawContext）。Fabric 26.2 版本重构了内部渲染层（GuiGraphics→GuiGraphicsExtractor），但公开的 HTML/CSS API 完全相同。
1. 通过 Builder 创建界面
import com.htmlcraft.api.HtmlRendererAPI;
import com.htmlcraft.api.binding.DataContext;
import com.htmlcraft.api.screen.HtmlScreen;
import net.minecraft.network.chat.Component;
DataContext data = new DataContext();
data.set("title", "My Interface");
data.set("content", "Hello, Minecraft!");
HtmlScreen screen = HtmlRendererAPI.createScreen(Component.literal("My Screen"))
.html("<div class='container'>" +
" <h1>{{title}}</h1>" +
" <p>{{content}}</p>" +
" <button id='btn-ok'>OK</button>" +
"</div>")
.css(".container { padding: 20px; background: #1a1a2e; border-radius: 10px; }" +
"h1 { color: #e94560; font-size: 16px; }" +
"p { color: #ffffff; }" +
"#btn-ok { background: #0f3460; color: #ffffff; border-radius: 6px; padding: 8px; }")
.data(data)
.onClick(event -> {
if ("btn-ok".equals(event.element().getId())) {
System.out.println("Player clicked the OK button");
}
})
.build();
Minecraft.getInstance().setScreen(screen);
2. 继承 HtmlScreen 实现自定义界面
public class MyScreen extends HtmlScreen {
public MyScreen() {
super(Component.literal("My Screen"));
}
@Override
protected String getHtml() {
return "<div class='root'>Custom content</div>";
}
@Override
protected String getCss() {
return ".root { padding: 16px; background: #2d2d44; }";
}
}
3. Forge / Fabric 映射对照
| Forge (Mojang) | Fabric (Yarn) | 描述 |
|---|---|---|
net.minecraft.network.chat.Component |
net.minecraft.text.Text |
文本组件 |
net.minecraft.client.Minecraft |
net.minecraft.client.MinecraftClient |
客户端实例 |
net.minecraft.client.gui.GuiGraphics |
net.minecraft.client.gui.DrawContext |
绘制上下文 |
net.minecraft.world.level.saveddata.SavedData |
net.minecraft.world.PersistentState |
存档持久化 |
net.minecraft.network.FriendlyByteBuf |
net.minecraft.network.PacketByteBuf |
网络缓冲区 |
net.minecraftforge.network.SimpleChannel |
ServerPlayNetworking / ClientPlayNetworking |
网络通道 |
核心 API
HtmlRendererAPI
统一入口，提供 Builder 模式来创建 HTML 界面。
| 方法 | 描述 |
|---|---|
createScreen(Component title) |
创建界面 Builder |
HtmlRendererAPI.Builder
用于配置 HTML、CSS、数据和事件的链式 Builder。
| 方法 | 描述 |
|---|---|
html(String html) |
设置 HTML 内容 |
css(String css) |
设置 CSS 样式表 |
data(DataContext context) |
设置模板数据上下文 |
onClick(Consumer<ClickEvent> handler) |
设置点击事件回调 |
build() |
构建 HtmlScreen 实例 |
HtmlScreen
抽象 HTML 渲染界面基类，继承 Minecraft 的 Screen。
| 方法 | 描述 |
|---|---|
getHtml() |
抽象方法，子类提供 HTML 内容 |
getCss() |
重写以提供 CSS 样式 |
setClickHandler(Consumer<ClickEvent>) |
设置点击事件处理器 |
setPreferredSize(int w, int h) |
设置内容区域大小（居中布局） |
rebuild() |
重建渲染管线（数据变更后刷新） |
getRootLayout() |
获取布局根节点 |
getPipeline() |
获取渲染管线 |
HtmlScreen.ClickEvent
包含被点击元素和坐标的点击事件。
| 方法 | 描述 |
|---|---|
element() |
被点击的 DOM 元素 |
button() |
鼠标按钮（0=左键、1=右键、2=中键） |
x() / y() |
点击坐标 |
DataContext
模板变量上下文，线程安全。
| 方法 | 描述 |
|---|---|
set(String key, Object value) |
设置变量 |
get(String key) |
获取变量 |
getString(String key) |
获取字符串值 |
has(String key) |
检查变量是否存在 |
clear() |
清除所有变量 |
HtmlElement
DOM 元素节点。
| 方法 | 描述 |
|---|---|
tagName() |
获取标签名 |
getId() |
获取 id 属性 |
hasClass(String) |
检查是否含有指定类 |
getAttribute(String) |
获取属性值 |
children() |
获取子节点 |
支持的 CSS 属性
布局
| 属性 | 值 |
|---|---|
display |
block / flex / inline / grid / none |
flex-direction |
row / column |
justify-content |
flex-start / center / flex-end / space-between / space-around |
align-items |
flex-start / center / flex-end / stretch |
gap |
像素值 |
grid-template-columns |
repeat(N, 1fr) |
盒模型
| 属性 | 描述 |
|---|---|
width / height |
像素值、auto |
padding |
像素值 |
margin |
像素值 |
border-width |
像素值 |
视觉效果
| 属性 | 值 |
|---|---|
background |
#RRGGBB / #AARRGGBB / #RRGGBBAA |
background（渐变） |
linear-gradient(to bottom, #color1, #color2) |
color |
文本颜色 |
border-color |
边框颜色 |
border-radius |
圆角像素值 |
box-shadow |
offsetX offsetY blur spread #color |
opacity |
0.0 - 1.0 |
文本
| 属性 | 值 |
|---|---|
font-size |
像素值 |
text-align |
left / center / right |
定位与溢出
| 属性 | 值 |
|---|---|
position |
static / relative / absolute / fixed |
overflow-x / overflow-y |
visible / hidden / scroll / auto |
z-index |
整数 |
模板引擎
在 HTML 中使用 {{变量}} 占位符。在 init() 过程中，TemplateEngine.render() 会用 DataContext 中的值替换这些占位符。
DataContext data = new DataContext();
data.set("player_name", "Steve");
data.set("level", 30);
// HTML 模板
String html = "<div>Player: {{player_name}} | Level: {{level}}</div>";
特殊字符会自动转义为 HTML 实体以防止注入。
渲染管线
HTML 字符串
↓
HtmlParser（解析为 DOM 树）
↓
StyleSheet + CssParser（加载 CSS 规则）
↓
StyleCalculator（计算每个元素的最终样式）
↓
LayoutEngine（执行布局，生成 LayoutNode 树）
↓
RenderPipeline（生成并执行渲染命令）
↓
GuiGraphics（绘制到 Minecraft 屏幕）
包结构
com.htmlcraft.api
├── HtmlCraftAPI.java // 模组主类
├── HtmlRendererAPI.java // 公开入口 + Builder
├── core/
│ ├── HtmlDocument.java // HTML 文档
│ ├── HtmlElement.java // DOM 元素节点
│ ├── HtmlNode.java // DOM 节点接口
│ └── HtmlText.java // DOM 文本节点
├── parser/
│ ├── HtmlParser.java // HTML 解析器
│ └── CssParser.java // CSS 解析器
├── style/
│ ├── StyleSheet.java // CSS 样式表
│ ├── StyleCalculator.java // 样式计算器
│ └── ComputedStyle.java // 计算后样式
├── layout/
│ ├── LayoutEngine.java // 布局引擎
│ └── LayoutNode.java // 布局节点
├── render/
│ ├── RenderPipeline.java // 渲染管线
│ ├── RenderContext.java // 渲染上下文
│ ├── RenderCommand.java // 渲染命令接口
│ └── commands/ // 具体渲染命令
│ ├── FillRectCommand.java
│ ├── DrawTextCommand.java
│ ├── DrawBorderCommand.java
│ └── BlitTextureCommand.java
├── binding/
│ ├── DataContext.java // 数据绑定上下文
│ └── TemplateEngine.java // 模板引擎
└── screen/
└── HtmlScreen.java // HTML 渲染界面基类
点击事件
可点击的元素包括：
<button>标签<a>标签- 任何带有
id属性的元素
点击会触发 ClickEvent 回调。使用 event.element().getId() 来识别被点击的元素。
滚动支持
带有 overflow-y: scroll 或 overflow-y: auto 的元素会自动响应鼠标滚轮滚动。每次滚动步进 20 像素。
许可证
LGPL-2.1
作者
Yifei
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表，这里同步展示。