Fabric Language Ruby

模组

· 作者 Bownlux

为 Fabric 模组加载器启用 Ruby

0 本站下载 0 关注 更新于 4 个月前

最新 1.0.0+jruby.9.4.15.0 · 1.20.4 · Fabric

一键开服(送7天)

由 Bownlux 制作,RevivalSMP.net 的开发者

关于更新: 本项目的大型更新不会频繁发布,因为我的大部分时间都投入到了 RevivalSMP.net 和 Retromod 上。请预期会有较小的维护版本(新的 Minecraft 版本、JRuby 升级、错误修复),而不是持续的功能流。欢迎提交问题报告和拉取请求。

用 Ruby 编写 Fabric 模组!这是一个 Fabric 语言模块,相当于 fabric-language-kotlin 的 Ruby 版本。它由嵌入在模组 jar 包中的 JRuby 运行时驱动,并附带完整的 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 仅在 1.18.2+ 版本中提供 slf4j。如果目标是旧版本?请使用 Log4j,它在所有受支持版本中都存在:LOGGER = org.apache.logging.log4j.LogManager.getLogger('my-ruby-mod'),或者直接使用普通的 puts。

支持的版本

Fabric 支持的每个 Minecraft 版本,从最初版(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 完全兼容:这两个语言模块可以同时安装,因此 Ruby 模组可以与 Kotlin 模组一起在一个整合包中运行。这已通过在一台服务器上同时运行两个适配器以及一个用 Kotlin 编写的模组(Ledger)进行测试验证。

对于玩家

如果你安装的某个模组需要此库,请从 Modrinth(或 GitHub releases)下载与你的 Minecraft 版本匹配的文件,并将其放入你的 mods/ 文件夹中,放在需要它的模组旁边。无需配置。

对于模组开发者

设置

将 ruby 适配器添加到 fabric.mod.json 中的入口点,将值指向你模组 jar 内的 Ruby 脚本,并依赖于 fabric-language-ruby:

{
	"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 位于你模组的 resources(资源)中(因此它会出现在你 jar 包的该路径下)。给目录起一个唯一的、特定于模组的名字,因为所有模组共享同一个 JVM 类路径。

脚本的最后一个表达式 是入口点。在上方的示例中,它是类本身,适配器会对其进行实例化。

入口点值语法

value 含义
"path/to/script.rb" 评估脚本;其最后一个表达式是入口点。类将通过 new 实例化;模块、实例或 lambda 则按原样使用。
"path/to/script.rb::Some::Constant" 评估脚本,然后解析(命名空间化的)常量。类将被实例化;其他任何内容均按原样使用。
"path/to/script.rb::Some::Constant#method_name" 解析常量并绑定 method_name。对于类,实例方法优先(为其创建新实例);否则绑定类/模块级别的方法(module_function,def self.)。对于任何其他常量,该方法将在对象本身上绑定。

三种形式的示例:

# value: "my_mod/main.rb"。最后一个表达式是一个 lambda,适用于像 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

方法引用和 lambda 入口点会将入口点接口的每个方法路由到那一个方法/lambda,因此它们适合像 ModInitializer 这样的单方法接口;对于实现多方法入口点接口,请使用类或模块。

Ruby 对象如何成为 Java 入口点

JRuby 会将你的 Ruby 对象强制转换为目标入口点接口(ModInitializer、ClientModInitializer、DedicatedServerModInitializer、自定义接口等)。方法名会自动映射:对 onInitialize 的 Java 调用会分发到你的 Ruby on_initialize(如果你定义的是字面量 onInitialize,则分发到该名称)。

无论有多少个入口点引用它,脚本最多只会被评估一次。如果最后一个表达式是类,每个入口点引用都会获得自己的实例;如果是实例(例如 MyMod.new)或模块,则该对象被共享。

一个共享的 JRuby 运行时

所有 Ruby 模组都在一个共享的 JRuby 解释器中运行。顶层常量、全局变量、monkey-patches(猴子补丁)以及 java_import 在所有 Ruby 模组之间可见,加载较晚的模组可以重新打开(或覆盖)另一个模组的顶层类。请确保每个模组内的所有内容都位于一个唯一命名的模块中(module MyRubyMod ... end),在您的类/模块内部而非顶层进行 java_import,并避免使用 $globals。

多文件模组与标准库

require_relative 可在 jar 包内的脚本之间正常工作,完整的 Ruby 标准库可通过普通的 require 使用:

require 'json'
require_relative 'helper'

使用 gems(构建时本地化)

不支持在运行时安装 gems(因为标准库位于 jar 包内),但可以在构建模组时将 gems 本地化到模组中。此仓库提供了一个 Gradle 辅助工具 gradle/gem-vendor.gradle,用于运行整个流程:它使用构建时的 JRuby 从 rubygems.org 解析您列出的 gems(及其传递依赖项),将每个解析到的 gem 复制到模组的资源中,并生成一个 vendor/setup.rb,通过 uri:classloader: 方案将所有 gem 添加到 $LOAD_PATH。

将该文件复制到您的项目中,并在 build.gradle 中进行配置:

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

gemVendor {
    vendorPath = 'my_ruby_mod/vendor'   // gems 存放的资源路径
    gem 'dentaku', '3.5.7'
    // 根据需要添加更多 gem 'name', 'version' 行;传递依赖项会自动解析,显式列出其中一个以固定其版本
}

然后在您的脚本中通过普通的 require 加载 gems:

require_relative 'vendor/setup'
require 'dentaku'

可行与不可行的情况:

  • Pure-Ruby gems 可以工作,带有预构建 JRuby jar 的 gem(例如 concurrent-ruby)也可以工作。包含 C 扩展的 gem 会在安装时失败,这正是发现问题的好时机。
  • 在磁盘上读取或写入自身文件的 gem 无法在 jar 包内工作。
  • 本地化会将 gems 分发到您 jar 包内部。请检查每个 gem 的许可证是否允许这样做,并按照许可证要求注明出处。
  • 如果您同时发布两个变体版本,请针对每个变体构建 vendoring 步骤(该辅助工具会使用您指定的 JRuby 版本),以便 gem 解析与您用户运行的 Ruby 版本匹配。

src/testmod 中的示例模组以这种方式本地化了 dentaku,并且每次 CI 构建都会针对两个变体测试该流程。如果您希望手动本地化,生成的 setup.rb 展示了所需的一切:每个 gem 的 require 目录作为 uri:classloader:/<resource path> 添加到 $LOAD_PATH(所有模组资源都在共享类路径上)。

调用 Minecraft 和 Fabric API

Java 互操作是标准的 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

重要提示: Fabric API 的 Event#register(T) 是一个泛型方法,因此 JRuby 无法从裸块中推断监听器接口。如上所示,请使用 lambda.to_java(TheListenerInterface) 进行显式转换。对于接受函数接口的非泛型 Java 方法,直接传递块即可正常工作。

关于不同 Minecraft 版本的类名说明: 在 Minecraft 26.x 及更高版本中,游戏未混淆,因此 Ruby 脚本可以通过其真实名称(Mojang 命名)调用 Minecraft 类。在旧版本(1.14-1.21.x)中,Minecraft 自身的类在运行时具有 intermediary 名称(net.minecraft.class_310 风格)。入口点接口、Fabric API、Fabric Loader API(包括 FabricLoader.getInstance.getMappingResolver 用于转换名称)以及所有 Java 库不受影响,并保持其正常名称。

限制

  • 不支持从 Ruby 使用 mixins。 Mixins 需要编译时的类;如果需要 mixins 的 Ruby 模组应与其 Ruby 入口点一起提供一个小型 Java/mixin 核心(两者可以存在于同一个 jar 包中)。
  • 不支持运行时 gem 安装。 如前所述,请在构建时本地化 gems。
  • 目标为遗留文件的脚本应坚持使用 Ruby 3.1 特性(现代文件运行 Ruby 3.4)。

示例模组

一个完整可用的示例位于 src/testmod:一个完全用 Ruby 编写的模组,从其 main 入口点记录日志,使用 require/require_relative,调用本地化的 gem(dentaku),并注册 Fabric API 生命周期回调。使用以下命令针对开发服务器运行它:

./gradlew runTestmodServer

从源代码构建

需要 JDK 25(构建出的 jar 包仍如上文所述在 Java 8/21+ 上运行)。

./gradlew build                    # 现代变体  -> build/libs/*+jruby.10.*.jar
./gradlew build -Pvariant=legacy   # 遗留变体  -> build/libs/*+jruby.9.4.*.jar

每次构建都会针对该变体的 JRuby 运行单元测试套件,并生成一个独立的示例模组 jar 包(*-testmod.jar)。JRuby 以 jar-in-jar 方式捆绑(org.jruby:jruby-core + org.jruby:jruby-stdlib);如果安装了多个携带 JRuby 的模组,Fabric Loader 会根据版本去重嵌套 jar 包。

版本控制

格式为 <modVersion>+jruby.<bundledJRubyVersion>,例如 1.0.0+jruby.10.0.6.0。这模仿了 fabric-language-kotlin 的方案。只有 + 之前的部分参与依赖解析,因此 "fabric-language-ruby": ">=1.0.0" 匹配两个变体文件。

许可证

MIT

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源