Fabric Language Ruby

Создано Bownlux, разработчиком RevivalSMP.net

Примечание об обновлениях: крупные обновления этого проекта выходят нечасто, так как большую часть времени я уделяю RevivalSMP.net и Retromod. Ожидайте скорее небольшие поддерживающие релизы (новые версии Minecraft, обновления JRuby, исправления багов), чем постоянный поток новых возможностей. Issues и pull requests по-прежнему приветствуются. Пишите моды для Fabric на Ruby! Это языковой модуль для Fabric, аналог fabric-language-kotlin для Ruby. Он работает на встроенной среде JRuby, которая поставляется внутри jar-файла мода вместе с полной стандартной библиотекой Ruby. Ваш fabric.mod.json указывает точку входа на скрипт .rb, а этот мод делает всё остальное: запускает JRuby (лениво, только когда точка входа на Ruby действительно нужна), выполняет ваш скрипт и передаёт получившийся объект Ruby в Fabric Loader как обычную точку входа. Имена методов Ruby автоматически сопоставляются с Java, так что def on_initialize реализует ModInitializer#onInitialize.

class MyRubyMod
  LOGGER = org.slf4j.LoggerFactory.getLogger('my-ruby-mod')

def on_initialize LOGGER.info("Hello from Ruby #{RUBY_VERSION}!") end end

MyRubyMod

