HtmlCraft API

HTML/CSS GUI Rendering Engine for Minecraft 1.20.1 Forge / Fabric and 26.2 Fabric

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

Requirements

This API ships in three versions. Pick the jar matching your loader and Minecraft version.

Forge Version (1.20.1)

Fabric Version (1.20.1)

Fabric Version (26.2)

Installation

As a Mod Dependency

• Forge 1.20.1: place htmlcraftapi-1.0.0-1.20.1forge.jar into the mods folder
• Fabric 1.20.1: place htmlcraftapi-1.0.0-1.20.1fabric.jar into the mods folder
• Fabric 26.2: place htmlcraftapi-1.0.0-26.2fabric.jar into the mods folder

As a Development Dependency

Forge version (Mojang mappings):

dependencies {
    implementation files('libs/htmlcraftapi-1.0.0-1.20.1forge.jar')
}

Fabric version (Yarn mappings, with Loom composite build):

dependencies {
    modImplementation 'com.htmlcraft.api:htmlcraftapi:1.0.0-1.20.1fabric'
}

For Fabric, includeBuild is recommended to bring in the source project for debugging:

// settings.gradle (1.20.1)
includeBuild '../HtmlCraftAPI/fabric'

// settings.gradle (26.2)
includeBuild '../HtmlCraftAPI/fabric/26.2'

Quick Start

Examples below use Forge (Mojang mappings) API. The Fabric 1.20.1 version only differs in class names (e.g. Component → Text, Minecraft → MinecraftClient, GuiGraphics → DrawContext). The Fabric 26.2 version refactors the internal render layer (GuiGraphics → GuiGraphicsExtractor), but the public HTML/CSS API is identical.

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; }";
    }
}

3. Forge / Fabric Mapping Reference

Core API

HtmlRendererAPI

Unified entry point providing a Builder pattern for creating HTML Screens.

HtmlRendererAPI.Builder

Chained builder for configuring HTML, CSS, data, and events.

HtmlScreen

Abstract HTML rendering screen base class, extends Minecraft Screen.

HtmlScreen.ClickEvent

Click event containing the clicked element and coordinates.

DataContext

Template variable context, thread-safe.

HtmlElement

DOM element node.

Supported CSS Properties

Layout

Box Model

Visual Effects

Text

Position & Overflow

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