HtmlCraft API

HtmlCraft API

Движок рендеринга HTML/CSS GUI для Minecraft 1.20.1 Forge

Введение

HtmlCraft API — это лёгкий движок рендеринга HTML/CSS, который привносит технологии веб-фронтенда в разработку GUI для Minecraft. Вместо изучения сложного Minecraft GUI API (GuiGraphics, Widget, AbstractContainerScreen и т.д.) разработчики могут создавать красивые игровые интерфейсы, просто написав HTML + CSS.

Возможности

Возможность	Описание
Парсинг HTML	Распространённые HTML-теги, атрибуты, вложенные структуры, HTML-сущности (именованные/десятичные/шестнадцатеричные)
Стилизация CSS	Селекторы классов, селекторы ID, селекторы тегов, инлайн-стили
Движок компоновки	Блочная компоновка, Flexbox, CSS Grid
Визуальные эффекты	Линейные градиенты, скругление углов, имитация теней, прозрачность
Взаимодействие	События клика по кнопкам, прокрутка колёсиком мыши, проверка попадания
Шаблонизатор	Подстановка {{переменная}}, контекст привязки данных
Потокобезопасность	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

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!");

Minecraft.getInstance().setScreen(screen);

### 2. Наследование HtmlScreen для кастомных экранов
```java
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

Единая точка входа, предоставляющая паттерн Builder для создания HTML-экранов.

HtmlRendererAPI.Builder

Цепочный builder для настройки HTML, CSS, данных и событий.

HtmlScreen

Абстрактный базовый класс экрана HTML-рендеринга, наследует Minecraft Screen.

HtmlScreen.ClickEvent

Событие клика, содержащее кликнутый элемент и координаты.

DataContext

Контекст переменных шаблона, потокобезопасный.

HtmlElement

Узел DOM-элемента.

Поддерживаемые свойства CSS

Компоновка

Блочная модель

Визуальные эффекты

Текст

Позиционирование и переполнение

Шаблонизатор

Используйте плейсхолдеры {{variable}} в HTML. Они заменяются методом TemplateEngine.render() значениями из DataContext во время 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>";

Специальные символы автоматически экранируются в HTML-сущности для предотвращения инъекций.

Конвейер рендеринга

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)

Структура пакетов

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

События клика

Кликабельные элементы включают:

• Теги `
• Теги ``
• Любой элемент с атрибутом id Клики вызывают колбэк ClickEvent. Используйте event.element().getId(), чтобы определить, по какому элементу кликнули.

Поддержка прокрутки

Элементы с overflow-y: scroll или overflow-y: auto автоматически реагируют на прокрутку колёсиком мыши. Каждый шаг прокрутки сдвигает на 20 пикселей.

Лицензия

LGPL-2.1

Автор

Yifei