> **Примечание о логировании:** Minecraft поставляет slf4j только начиная с 1.18.2+. Целитесь в более
> старые версии? Используйте Log4j, который есть на всех поддерживаемых версиях:
> `LOGGER = org.apache.logging.log4j.LogManager.getLogger('my-ruby-mod')`, или просто используйте `puts`.
## Поддерживаемые версии
Все версии Minecraft, которые поддерживает Fabric, вплоть до самой первой (1.14). Для каждого релиза
публикуются два файла. Установите тот, что соответствует вашей версии Minecraft:
| Файл | Minecraft | Java | Встроенная среда |
| --- | --- | --- | --- |
| `fabric-language-ruby-<v>+jruby.10.x.jar` | **1.20.5 и новее** (вкл. 26.x) | 21+ | JRuby 10.0 (Ruby 3.4) |
| `fabric-language-ruby-<v>+jruby.9.4.x.jar` | **1.14-1.20.4** | 8+ | JRuby 9.4 (Ruby 3.1) |
Оба файла — это один и тот же мод (`fabric-language-ruby`, одинаковые возможности, одинаковый адаптер);
они отличаются только встроенной версией JRuby, потому что JRuby 10 требует Java 21, а старые версии
Minecraft работают на Java 8-17. Modrinth автоматически выдаёт нужный файл для вашей версии игры.
Требуется Fabric Loader 0.16.0+.
Fabric Language Ruby полностью совместим с
[fabric-language-kotlin](https://github.com/FabricMC/fabric-language-kotlin): оба языковых модуля
можно установить одновременно, так что моды на Ruby работают рядом с модами на Kotlin в одном модпаке.
Это проверено в тестах: оба адаптера плюс мод, написанный на Kotlin (Ledger), запускались на одном сервере.
## Для игроков
Если установленному вами моду нужна эта библиотека, скачайте файл, соответствующий вашей версии
Minecraft, с Modrinth (или из [релизов на GitHub](https://github.com/Bownlux/Fabric-language-Ruby/releases))
и положите его в папку `mods/`, рядом с модом, которому он нужен. Никакой настройки не требуется.
## Для разработчиков модов
### Настройка
Добавьте адаптер `ruby` в свои точки входа в `fabric.mod.json`, укажите в значении скрипт Ruby
внутри jar-файла вашего мода и добавьте зависимость от `fabric-language-ruby`:
```json
{
    "schemaVersion": 1,
    "id": "my-ruby-mod",
    "version": "1.0.0",
    "entrypoints": {
        "main": [
            {
                "adapter": "ruby",
                "value": "my_ruby_mod/main.rb"
            }
        ]
    },
    "depends": {
        "fabricloader": ">=0.16.0",
        "fabric-language-ruby": ">=1.0.0"
    }
}

my_ruby_mod/main.rb лежит в ресурсах вашего мода (так он окажется по этому пути внутри вашего jar-файла). Дайте директории уникальное имя, специфичное для мода, потому что все моды используют один общий classpath JVM. Последнее выражение скрипта — это точка входа. В примере выше это сам класс, который адаптер создаёт через new.

Синтаксис значения точки входа

Примеры всех трёх форм:

# value: "my_mod/main.rb". Последнее выражение — лямбда, что подходит для
# точек входа с одним методом, таких как ModInitializer.
-> { puts 'initialized!' }

# value: "my_mod/main.rb::MyMod::Initializer"
module MyMod
  class Initializer
    def on_initialize
      # ...
    end
  end
end

# value: "my_mod/main.rb::MyMod#init"
module MyMod
  module_function

  def init
    # ...
  end
end

Точки входа в виде ссылки на метод и лямбды направляют каждый метод интерфейса точки входа в этот единственный метод/лямбду, поэтому они подходят для интерфейсов с одним методом, таких как ModInitializer; интерфейсы точек входа с несколькими методами реализуйте классом или модулем.

Как объекты Ruby становятся точками входа Java

JRuby приводит ваш объект Ruby к запрошенному интерфейсу точки входа (ModInitializer, ClientModInitializer, DedicatedServerModInitializer, пользовательские интерфейсы и так далее). Имена методов сопоставляются автоматически: вызов onInitialize из Java направляется в ваш Ruby-метод on_initialize (или в буквальный onInitialize, если вы определите его вместо этого). Скрипт выполняется не более одного раза на мод, сколько бы точек входа на него ни ссылалось. Если последнее выражение — класс, каждая ссылка на точку входа получает собственный экземпляр; если это экземпляр (например, MyMod.new) или модуль, этот объект используется совместно.

Одна общая среда JRuby

Все моды на Ruby работают в одном общем интерпретаторе JRuby. Константы верхнего уровня, глобальные переменные, monkey-patch и java_import видны всем модам на Ruby, и мод, загружающийся позже, может

переоткрывать (или перезаписывать) классы верхнего уровня другого мода. Держи всё внутри одного уникально названного модуля на мод (module MyRubyMod ... end), делай java_import внутри своего класса/модуля, а не на верхнем уровне, и избегай $globals.

Многофайловые моды и стандартная библиотека

require_relative работает между скриптами в твоём jar, а полная стандартная библиотека Ruby доступна через обычный require:

require 'json'
require_relative 'helper'

Использование гемов (вендоринг на этапе сборки)

Установка гемов во время выполнения не поддерживается (stdlib живёт внутри jar), но гемы можно вендорить в твой мод во время его сборки. Этот репозиторий поставляет Gradle-хелпер, gradle/gem-vendor.gradle, который прогоняет весь пайплайн: он разрешает перечисленные тобой гемы (плюс их транзитивные зависимости) с rubygems.org, используя JRuby на этапе сборки, копирует каждый разрешённый гем в ресурсы твоего мода и генерирует vendor/setup.rb, который помещает каждый гем в $LOAD_PATH со схемой uri:classloader:. Скопируй файл в свой проект и подключи его в build.gradle:

apply from: 'gradle/gem-vendor.gradle'

gemVendor {
    vendorPath = 'my_ruby_mod/vendor'   // resource path the gems land under
    gem 'dentaku', '3.5.7'
    // more gem 'name', 'version' lines as needed; transitive dependencies
    // are resolved automatically, list one explicitly to pin its version
}

Затем загружай гемы из своего скрипта обычным require:

require_relative 'vendor/setup'
require 'dentaku'

Что может работать, а что нет:

• Чисто рубиновые гемы работают, как и гемы, поставляющие предсобранный JRuby jar (например, concurrent-ruby). Гемы с C-расширениями падают на этапе установки — это правильный момент, чтобы узнать об этом.
• Гемы, которые читают или пишут свои собственные файлы на диске, не будут работать изнутри jar.
• Вендоринг распространяет гемы внутри твоего jar. Проверь, что лицензия каждого гема это разрешает, и укажи атрибуцию так, как требует лицензия.
• Если ты выпускаешь для обоих вариантов, собирай шаг вендоринга для каждого варианта (хелпер использует ту версию JRuby, которую ты ему дашь), чтобы разрешение гемов соответствовало версии Ruby, которую запускают твои пользователи. Пример мода в src/testmod вендорит dentaku таким образом, и каждая CI-сборка прогоняет пайплайн на обоих вариантах. Если ты предпочитаешь вендорить вручную, сгенерированный setup.rb показывает всё, что нужно: require-директория каждого гема добавляется в $LOAD_PATH как `uri:classloader:/` (все ресурсы мода находятся в общем classpath).

Вызов Minecraft и Fabric API

Java interop — это стандартный JRuby:

class MyRubyMod
  java_import 'net.fabricmc.fabric.api.event.lifecycle.v1.ServerLifecycleEvents'

  def on_initialize
    on_started = lambda do |server|
      puts "server started: #{server.class.java_class.simple_name}"
    end

    ServerLifecycleEvents::SERVER_STARTED.register(
      on_started.to_java(ServerLifecycleEvents::ServerStarted)
    )
  end
end

MyRubyMod

Важно: Event#register(T) в Fabric API — это дженерик-метод, поэтому JRuby не может вывести интерфейс слушателя из голого блока. Конвертируй явно через lambda.to_java(TheListenerInterface), как показано выше. Для недженерик Java-методов, принимающих функциональный интерфейс, передача блока напрямую работает нормально. Замечание об именах классов по эпохам Minecraft: на Minecraft 26.x и новее игра не обфусцирована, поэтому Ruby-скрипты могут вызывать классы Minecraft по их настоящим (Mojang) именам. На старых версиях (1.14-1.21.x) собственные классы Minecraft имеют во время выполнения intermediary имена (в стиле net.minecraft.class_310). Интерфейсы точек входа, Fabric API, Fabric Loader API (включая FabricLoader.getInstance.getMappingResolver для перевода имён) и все Java-библиотеки не затронуты и сохраняют свои обычные имена.

Ограничения

• Никаких миксинов из Ruby. Миксинам нужны классы времени компиляции; Ruby-мод, которому они нужны, должен поставлять небольшое Java/mixin-ядро вместе со своими Ruby-точками входа (оба могут жить в одном jar).
• Никакой установки гемов во время выполнения. Вендорь гемы на этапе сборки, как объяснено выше.
• Скрипты, нацеленные на legacy-файл, должны придерживаться возможностей Ruby 3.1 (современный файл работает на Ruby 3.4).

Пример мода

Полный рабочий пример живёт в src/testmod: мод, написанный целиком на Ruby, который логирует из своей точки входа main, использует require/require_relative, вызывает вендоренный гем (dentaku) и регистрирует колбэк жизненного цикла Fabric API. Запусти его против dev-сервера с помощью:

./gradlew runTestmodServer

Сборка из исходников

Требуется JDK 25 (собранные jar всё ещё работают на Java 8/21+, как описано выше).

./gradlew build                    # modern variant  -> build/libs/*+jruby.10.*.jar
./gradlew build -Pvariant=legacy   # legacy variant  -> build/libs/*+jruby.9.4.*.jar

Каждая сборка прогоняет набор юнит-тестов против JRuby этого варианта и также производит отдельный jar примера мода (*-testmod.jar). JRuby поставляется как jar-in-jar (org.jruby:jruby-core + org.jruby:jruby-stdlib); Fabric Loader дедуплицирует вложенные jar по версии, если несколько установленных модов поставляют JRuby.

Версионирование

`+jruby., например 1.0.0+jruby.10.0.6.0. Это повторяет схему fabric-language-kotlin. Только часть до + участвует в разрешении зависимостей, поэтому "fabric-language-ruby": ">=1.0.0"` соответствует обоим файлам вариантов.

Лицензия

MIT