Как сделать мод

Моды добавляют в The Blockheads новые возможности: команды чата, новые правила, инструменты для администраторов серверов и, позже, изменения, которые игроки увидят в игре. Что сделали другие, можно посмотреть на странице модов.

Что работает сегодня

bhmod (создание, проверка, упаковка) работает, а Blockheads Server запускает Lua-моды в своих сборках для разработки, а также WASM-моды (Rust). Клиентские моды работают с загрузчиком модов PC-версии и с патчем загрузчика для Android в Patcher; оба пока в сборках для разработки и появятся в следующих релизах.

С чего начать

1. Ваш первый Lua-мод: от bhmod new до работающего сервера.
2. События, команды и таймеры, хранилище.
3. Работа с другими модами: сервисы, свои события, каналы.
4. Горячая перезагрузка и замеры времени: меняйте мод без перезапуска мира.
5. Публикация в общем списке.

Больше нравится Rust? Смотрите первый мод на Rust. Все функции описаны в справочнике API.

Стороны

Мод работает на одной или на обеих сторонах:

• server: работает на сервере.
• client: работает в игре на устройстве игрока (нужен загрузчик модов).
• both: есть серверная и клиентская часть. Мод можно пометить как client-required (обязателен на клиенте), тогда игроки без него не смогут зайти.

Языки

Lua (Luau) — самый простой. Rust, скомпилированный в WebAssembly (WASM), тоже работает; C, Zig, Go и другие, умеющие собирать компоненты WASM, появятся позже. Работает и Java (а также Kotlin или любой язык JVM): выполните bhmod new my-mod --lang java. Моды на разных языках могут вызывать друг друга.

Java-моды и нативные моды работают без песочницы

Java-моды (JVM) и нативные моды (они перехватывают саму игру) работают со всеми правами сервера или игры. Им нужно разрешение native, они показываются с красным предупреждением и выключены, пока вы их не включите: поддержка JVM — это переключатель (сервер: Настройки > Java-моды; PC Port: настройки модов в лаунчере; Android: переключатель Java-моды на экране модов). Нативные моды загружаются только из проверенного публичного списка. Подробнее: JVM-моды, нативные моды.

mod.toml

У каждого мода есть файл mod.toml. Основные поля:

Поле	Значение
id, version, name, description	Кто этот мод. Id состоит из строчных букв, цифр, - и _.
authors, license	Кто сделал и под какой лицензией.
api	С какими версиями API модов он работает, например ^0.2 (версии API).
[sides], [entry]	Где он работает и какой файл его запускает.
[dependencies]	Другие моды, которые ему нужны.
[permissions]	Что ему разрешено (ниже).

Полный формат описан в документации SDK.

Разрешения

Мод может делать только то, что разрешено его правами, и владелец сервера должен выдать каждое из них:

• world: none, read или write.
• players: любые из chat, teleport, kick, ban, inventory, health.
• net-http: сайты, к которым он может подключаться.
• channels: собственные сообщения между сервером, клиентами и другими модами.
• native: нативный код вне песочницы. Показывается с красным предупреждением и проверяется вручную.

Запрашивайте только то, что нужно. Что видят владельцы серверов: Моды на вашем сервере.

Публикация

Моды попадают в каталог через pull request в Blockheads-Club/mods. Шаги, правила и проверки описаны на странице «Отправить мод», а коротко в разделе Публикация.