Minecraft Horizon — независимый клиент Minecraft: Java Edition, написанный на Rust. У него есть собственная система модификаций. Если вы раньше делали моды на Forge, Fabric или NeoForge, важно сразу понять: обычные Java-моды (.jar) здесь нельзя просто положить в папку и запустить.
Обновлено: 29 октября 2026 года. Система Horizon активно меняется. В актуальной документации есть два разных пути: моды-контент (.hmod) и нативные моды на Rust (.hnmod). Ниже разберём каждый, покажем сборку и объясним, как читать Mod API.
Быстрый выбор: какой мод вам нужен?
| Задача | Что выбрать | Нужно ли программировать? |
|---|---|---|
| Новый предмет, блок, рецепт, текстура, лут или структура | Content mod (.hmod) | Нет — файлы данных и ресурсы |
| HUD, счётчик FPS, горячая клавиша, игровая команда, новое поведение клиента | Native mod (.hnmod) | Да — Rust |
| События сервера, команды, работа с миром | Экспериментальный серверный Mod API | Да, с учётом ограничений версии |
Важно: текущий официальный гайд описывает нативные моды через .hnmod и horizon-mixins. Отдельная страница Mod API всё ещё документирует WebAssembly/SDK, команды cargo horizon-mod и .hmod. Это разные реализации/пути; не смешивайте команды и типы пакетов. Перед сборкой проверьте актуальность документации и выбранной версии клиента.
1. Что подготовить
Нужны установленный Horizon Launcher и подготовленные файлы игры, Rust (стабильная версия), Git, Python 3.11+ и rsync. Для проверки нативных модов на Windows разработчики рекомендуют WSL. На Linux и macOS используется обычный терминал.
Проверьте инструменты:
rustc --version
cargo --version
git --version
python3 --version
rsync --versionЕсли какая-то команда не найдена, установите соответствующую программу. Rust берите с rustup.rs, код Horizon и примеры — только из официальных репозиториев.
2. Создаём первый нативный мод (.hnmod): пример Playtime
Нативный мод встраивается в исходный код клиента перед компиляцией. Он не изолирован: такой код может получить права вашего пользователя на компьютере. Поэтому не собирайте чужие непроверенные пакеты.
Скачайте официальный каталог модов:
git clone https://github.com/horizon-rust/horizon-mods
cd horizon-modsВ каталоге native/ найдите примеры, включая playtime (время игры) и fps-overlay. Для первого знакомства лучше скопировать пример в отдельную рабочую папку и менять его постепенно.
Типичная структура примера:
playtime/
├── Cargo.toml
├── compatibility.json
└── mixins/playtime/
├── horizon-mixin.toml
├── runtime.rs
├── tick.rs
└── hud.rsЧто означает каждый файл: Cargo.toml описывает Rust-проект и тесты; compatibility.json фиксирует проверяемые точки интеграции и совместимые коммиты Horizon; horizon-mixin.toml — манифест модуля; runtime.rs — собственная логика; tick.rs и hud.rs подключают её к событиям клиента.
3. Проверяем код перед сборкой
Находясь в папке скачанного horizon-mods, выполните:
python3 native/tools/native.py check /полный/путь/к/playtimeУтилита применяет ваш мод к исходникам Horizon и запускает cargo check. Если в манифесте неправильная точка интеграции, проверка сообщит об ошибке; если ошибка в Rust, вы увидите имя файла и строку. Первая проверка дольше, поскольку загружаются зависимости.
Контрольная точка: команда check должна завершиться успешно. Если она падает, не переходите к сборке.
4. Компилируем мод и запускаем в игре
В актуальном руководстве для нативных модов используется команда лаунчера:
horizon-launcher native-build /полный/путь/к/playtime/mixins/playtime --trust-native-codeЛаунчер собирает отдельный вариант клиента с вашим кодом, затем создаёт экземпляр Native mods. Откройте этот экземпляр и нажмите Play. В настройках лаунчера может потребоваться включить Native mods (experimental). При первой сборке лаунчер устанавливает собственную среду Rust; повторные сборки обычно короче.
Флаг --trust-native-code означает, что вы осознанно разрешаете запуск нативного кода. Не используйте его для непроверенных архивов.
5. Как работают хуки — краткий перевод и объяснение
*Hook* — заранее предусмотренная точка, в которой Horizon вызывает код мода. Основные хуки из актуальной документации:
| Хук | Когда срабатывает | Что можно сделать |
|---|---|---|
native_tick() | На игровом тике | Счётчики, обновление состояния |
native_frame(elapsed) | На каждом кадре | Анимация, замер времени |
native_hud(batch, corners) | При рисовании HUD | Текст, панели, показатели |
native_key(key, pressed) | Нажатие и отпускание клавиши | Горячие клавиши |
native_command(command, ran) | При вводе команды | Собственная команда |
native_wheel(steps, claimed) | Прокрутка колеса | Изменение управления |
native_zoom(zoom) | При установке зума | Собственное масштабирование |
Например, чтобы вывести счётчик времени в углу, можно отслеживать время в native_tick и показывать его через native_hud. Полный пример Playtime уже есть у разработчиков; используйте его как основу вместо непроверенного кода из комментариев.
Подробнее: точки интеграции и вспомогательные функции, формат пакета.
6. Новый блок или предмет без Rust: content mod (.hmod)
Если нужны блоки, предметы, рецепты, модели или текстуры, писать Rust-код необязательно. Такой мод состоит из данных и ресурсов. Его упаковка .hmod не равна нативному .hnmod.
Что понадобится: идентификатор вашего пространства имён, JSON-файлы описания контента, локальные текстуры и модели, рецепты и названия. Начните с официального примера ruby-content из репозитория Horizon SDK и пошагового руководства Content mods. Проверяйте структуру файлов по используемой версии, а не по старому Java-моду.
7. Mod API на русском: WebAssembly и Cargo
Отдельная документация Mod API описывает SDK, в котором Rust-код компилируется в WebAssembly и ограничивается разрешёнными возможностями (*capabilities*). Это не тот же сценарий, что нативный .hnmod.
Ключевые части API:
game— чтение ограниченной информации об игроке и игровом времени;chat— локальные сообщения и обработка чата;hud— текстовая панель поверх экрана;storage— небольшое собственное хранилище мода;log— диагностические сообщения;players— возможности серверных модов (экспериментально).
Для WebAssembly-ветки документация приводит следующие команды:
rustup target add wasm32-unknown-unknown
cargo install --git https://github.com/horizon-rust/horizon cargo-horizon-mod
cargo horizon-mod new my-mod
cd my-mod
cargo horizon-mod build
cargo horizon-mod testВнимание: это команды SDK/WebAssembly, а не инструкции по сборке нового нативного .hnmod. Наличие этих команд в API-справочнике не гарантирует их поддержку конкретной актуальной сборкой Horizon. Сначала сверяйте версии.
В SDK есть клиентские события init, tick, frame, command, chat. Экспериментальный серверный API добавляет события подключения, выхода игроков и взаимодействия с блоками. Разрешения декларируются в манифесте. Не все привычные функции Fabric/Forge здесь доступны: работа с инвентарём, сущностями, сложными интерфейсами и сетью развиваются отдельно.
Справочник также описывает ограничения песочницы, включая объём хранилища и количество выводимых строк. Для конкретных чисел, структур и типов используйте Mod API reference: они могут меняться с релизами.
8. Тестирование: не пропускайте этот шаг
Для нативных модов проверьте cargo test в папке проекта, затем native.py check и поведение в игровом экземпляре. Для WebAssembly SDK предусмотрено cargo horizon-mod test, которое прогоняет сценарии без запуска игры. Смотрите официальную инструкцию по тестированию.
Чек-лист: мод собирается без ошибок; HUD не закрывает интерфейс; после перезапуска настройки сохраняются; игра нормально работает без мода; нет неожиданных запросов разрешений.
9. Если сборка выдаёт ошибку
cargo: command not found — Rust не установлен или терминал не видит путь к нему. Переоткройте терминал и проверьте cargo --version.
python3: command not found — установите Python 3.11+; на Windows запускайте проверки в WSL.
rsync: command not found — установите rsync в вашу среду разработки.
horizon-launcher: command not found — проверьте установку лаунчера и его доступность из терминала; если команда отсутствует в сборке, воспользуйтесь графическим интерфейсом или сверяйтесь с документацией вашей версии.
Ошибка в horizon-mixin.toml или compatibility.json — сравните файлы с официальным рабочим примером и проверьте совместимость коммита.
Java .jar не запускается — это ожидаемо. Используйте перенос данных и ресурсов либо переписывайте игровую логику под доступные хуки/SDK.
10. Публикация и безопасность
Протестированный мод можно подготовить для каталога Horizon. Указывайте версию, лицензию, исходный код и описание разрешений; следуйте актуальному регламенту публикации. Нативный мод несёт больший риск, потому что работает без песочницы; это важно честно объяснять пользователям.
Не загружайте сомнительные архивы и не запускайте чужие скрипты с правами администратора. Работайте с копией мира и храните проект в Git.
Краткая памятка
Если вам нужен HUD или новая логика: клонируйте horizon-mods → возьмите Playtime/FPS Overlay → измените Rust-код → native.py check → horizon-launcher native-build → проверьте отдельный экземпляр Native mods.
Если нужны блоки, рецепты, модели и текстуры: выберите content mod и следуйте руководству для .hmod.
Если нужна экспериментальная серверная логика: откройте Mod API 0.3 и сначала проверьте, что нужный хук уже реализован.
Официальные материалы и примеры
- Как сделать мод: актуальное пошаговое руководство
- Mod API: обзор SDK и разрешений
- Хуки и пример Playtime
- Content mods: блоки и предметы
- Тестирование
- Публикация
- Исходники Horizon
- Официальные нативные моды и примеры
Материал подготовлен как самостоятельная русскоязычная инструкция по официальной документации, а не как её дословная копия. Интерфейс и команды Horizon могут изменяться.