Papyrus
Papyrus 为 Fabric 加载器的 MappingResolver 提供了多种具名映射(named mappings)。这使得在运行时更友好地访问映射成为可能,例如在反射中使用具名类而非中间层(intermediary)类。
Papyrus 会在首次运行特定版本时下载映射,并将缓存的映射以 tiny v2 格式存储在
${game_dir}/cache/papyrus/${mapping}_${version}.tiny
使用 Papyrus
要使用 Papyrus,只需将托管 Papyrus 的 Maven 仓库添加到你的 Gradle 构建脚本中:
# Kotlin DSL
repositories {
maven("https://maven.nelind.dk/releases") {
name = "Nelind Maven"
}
}
# Groovy DSL
repositories {
maven {
name 'Nelind Maven'
url 'https://maven.nelind.dk/releases'
}
}
然后通过标准的 Loom “include” Gradle 配置包含 Papyrus JIJ:
# Kotlin DSL
modRuntimeOnly(include("dk.nelind:papyrus:(version)")!!)
# Groovy DSL
modRuntimeOnly include("dk.nelind:papyrus:(version)")
你也可以选择不包含 Papyrus JIJ;在这种情况下,请确保在 fabric.mod.json 中手动将 Papyrus 添加为依赖项。如果你需要访问 Papyrus 的内部实现,可以使用 modApi 配置而不是 modRuntimeOnly 配置来引入 Papyrus。
然后在 fabric.mod.json 中,你需要告诉 Papyrus 你需要访问哪些映射及其对应版本:
{
...
"custom": {
"papyrus": {
"mappings": [
"mojmap",
"yarn:build.1"
]
}
}
}
接着通过任意已添加的映射命名空间获取并使用 MappingResolver:
MappingResolver mappingResolver = FabricLoader.getInstance().getMappingResolver();
String runtimeClassNameFromYarnName = mappingResolver.mapClassName("yarn:build.1", yarnClassName);
String runtimeClassNameFromMojmapName = mappingResolver.mapClassname("mojmap", mojmapClassName);
使用说明:
-
Papyrus 在 preLaunch(预启动)阶段注入所添加的映射,因此你应该在此之后某个时间点才使用 Papyrus。
如果未来 Fabric 加载器插件的相关讨论中有合理理由让 Papyrus 成为加载器插件,它将会这样做。希望届时能在 preLaunch 阶段提供额外的映射。
-
Mojmap 对继承的类成员处理方式与 Intermediary 和 Yarn 不同!
Intermediary 和 Yarn 仅针对在其各自映射定义中直接定义的成员提供映射,而 Mojmap 则为该类拥有的所有成员(包括继承而来的)提供名称。在实践中这意味着,如果你在某个类中请求 Mojmap 的方法名,而该类继承了该方法且运行时映射是 Intermediary 或 Yarn,你将得到 null,因为解析器可以找到该名称(在 Mojmap 中),但在运行时映射中该方法没有定义的名称。这对你意味着什么? 如果你使用 Mojmap 名称作为映射解析器的输入,你应该使用方法或字段声明所在的类的类名,而不是你想要修改的类的类名。或者,你可以进行空值检查,并通过编程方式查找该类的超类,然后以该类作为拥有者向映射解析器请求成员名称。
提供的映射
| 映射类型 |
映射解析器中使用的命名空间 |
| Mojang Mappings |
mojmap |
| Yarn |
yarn |
关于版本控制的说明
由于 Papyrus 几乎完全独立于游戏本身的版本,模组版本号表示该构建所针对的 Java 版本。例如,Papyrus x.y.z+java.17 是针对 Java 17 构建的,因此支持任何同样针对 Java 17 构建的游戏版本(即从 1.18 到 1.20.4 的所有版本,含两端)。
Papyrus
Papyrus provides various named mappings to the Fabric loader MappingResolver. This allows for more developer friendly
access to mappings at runtime for example for using named classes in reflection instead of intermediary.
Papyrus downloads mappings on the first run on any given version and stores cached mappings in tiny v2 format at
${game_dir}/cache/papyrus/${mapping}_${version}.tiny
Using Papyrus
To use Papyrus just add the maven repository which hosts Papyrus to your gradle build script:
# Kotlin DSL
repositories {
maven("https://maven.nelind.dk/releases") {
name = "Nelind Maven"
}
}
# Groovy DSL
repositories {
maven {
name 'Nelind Maven'
url 'https://maven.nelind.dk/releases'
}
}
and then include Papyrus JIJ with the standard loom "include" gradle configuration:
# Kotlin DSL
modRuntimeOnly(include("dk.nelind:papyrus:(version)")!!)
# Groovy DSL
modRuntimeOnly include("dk.nelind:papyrus:(version)")
You can also choose to not include Papyrus JIJ in that case make sure to manually add Papyrus as a dependency in your
fabric.mod.json. If you need to access Papyrus internals you can also add Papyrus with the modApi configuration instead of the
modRuntimeOnly configuration.
Then in your fabric.mod.json you need to tell Papyrus what mappings you need access to and the version thereof:
{
...
"custom": {
"papyrus": {
"mappings": [
"mojmap",
"yarn:build.1"
]
}
}
}
Then get and use the MappingResolver with any of the added mapping namespaces:
MappingResolver mappingResolver = FabricLoader.getInstance().getMappingResolver();
String runtimeClassNameFromYarnName = mappingResolver.mapClassName("yarn:build.1", yarnClassName);
String runtimeClassNameFromMojmapName = mappingResolver.mapClassname("mojmap", mojmapClassName);
Usage notes:
-
Papyrus injects the added mappings at preLaunch so you should only use Papyrus at some point after that.
If the here and there talks about possible future fabric loader plugins go somewhere where it makes sense for
Papyrus to become a loader plugin it will. Hopefully making extra mappings available at preLaunch
-
Mojmap handles inherited class members differently from Intermediary and Yarn!
Intermediary and Yarn only give mappings for members defined directly in a class in said classes mapping
definition whereas Mojmap gives names for all members a class has, inherited or not. In practice this means that if you
ask the mapping resolver for a Mojmap method name in a class where the class has inherited the method while the runtime
mappings are either Intermediary or Yarn you'll get null because the resolver can find that name (in Mojmap) but
there is no defined name for that method in the runtime mapping. What does this mean for you? If you're using
Mojmap names as the input to the mapping resolver you should use the class name of the class a method or field is
declared on not the class you want to modify. Alternatively you can have a null check and programmatically find the
class's super class and ask the mapping resolver for the member name with that class as the owning class.
Provided mappings
| Mappings |
Namespace used in mapping resolver |
| Mojang Mappings |
mojmap |
| Yarn |
yarn |
Note on versioning
Since Papyrus is almost entirely independent of the version of the game itself. The mod version indicates the java
version said build was built against. For example Papyrus x.y.z+java.17 is built against java 17 and as such supports
any game version that's also built against java 17 (that being any version from 1.18 to 1.20.4 inclusively).
评论 0
登录后参与评分
还没有评论,来抢沙发吧