HtmlCraft API
适用于 Minecraft 1.20.1 Forge 的 HTML/CSS GUI 渲染引擎
简介
HtmlCraft API 是一个轻量级的 HTML/CSS 渲染引擎,将 Web 前端技术引入 Minecraft GUI 开发中。开发者无需学习复杂的 Minecraft GUI API(如 GuiGraphics、Widget、AbstractContainerScreen 等),只需编写 HTML + CSS 即可构建精美的游戏界面。
特性
| 特性 |
描述 |
| HTML 解析 |
常用 HTML 标签、属性、嵌套结构、HTML 实体(命名/十进制/十六进制) |
| CSS 样式 |
类选择器、ID 选择器、标签选择器、内联样式 |
| 布局引擎 |
Block 布局、Flexbox、CSS Grid |
| 视觉效果 |
线性渐变、圆角、阴影模拟、透明度 |
| 交互 |
按钮点击事件、鼠标滚轮滚动、命中测试 |
| 模板引擎 |
{{variable}} 替换、数据绑定上下文 |
| 线程安全 |
ConcurrentHashMap、CopyOnWriteArrayList |
依赖要求
| 依赖项 |
版本 |
| Minecraft |
1.20.1 |
| Forge |
47.x |
| Java |
17 |
安装
作为模组依赖
将 htmlcraftapi-1.0.0-1.20.1forge.jar 放入 mods 文件夹。
作为开发依赖
添加到你的 build.gradle:
dependencies {
implementation files('libs/htmlcraftapi-1.0.0-1.20.1forge.jar')
}
快速入门
1. 通过 Builder 创建 Screen
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 以创建自定义 Screen
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; }";
}
}
核心 API
HtmlRendererAPI
提供用于创建 HTML Screen 的 Builder 模式的统一入口点。
| 方法 |
描述 |
createScreen(Component title) |
创建一个 Screen 构建器 |
HtmlRendererAPI.Builder
用于配置 HTML、CSS、数据和事件的链式构建器。
| 方法 |
描述 |
html(String html) |
设置 HTML 内容 |
css(String css) |
设置 CSS 样式表 |
data(DataContext context) |
设置模板数据上下文 |
onClick(Consumer<ClickEvent> handler) |
设置点击事件回调 |
build() |
构建 HtmlScreen 实例 |
HtmlScreen
抽象 HTML 渲染 Screen 基类,继承自 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 中使用 {{variable}} 占位符。它们在 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 String
↓
HtmlParser (解析为 DOM 树)
↓
StyleSheet + CssParser (加载 CSS 规则)
↓
StyleCalculator (计算每个元素的最终样式)
↓
LayoutEngine (执行布局,生成 LayoutNode 树)
↓
RenderPipeline (生成并执行渲染命令)
↓
GuiGraphics (绘制到 Minecraft 屏幕)
包结构
com.htmlcraft.api
├── HtmlCraftAPI.java // Mod 主类
├── 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
HtmlCraft API
HTML/CSS GUI Rendering Engine for Minecraft 1.20.1 Forge
Introduction
HtmlCraft API is a lightweight HTML/CSS rendering engine that brings web frontend technologies into Minecraft GUI development. Instead of learning the complex Minecraft GUI API (GuiGraphics, Widget, AbstractContainerScreen, etc.), developers can build beautiful game interfaces by simply writing HTML + CSS.
Features
| Feature |
Description |
| HTML Parsing |
Common HTML tags, attributes, nested structures, HTML entities (named/decimal/hex) |
| CSS Styling |
Class selectors, ID selectors, tag selectors, inline styles |
| Layout Engine |
Block layout, Flexbox, CSS Grid |
| Visual Effects |
Linear gradients, border radius, shadow simulation, opacity |
| Interaction |
Button click events, mouse wheel scrolling, hit testing |
| Template Engine |
{{variable}} replacement, data binding context |
| Thread Safety |
ConcurrentHashMap, CopyOnWriteArrayList |
Requirements
| Dependency |
Version |
| Minecraft |
1.20.1 |
| Forge |
47.x |
| Java |
17 |
Installation
As a Mod Dependency
Place htmlcraftapi-1.0.0-1.20.1forge.jar into the mods folder.
As a Development Dependency
Add to your build.gradle:
dependencies {
implementation files('libs/htmlcraftapi-1.0.0-1.20.1forge.jar')
}
Quick Start
1. Create a Screen via 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. Extend HtmlScreen for Custom Screens
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; }";
}
}
Core API
HtmlRendererAPI
Unified entry point providing a Builder pattern for creating HTML Screens.
| Method |
Description |
createScreen(Component title) |
Create a Screen builder |
HtmlRendererAPI.Builder
Chained builder for configuring HTML, CSS, data, and events.
| Method |
Description |
html(String html) |
Set HTML content |
css(String css) |
Set CSS stylesheet |
data(DataContext context) |
Set template data context |
onClick(Consumer<ClickEvent> handler) |
Set click event callback |
build() |
Build the HtmlScreen instance |
HtmlScreen
Abstract HTML rendering screen base class, extends Minecraft Screen.
| Method |
Description |
getHtml() |
Abstract method, subclass provides HTML content |
getCss() |
Override to provide CSS styles |
setClickHandler(Consumer<ClickEvent>) |
Set click event handler |
setPreferredSize(int w, int h) |
Set content area size (centered layout) |
rebuild() |
Rebuild render pipeline (refresh after data changes) |
getRootLayout() |
Get layout root node |
getPipeline() |
Get render pipeline |
HtmlScreen.ClickEvent
Click event containing the clicked element and coordinates.
| Method |
Description |
element() |
The clicked DOM element |
button() |
Mouse button (0=left, 1=right, 2=middle) |
x() / y() |
Click coordinates |
DataContext
Template variable context, thread-safe.
| Method |
Description |
set(String key, Object value) |
Set a variable |
get(String key) |
Get a variable |
getString(String key) |
Get string value |
has(String key) |
Check if variable exists |
clear() |
Clear all variables |
HtmlElement
DOM element node.
| Method |
Description |
tagName() |
Get tag name |
getId() |
Get id attribute |
hasClass(String) |
Check if has class |
getAttribute(String) |
Get attribute value |
children() |
Get child nodes |
Supported CSS Properties
Layout
| Property |
Values |
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 |
Pixel value |
grid-template-columns |
repeat(N, 1fr) |
Box Model
| Property |
Description |
width / height |
Pixel value, auto |
padding |
Pixel value |
margin |
Pixel value |
border-width |
Pixel value |
Visual Effects
| Property |
Values |
background |
#RRGGBB / #AARRGGBB / #RRGGBBAA |
background (gradient) |
linear-gradient(to bottom, #color1, #color2) |
color |
Text color |
border-color |
Border color |
border-radius |
Corner radius in pixels |
box-shadow |
offsetX offsetY blur spread #color |
opacity |
0.0 - 1.0 |
Text
| Property |
Values |
font-size |
Pixel value |
text-align |
left / center / right |
Position & Overflow
| Property |
Values |
position |
static / relative / absolute / fixed |
overflow-x / overflow-y |
visible / hidden / scroll / auto |
z-index |
Integer |
Template Engine
Use {{variable}} placeholders in HTML. They are replaced by TemplateEngine.render() with values from DataContext during init().
DataContext data = new DataContext();
data.set("player_name", "Steve");
data.set("level", 30);
// HTML template
String html = "<div>Player: {{player_name}} | Level: {{level}}</div>";
Special characters are automatically escaped to HTML entities to prevent injection.
Render Pipeline
HTML String
↓
HtmlParser (parse to DOM tree)
↓
StyleSheet + CssParser (load CSS rules)
↓
StyleCalculator (compute final styles per element)
↓
LayoutEngine (perform layout, generate LayoutNode tree)
↓
RenderPipeline (generate and execute render commands)
↓
GuiGraphics (draw to Minecraft screen)
Package Structure
com.htmlcraft.api
├── HtmlCraftAPI.java // Mod main class
├── HtmlRendererAPI.java // Public entry point + Builder
├── core/
│ ├── HtmlDocument.java // HTML document
│ ├── HtmlElement.java // DOM element node
│ ├── HtmlNode.java // DOM node interface
│ └── HtmlText.java // DOM text node
├── parser/
│ ├── HtmlParser.java // HTML parser
│ └── CssParser.java // CSS parser
├── style/
│ ├── StyleSheet.java // CSS stylesheet
│ ├── StyleCalculator.java // Style calculator
│ └── ComputedStyle.java // Computed style
├── layout/
│ ├── LayoutEngine.java // Layout engine
│ └── LayoutNode.java // Layout node
├── render/
│ ├── RenderPipeline.java // Render pipeline
│ ├── RenderContext.java // Render context
│ ├── RenderCommand.java // Render command interface
│ └── commands/ // Concrete render commands
│ ├── FillRectCommand.java
│ ├── DrawTextCommand.java
│ ├── DrawBorderCommand.java
│ └── BlitTextureCommand.java
├── binding/
│ ├── DataContext.java // Data binding context
│ └── TemplateEngine.java // Template engine
└── screen/
└── HtmlScreen.java // HTML rendering screen base class
Click Events
Clickable elements include:
<button> tags
<a> tags
- Any element with an
id attribute
Clicks trigger a ClickEvent callback. Use event.element().getId() to identify which element was clicked.
Scroll Support
Elements with overflow-y: scroll or overflow-y: auto automatically respond to mouse wheel scrolling. Each scroll step moves 20 pixels.
License
LGPL-2.1
Author
Yifei
评论 0
登录后参与评分
还没有评论,来抢沙发吧