FarlandsOrigin
适用于 Paper/Folia 服务器的 Farlands
ThePotatoArchivist's ClassicFarlands(MIT 许可 - 请阅读 LICENSE 文件)从 Fabric 移植到 Paper/Folia,
针对 Minecraft 26.1 / 26.2。
警告:由 AI 制作(因为我不懂 Java)- 请支持 原作者
我是一个随机的开发者,你真的不应该信任你在互联网上找到的随机东西。看看源代码,它只有几百行。(点击侧边的 GitHub “查看源码”链接)。如果你愿意,也可以使用 mvn clean package 自行编译项目(需要安装 Java JDK 21+ 和 Maven)。
在部署前请通读整个文件。 这不是常规的“针对不同 API 重新编译”的移植。Fabric 给模组提供了三样 Paper 插件 API 所没有的东西:在 Mojang 注册表冻结之前运行的初始化钩子、对内部世界生成类进行 Mixin 字节码注入,以及在加载时对数据包文件进行通用的 JSON 修补。以下内容都是为了在不使用上述任何一项的情况下替代这三项功能而存在的。
与 Fabric 模组的区别及原因
| Fabric 模组部分 |
Paper 移植版 |
原因 |
Registry.register(BuiltInRegistries.DENSITY_FUNCTION_TYPE, ...) in onInitialize |
FarlandsOriginBootstrap (一个 PluginBootstrap) + NmsRegistryUnfreezer, 反射 |
Paper 插件在 BuiltInRegistries 已经被冻结之后才加载;Paper API 根本没有这个注册表的接口(对照当前的 RegistryEvents javadocs 检查过——它只涵盖附魔/实体变体/对话框等,不包含世界生成)。 |
RadiusCheck.java |
逐字移植 |
纯原版 DensityFunction 代码,没有任何 Fabric 特定内容。 |
BlendedNoiseMixin / PerlinNoiseMixin (SpongePowered Mixin) |
FarlandsOriginAgent + BlendedNoiseTransformer / PerlinNoiseTransformer (通过 java.lang.instrument agent 使用原始 ASM) |
现代 SpongePowered Mixin(版本 mixinextras/@ModifyExpressionValue 所需的那个)在没有模组加载器的情况下没有支持的独立模式——它是围绕与特定启动平台绑定的 IMixinService 构建的。与其发布一个不可验证的 Mixin 引导序列,我直接使用 ASM 进行了相同的两个字节码编辑,这是完全独立可用的。 |
Mixson (noise_settings 的通用运行时 JSON 修补) |
FarlandsOriginDatapackInstaller (自动,在引导时) / tools/build_datapack.py (手动后备) + 配套数据包 |
Fabric 的资源重载事件之外不存在等效项。数据包只能覆盖整个注册表文件,而不能修补一个字段——因此与其在这里无法验证的某个 Minecraft 版本的 vanilla noise_settings.json 内容进行猜测,而是从运行中服务器自己的 classpath(或手动地,你的服务器 jar)中读取它,并仅修补 final_density,就像 Mixson 所做的那样,只是在安装时而不是每次加载时进行。 |
Quilt Config (FarlandsOriginConfig) |
FarlandsOriginState + config.yml |
Kaleido/Quilt Config 在 Paper 上不可用;替换为普通的 Bukkit 配置。相同的 distance 选项,相同的算术运算。 |
安装
-
如果你还没有 Gradle wrapper,请先生成一个。 使用 Gradle
9.1.0 或更高版本——Gradle 仅在 9.1.0 中添加了对运行于 JDK 25 的支持(较旧的 Gradle,包括整个 8.x 系列,在 JDK 25 系统上会因“Unsupported class file major version 69”而失败):
cd farlandsorigin
gradle wrapper --gradle-version 9.7
从那时起,对以下每个命令都使用 ./gradlew 而不是 gradle。
使用 JDK 25 构建,而不仅仅是“任何最近的 LTS”——Paper 26.2 的 dev bundle
本身就需要 25+ 运行时来编译对抗(build.gradle 中的
options.release/sourceCompatibility 已经设置为 25 以匹配;
不要降低它们而不也降低 minecraft_version,否则你会遇到
“依赖解析正在寻找与 JVM 运行时版本 X 兼容的库,但 paper-api ... 仅与 ... 25 兼容”)。
-
在 gradle.properties 中设置你的确切目标版本 -
minecraft_version=26.2(或 26.1.2)会通过 .build.+ 解析为该版本的最新已发布
构建;一旦你选定了一个,将其固定到特定的构建(例如
26.2.build.102),这样后来的重建就不会静默跳转到更新版的 Paper 构建。
-
构建。 ./gradlew shadowJar - 需要网络访问,因为它第一次会从 Paper 的 Maven 拉取 minecraft_version 的 paperweight dev bundle。输出:build/libs/farlandsorigin-<mod_version>.jar。
没有单独的“reobf”步骤——Paper 26.1+ 提供完全未混淆的
(Mojang 映射一直到底层),所以这个 jar 就是
服务器运行的内容;没有什么需要重新映射的。
-
将该 jar 放入 Folia(或 Paper)服务器的 plugins/ 目录中。
-
添加 java agent 标志。 在你的启动脚本中,在 -jar paper.jar 之前(对 Folia 的 jar 同样有效):
java -javaagent:plugins/farlandsorigin-<mod_version>.jar <your normal flags> -jar folia-<version>.jar nogui
这是可选的,不能从插件内部设置——agents 是一个 JVM 级别的概念,在进程启动时固定,在任何插件代码运行之前。
-
启动服务器。 截至此版本,配套的数据包会自动生成和安装——FarlandsOriginBootstrap 直接从 classpath 读取你服务器自己的 vanilla noise_settings.json 文件(就像它已经读取真实的 NMS 类一样),并在扫描该文件夹之前将数据包写入 <level-name>/datapacks/farlandsorigin/,所以对于常见情况,不需要手动查找 jar 或运行脚本。检查日志是否包含:
Wrote Far Lands override for overworld.(以及 amplified,
large_biomes)
FarlandsOrigin datapack auto-installed at ...
如果你没看到这些日志——例如你的服务器使用了非默认的 plugins
文件夹位置,导致安装程序的服务器根目录猜测错误——请改用手动路径:
python3 farlandsorigin/tools/build_datapack.py path/to/your/server.jar farlandsorigin
cp datapack/farlandsorigin/data/farlandsorigin/worldgen/density_function/old_overworld_noise.json \
farlandsorigin/data/farlandsorigin/worldgen/density_function/
cp -r farlandsorigin <world-folder>/datapacks/
(脚本也能自动检测 Mojang 的 bundler-jar 格式,因此你指向的任何服务器
jar 文件——启动器存根、原始 Mojang jar、已解压的 jar——均可正常工作)
无论是自动还是手动模式,这都必须在世界首次创建/加载之前完成——Far Lands 的世界生成注册表在服务器启动时固化一次,不会回溯应用到之前生成的区块,这与原版模组存在相同的限制。
-
检查日志其余部分是否包含以下内容:
Registered farlandsorigin:radius_check density function type.
[FarlandsOrigin] BlendedNoise.compute: patched 2 call site(s).
[FarlandsOrigin] PerlinNoise.wrap: patched to identity function.
FarlandsOrigin agent attached; Far Lands generation active at distance ...
如果缺少上述任何一项或显示修补站点数为 0,则 Far Lands 生成未激活——请参阅故障排除。
配置
plugins/FarlandsOrigin/config.yml:
distance: 12550824
与 Fabric 模组的配置具有相同的选项和算术逻辑。
Folia 注意事项
此移植版不涉及按区域调度,因此无需专门针对 Folia 的线程化区域模型进行移植——世界生成密度函数会在生成特定区域的任意线程上运行,无论使用的是 Folia 还是 Paper,且此插件的代码均未触及 Bukkit 的单线程 API(无实体、无方块更新、无调度)。在 Folia 上唯一需要双重检查的是 PluginBootstrap 相对于注册表冻结的时间点是否与 Paper 上一致(Folia 是 Paper 的分叉版本,因此理应一致,但请在你的 Folia 构建版本中进行验证)。
已知限制 / 在生产环境信任此插件前需验证的内容
本代码是在无法编译或在真实 Paper/Folia 26.1/26.2 服务器上运行的情况下编写和审查的(生产环境缺乏网络访问权限及 NMS jar 包)。具体未验证项如下:
NmsRegistryUnfreezer.FROZEN_FIELD = "frozen" —— vanilla 的 MappedRegistry 中用于保存其冻结状态的字段的名称。如果在启动时抛出 NoSuchFieldException,请检查你版本中的 MappedRegistry(例如通过反编译器查看 Paper/NMS jar),并更新该常量。
BlendedNoiseTransformer/PerlinNoiseTransformer 的目标签名 —— 基于你自己的 Fabric 模组 mixins 已经定位的方法/类名构建(BlendedNoise.compute、PerlinNoise.wrap、FunctionContext.blockX/blockZ`),这些是 Mojang 的官方映射名称,应原样保留到 Paper 的 mojmap 运行时中。两个转换器都在启动时记录了它们修补了多少个调用站点,以便不匹配的情况能够被明显察觉而非静默失败——如果你看到“found 0 ... to patch”的警告,请反编译你版本中的实际类并进行调整。
build_datapack.py / FarlandsOriginDatapackInstaller 对 final_density 的引用与内联检测 —— 基于你的模组自己的 old_overworld_noise.json 中已可见的模式(通过 ID 引用同级条目,如 minecraft:overworld/sloped_cheese),因此 final_density 在现代 vanilla 数据中很可能也是一个纯字符串引用——但两者也处理了内联对象的情况以防万一。
FarlandsOriginDatapackInstaller 的服务器根目录检测 —— 使用服务器进程的工作目录(Path.of("").toAbsolutePath()),这是正常启动的服务器(从服务器文件夹内运行 java -jar ... folia.jar)中 server.properties/world//plugins/ 所在的路径。此代码的早期版本尝试从 context.getDataDirectory() 推导该路径,但在真实服务器上抛出了 NullPointerException——该路径实际上是相对的,而非绝对的,因此向上回溯两级父目录会超出根目录范围。如果你使用的工作目录并非实际的服务器文件夹启动服务器(这种情况较少见,但某些包装脚本/进程管理器可能如此),此检测仍会出错——症状与之前相同(出现“Wrote Far Lands override...”日志但生成并未实际更改),修复方法也相同(回退到手动脚本,该脚本通过直接获取世界的数据包路径来规避此问题)。
pack.mcmeta 中的 pack_format —— 如果存在,则从类路径上的 version.json(对于手动脚本则是服务器 jar 中)自动检测;如果生成因 pack-format 警告/错误而拒绝加载,请对照服务器的实际 vanilla 数据包进行验证。
- Java agent 的自足性 ——
Launch-Agent-Class/Premain-Class 均在清单中设置,因此无论通过 -javaagent: 附加(推荐,上文所用)还是在运行时自我附加(如果你偶尔需要的话),同一个 jar 都能工作;此处仅仔细推演过 -javaagent: 这一路径。
以上都不是“肯定无法工作”的问题——它们是依赖此插件前应在真实测试服务器上检查的具体、可证伪的事项,列出而非一笔带过。
在真实服务器测试期间修复的问题(保留此处作为记录)
已在实时 Folia 26.1.2 服务器上确认:
- ASM 完全无法解析 JDK 25 的类文件(
Unsupported class file major version 69)—— ASM 在 9.8 版本中才添加了对 Java 25 的支持;更早的版本会直接失败。已锁定 asm_version=9.8。
ClassWriter 默认的 getCommonSuperClass 无法识别 NMS 类型 —— 它默认通过代理自身的类加载器进行解析,而该加载器对 Folia 的服务端类没有可见性。通过使用 TargetLoaderClassWriter 修复,该类针对实际加载正在转换类的类加载器进行解析。
- 从
BlendedNoise 到独立辅助类的普通 invokestatic 调用因 NoClassDefFoundError 失败 —— JVM 使用 BlendedNoise 自身的定义类加载器来解析该符号引用,而 Paperclip/Folia 的加载器在其搜索路径上并未包含此插件的 jar 包。通过让 BlendedNoiseTransformer 将辅助类的编译字段和方法字节码直接复制到 BlendedNoise 本身来修复(参见该类的 Javadoc),从而避免在运行时进行跨类加载器的解析。出于相同原因,配置也通过 JVM 系统属性(farlandsorigin.coordinateDistance / farlandsorigin.baseDistance)而非共享类的静态字段跨越同一边界。
FarlandsOrigin
Farlands for Paper/Folia servers
Port of ThePotatoArchivist's ClassicFarlands
(MIT licensed - read LICENSE file) from Fabric to Paper/Folia,
targeting Minecraft 26.1 / 26.2.
WARNING: Made with AI (cuz idk how to use Java) - PLEASE SUPPORT THE ORIGINAL DEVELOPER
I am a random dev, and you should really not trust random stuff you find on the Internet. Take a look at the source code which is only a few hundred lines long. (click on the GitHub "view source" link on the side). And if you prefer, compile the project yourself with mvn clean package (requires Java JDK 21+ and Maven installed).
Read this whole file before deploying. This is not a routine "recompile
against a different API" port. Fabric gives mods three things Paper's plugin
API does not: an init hook that runs before Mojang's registries freeze,
Mixin bytecode injection into internal worldgen classes, and generic
JSON-patching of datapack files at load time. Everything below exists to
replace those three things without either of them.
What changed vs. the Fabric mod, and why
| Fabric mod piece |
Paper port |
Why |
Registry.register(BuiltInRegistries.DENSITY_FUNCTION_TYPE, ...) in onInitialize |
FarlandsOriginBootstrap (a PluginBootstrap) + NmsRegistryUnfreezer, reflection |
Paper plugins load after BuiltInRegistries is already frozen; there's no Paper API for this registry at all (checked against the current RegistryEvents javadocs - it only covers enchantments/entity variants/dialogs/etc., not worldgen). |
RadiusCheck.java |
Ported verbatim |
Plain vanilla DensityFunction code, nothing Fabric-specific. |
BlendedNoiseMixin / PerlinNoiseMixin (SpongePowered Mixin) |
FarlandsOriginAgent + BlendedNoiseTransformer / PerlinNoiseTransformer (raw ASM via a java.lang.instrument agent) |
Modern SpongePowered Mixin (the version mixinextras/@ModifyExpressionValue needs) has no supported standalone mode outside a mod loader - it's built around an IMixinService tied to a specific launch platform. Rather than ship an unverifiable Mixin bootstrap sequence, I did the same two bytecode edits directly with ASM, which is fully standalone-capable. |
Mixson (generic runtime JSON patching of noise_settings) |
FarlandsOriginDatapackInstaller (auto, at bootstrap) / tools/build_datapack.py (manual fallback) + companion datapack |
No equivalent exists outside Fabric's resource-reload events. Datapacks can only override a whole registry file, not patch one field - so instead of guessing at vanilla's noise_settings.json content for a Minecraft version I have no way to verify from here, this reads it from the running server's own classpath (or, manually, your server jar) and patches only final_density, the same way Mixson did, just at install time instead of every load. |
Quilt Config (FarlandsOriginConfig) |
FarlandsOriginState + config.yml |
Kaleido/Quilt Config isn't available on Paper; swapped for a plain Bukkit config. Same distance option, same arithmetic. |
Install
-
Generate a Gradle wrapper first, if you don't have one. Use Gradle
9.1.0 or newer - Gradle only added support for running on JDK 25 in
9.1.0 (older Gradle, including the whole 8.x line, fails with
"Unsupported class file major version 69" on a JDK 25 system):
cd farlandsorigin
gradle wrapper --gradle-version 9.7
From then on use ./gradlew instead of gradle for every command below.
Build with JDK 25, not just "any recent LTS" - Paper 26.2's dev bundle
itself requires a 25+ runtime to compile against (build.gradle's
options.release/sourceCompatibility are already set to 25 to match;
don't lower them without also lowering minecraft_version, or you'll hit
"Dependency resolution is looking for a library compatible with JVM
runtime version X, but paper-api ... is only compatible with ... 25").
-
Set your exact target version in gradle.properties -
minecraft_version=26.2 (or 26.1.2) resolves to the latest published
build for that version via .build.+; pin it to a specific build (e.g.
26.2.build.102) once you've picked one, so a later rebuild doesn't
silently jump to a newer Paper build underneath you.
-
Build. ./gradlew shadowJar - needs network access, since it pulls
the paperweight dev bundle for minecraft_version from Paper's Maven the
first time. Output: build/libs/farlandsorigin-<mod_version>.jar.
No separate "reobf" step - Paper 26.1+ ships fully unobfuscated
(Mojang mappings all the way down), so this jar already is what the
server runs; there's nothing to remap.
-
Drop that jar in plugins/ on your Folia (or Paper) server.
-
Add the java agent flag. In your start script, before -jar paper.jar (works identically for Folia's jar):
java -javaagent:plugins/farlandsorigin-<mod_version>.jar <your normal flags> -jar folia-<version>.jar nogui
This is not optional and can't be set from inside the plugin - agents are
a JVM-level concept, fixed at process launch, before any plugin code runs.
-
Start the server. As of this version, the companion datapack is
generated and installed automatically - FarlandsOriginBootstrap reads
your server's own vanilla noise_settings.json files straight off the
classpath (the same way it already reads real NMS classes) and writes
the datapack into <level-name>/datapacks/farlandsorigin/
before that folder gets scanned, so there's no manual jar-hunting or
script-running step needed for the common case. Check the log for:
Wrote Far Lands override for overworld. (and amplified,
large_biomes)
FarlandsOrigin datapack auto-installed at ...
If you don't see those - e.g. your server uses a non-default plugins
folder location, so the installer's server-root guess is wrong - fall
back to the manual path instead:
python3 farlandsorigin/tools/build_datapack.py path/to/your/server.jar farlandsorigin
cp datapack/farlandsorigin/data/farlandsorigin/worldgen/density_function/old_overworld_noise.json \
farlandsorigin/data/farlandsorigin/worldgen/density_function/
cp -r farlandsorigin <world-folder>/datapacks/
(the script auto-detects Mojang's bundler-jar format too, so any server
jar you point it at - launcher stub, raw Mojang jar, already-extracted
one - works)
Either way (auto or manual), this has to be in place before a world is
first created/loaded - Far Lands worldgen registries are baked once at
server boot and won't retroactively apply to chunks generated earlier,
same limitation the original mod has.
-
Check the rest of the log for:
Registered farlandsorigin:radius_check density function type.
[FarlandsOrigin] BlendedNoise.compute: patched 2 call site(s).
[FarlandsOrigin] PerlinNoise.wrap: patched to identity function.
FarlandsOrigin agent attached; Far Lands generation active at distance ...
If any of these are missing or show 0 patched sites, Far Lands generation
is not active - see Troubleshooting.
Configuration
plugins/FarlandsOrigin/config.yml:
distance: 12550824
Same option and arithmetic as the Fabric mod's config.
Folia notes
Nothing in this port does per-region scheduling, so there was nothing to
port to Folia's threaded-regions model specifically - worldgen density
functions run on whichever thread is generating a given region regardless of
Folia vs. Paper, and none of this plugin's code touches Bukkit's
single-threaded APIs (no entities, no block updates, no scheduling). The one
thing to double check on Folia specifically is that PluginBootstrap timing
relative to registry freezing is the same as on Paper (Folia is a Paper
fork, so it should be, but verify on your Folia build).
Known limitations / what to verify before trusting this in production
This was written and reviewed without the ability to compile or run it
against a real Paper/Folia 26.1/26.2 server (no network or NMS jars
available in the environment that produced it). Specifically unverified:
NmsRegistryUnfreezer.FROZEN_FIELD = "frozen" - the field name inside
vanilla's MappedRegistry holding its frozen state. If this throws
NoSuchFieldException at boot, inspect MappedRegistry in your version
(e.g. via a decompiler on the Paper/NMS jar) and update the constant.
BlendedNoiseTransformer/PerlinNoiseTransformer target signatures -
built from the method/class names your own Fabric mod's mixins already
target (BlendedNoise.compute, PerlinNoise.wrap, FunctionContext.blockX/ blockZ), which are Mojang's official mapped names and should carry over
identically to Paper's mojmap runtime. Both transformers log how many call
sites they patched at startup specifically so a mismatch is loud, not
silent - if you see the "found 0 ... to patch" warnings, decompile the
actual class in your version and adjust.
build_datapack.py / FarlandsOriginDatapackInstaller's reference-vs-inline
detection for final_density - based on the pattern already visible in
your mod's own old_overworld_noise.json (which references sibling
entries like minecraft:overworld/sloped_cheese by ID), so final_density
is very likely also a plain string reference in modern vanilla data - but
both handle the inline-object case too, just in case.
FarlandsOriginDatapackInstaller's server-root detection - uses the
server process's working directory (Path.of("").toAbsolutePath()),
which is where server.properties/world//plugins/ all live relative
to for a normally-launched server (java -jar ... folia.jar run from
inside the server folder). An earlier version of this tried to derive it
from context.getDataDirectory() instead and threw a
NullPointerException on a real server - that path turned out to be
relative, not absolute, so walking up two parents overshot past the root.
If you launch the server with a working directory that ISN'T the actual
server folder (unusual, but possible with some wrapper scripts/process
managers), this will still get it wrong - same symptom as before ("Wrote
Far Lands override..." logs appearing but generation not actually
changing) and same fix (fall back to the manual script, which sidesteps
this by taking the world's datapacks path from you directly).
pack_format in pack.mcmeta - auto-detected from version.json on
the classpath (or in the server jar, for the manual script) if present;
verify against your server's actual vanilla datapack if generation
refuses to load with a pack-format warning/error.
- Java agent self-sufficiency -
Launch-Agent-Class/Premain-Class are
both set in the manifest so the same jar works whether attached via
-javaagent: (recommended, used above) or (if you ever need it) a
self-attach at runtime; only the -javaagent: path has been reasoned
through carefully here.
None of these are "this definitely won't work" - they're the concrete,
falsifiable things to check on a real test server before relying on this,
listed instead of glossed over.
Fixed during real-server testing (kept here as a record)
Confirmed against a live Folia 26.1.2 server:
- ASM couldn't parse JDK 25 class files at all (
Unsupported class file major version 69) - ASM added Java 25 support in 9.8; anything earlier
fails outright. Pinned to asm_version=9.8.
ClassWriter's default getCommonSuperClass can't see NMS types -
it resolves via the agent's own classloader by default, which has no
visibility into Folia's server classes. Fixed with
TargetLoaderClassWriter, which resolves against the classloader that's
actually loading the class being transformed.
- A plain
invokestatic from BlendedNoise to a separate helper class
failed with NoClassDefFoundError - the JVM resolves that symbolic
reference using BlendedNoise's own defining classloader, and
Paperclip/Folia's loader doesn't have this plugin's jar on its search
path. Fixed by having BlendedNoiseTransformer copy the helper's
compiled field+method bytecode directly onto BlendedNoise itself
(see that class's Javadoc), so nothing needs cross-classloader
resolution at runtime. Configuration crosses the same boundary via JVM
system properties (farlandsorigin.coordinateDistance /
farlandsorigin.baseDistance) rather than a shared class's static
fields, for the same reason.
评论 0
登录后参与评分
还没有评论,来抢沙发吧