FoliaForAll
无需修改源码,即可在 Folia 上运行你的 Paper 插件。
Folia 会拒绝任何未明确声明 folia-supported: true 的插件,并将标准的 BukkitScheduler 替换为一个存根(stub),该存根在每次调用时都会抛出 UnsupportedOperationException。FoliaForAll 移除了这两道障碍,使得绝大多数传统的 Bukkit/Paper 插件能够开箱即用。
工作原理
FoliaForAll 同时作为 Java agent 和 插件 提供,二者协同工作。
Java agent
- 修补
PluginDescriptionFile.isFoliaSupported() 使其始终返回 true,从而绕过 Folia 对所有已安装插件的加载时兼容性检查
- 修补
CraftServer.waitForAsyncTasksShutdown() 以避免因调度器类型不兼容而在服务器停止时导致的崩溃
插件
- 在服务器启动时将一个
BukkitScheduler 兼容性适配器注入到服务器中,将调用路由至 Folia 的原生调度器 API
该调度器适配器映射了完整的 BukkitScheduler API 表面:
- 同步任务 →
GlobalRegionScheduler(最接近 Paper 主线程的非世界操作等效项)
- 异步任务 →
AsyncScheduler
- 延迟和周期从刻(ticks)转换为毫秒(1 tick = 50 ms)
安装
- 将最新的
FoliaForAll-x.x.x.jar 放入你的 plugins/ 文件夹。
- 在你的服务器启动命令中添加 Java agent:
java -javaagent:plugins/FoliaForAll-x.x.x.jar -jar server.jar
这两个步骤都是必需的。如果没有 -javaagent 标志,那些未声明 folia-supported: true 的插件仍会在兼容性层提供帮助之前被 Folia 拒绝。
局限性
- 同步任务在全局区域线程上运行,而非特定的区块区域。读取或写入特定区块方块/实体数据的插件仍可能会遇到线程安全问题。请使用 Folia 原生的
RegionScheduler 或 EntityScheduler API 进行正确的区域感知调度。
- 任务 ID 是内部生成的,不与 Folia 自身的任务跟踪共享。
- 这是一个尽力而为的兼容性适配层。对 Paper 单线程模型有深层假设的插件在 Folia 的区域化架构下仍可能出现异常行为。
要求
- Folia 或其分支 1.20.4 或更高版本
- Java 21+
免责声明
FoliaForAll 按“原样”提供,不提供任何功能性的保证或担保。虽然它旨在改善传统 Bukkit/Paper 插件与 Folia 及其分支之间的兼容性,但我们并不保证任何特定插件都能正常工作。由不兼容插件引起的插件崩溃、数据损坏或意外行为均由服务器操作员负责。使用风险自负。
FoliaForAll
Run your Paper plugins on Folia - no source changes required.
Folia rejects any plugin that doesn't explicitly declare folia-supported: true, and replaces the standard BukkitScheduler with a stub that throws UnsupportedOperationException on every call. FoliaForAll removes both of these barriers so that the vast majority of legacy Bukkit/Paper plugins work out of the box.
How it works
FoliaForAll ships as both a Java agent and a plugin that work together.
Java agent
- Patches
PluginDescriptionFile.isFoliaSupported() to always return true, bypassing Folia's load-time compatibility check for every installed plugin
- Patches
CraftServer.waitForAsyncTasksShutdown() to avoid a crash on server stop caused by scheduler type incompatibility
Plugin
- Injects a
BukkitScheduler compatibility adapter into the server at startup, routing calls to Folia's native scheduler APIs
The scheduler adapter maps the full BukkitScheduler API surface:
- Sync tasks →
GlobalRegionScheduler (closest equivalent to Paper's main thread for non-world operations)
- Async tasks →
AsyncScheduler
- Delays and periods are converted from ticks to milliseconds (1 tick = 50 ms)
Installation
- Drop latest
FoliaForAll-x.x.x.jar into your plugins/ folder.
- Add the Java agent to your server start command:
java -javaagent:plugins/FoliaForAll-x.x.x.jar -jar server.jar
Both steps are required. Without the -javaagent flag, plugins that don't declare folia-supported: true will still be rejected by Folia before the compatibility layer can help them.
Limitations
- Sync tasks run on the global region thread, not a specific chunk region. Plugins that read or write block/entity data for a particular chunk may still encounter thread-safety errors. Use Folia's native
RegionScheduler or EntityScheduler APIs for correct region-aware scheduling.
- Task IDs are generated internally and are not shared with Folia's own task tracking.
- This is a best-effort compatibility shim. Plugins with deep assumptions about Paper's single-threaded model may still misbehave on Folia's regionized architecture.
Requirements
- Folia or a fork 1.20.4 or newer
- Java 21+
Disclaimer
FoliaForAll is provided as-is, without any warranty or guarantee of functionality. While it aims to improve compatibility between legacy Bukkit/Paper plugins and Folia and its forks, we make no guarantees that any specific plugin will work correctly. Plugin crashes, data corruption, or unexpected behaviour caused by incompatible plugins remain the responsibility of the server operator. Use at your own risk.
评论 0
登录后参与评分
还没有评论,来抢沙发吧