Моды на вашем сервере

Предварительная версия

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

Включите моды

Моды загружаются из папки mods в папке данных сервера:

Способ запуска	Папка модов
Приложение / командная строка	<папка данных>/mods (папка данных задаётся через BLOCKHEADS_DATA_DIR, иначе это GNUstep/Library/ApplicationSupport/TheBlockheads в вашей домашней папке)
Docker	/data/mods внутри тома
Везде	задайте BLOCKHEADS_MODS_DIR с другой папкой

Без папки модов (или с пустой) сервер ведёт себя точно как обычный: те же байты, сохранения и вывод.

Установите мод

1. Скачайте файл .bhmod со страницы модов (или получите его у автора). Распакованная папка мода (с mod.toml внутри) тоже подойдёт.
2. Положите его в папку модов.
3. Выдайте ему разрешения в mods.toml (ниже).
4. Перезапустите сервер. В логе будет loaded 1 mod(s): … или причина, по которой мод не загрузился.

В приложении Server есть и экран «Моды» для папки модов (сборки для разработки).

mods.toml

mods.toml лежит в папке модов. Один раздел на каждый id мода:

[hello-lua]
grant = ["players:chat"]

[noisy-mod]
enabled = false   # остаётся установленным, но не загружается

Моду без разрешений раздел не нужен. Мод, который просит невыданное разрешение, не загружается; моды, которые от него зависят, тоже пропускаются.

Разрешения

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

Всё остальное разрешений не требует: события, собственные команды, таймеры, собственное хранилище, чат одному игроку и сервисы модов, от которых он зависит. Что просит мод, видно на его странице в общем списке.

Ограничения по времени и памяти

Моды работают в главном потоке сервера, поэтому каждый из них держится на коротком поводке:

• Каждый вызов в мод может занимать 25 мс (после 5 мс в лог пишется предупреждение).
• Все моды вместе получают 20 мс на шаг мира; таймеры сверх этого ждут следующего шага.
• Каждому моду выделяется 32 МиБ памяти.

Ошибка, превышение времени или нехватка памяти считаются сбоем. 3 сбоя за 60 с отключают мод до следующего перезапуска; в логе будет disabled: 3 faults within 60 s и название ошибки. Сообщите об этом автору мода.

Управление работающими модами

Администраторы могут смотреть список модов, перезагружать их и смотреть замеры времени без перезапуска сервера: /mods, /mods reload [id], /mods timings. См. Горячая перезагрузка и замеры времени.

Хранилище

Каждый мод хранит свои данные отдельно для каждого мира в saves/<world>/mods/storage, не смешивая их с самим миром. Если удалить эту папку, данные модов сбросятся, а мир не пострадает. Делайте её резервную копию вместе с миром.

Java-моды (JVM)

Моды на Java или Kotlin работают в виртуальной машине Java внутри сервера. JVM нельзя запереть в песочнице, поэтому по умолчанию это выключено, а у мода должно быть разрешение native:

1. Установите на машину Java 8 или новее (или укажите серверу путь к ней).
2. Включите Настройки > Java-моды в приложении сервера (или запустите сервер с BLOCKHEADS_JVM=1; BLOCKHEADS_JAVA_HOME задаёт папку Java). Приложение должно быть собрано с поддержкой Java, иначе под переключателем будет об этом написано.
3. Выдайте моду native в mods.toml. Красное предупреждение остаётся на моде.

Включайте только для модов, которым доверяете. Ограничение по времени не прерывает плотный цикл в коде Java, только блокирующий вызов.

Игроки с обычной игрой

• Только серверные моды: зайти может любой с обычной игрой.
• Моды, обязательные на клиенте превью: игроков без загрузчика модов не пускают (их игра пишет, что клиент устарел). На странице мода такие моды помечены как client-required.