UniversalFolia
无需修改代码,即可在 Folia 上运行 Paper / Bukkit / Spigot 插件。
由 Matelex 制作
它是什么?
Folia 拒绝加载传统插件并移除了旧版调度器。UniversalFolia 通过嵌入的 Java Agent 弥补了这两方面的空白:
- 加载任何插件 — 修补插件描述检查,使 Folia 接受未声明
folia-supported: true 的插件
- 完整的调度器兼容性 — 重写
Bukkit.getScheduler()、BukkitRunnable 以及所有基于遗留任务的方法,底层依托于 Folia 的原生调度器(同步任务在全局区域 Global Region 运行,异步任务在 AsyncScheduler 上运行)
- 安全的传送 — 同步的
Entity.teleport() 调用会自动回退至 teleportAsync()
- 智能救援系统 — 启动期间被跳过的插件会在启动过程中按依赖关系(
depend、softdepend、loadbefore:Vault 优先于 Essentials 加载)立即恢复,并对延迟失败进行自动重试
- 零配置 — 单个 jar 文件同时充当插件和 Agent;内置动态自附加及外部进程回退机制
- 彩色且结构化的启动日志,带有清晰的
[OK] / [!!] / [XX] 标记
安装
推荐方式(Agent 优先加载):
- 将
UniversalFolia-x.x.jar 放入你的 plugins/ 文件夹
- 在你的 JVM 参数中添加这一行(例如在
user_jvm_args.txt 中):
-javaagent:plugins/UniversalFolia-x.x.jar
- 启动服务器
简易模式: 只需将 jar 放入 plugins/ 即可。插件会将 Agent 附加到其自身进程,并自动救援所有被跳过的插件。
命令
| 命令 |
描述 |
/universalfolia status |
查看 Agent 状态、模式、已转换的类、已加载的插件 |
/universalfolia rescue |
手动重试加载被跳过的插件 |
权限:universalfolia.admin(默认:OP)
配置
console-colors: true # 控制台日志中的 ANSI 颜色
auto-attach: true # 缺少 -javaagent 时动态附加
rescue:
enabled: true # 恢复启动时被跳过的插件
instant: true # 在 PlaceholderAPI 注册扩展之前运行
delay-ticks: 20 # 当 instant=false 时用于自动重试的时间间隔
兼容性
- 服务器: Folia 1.21.x 及更高版本(基于 Folia 1.21.4 构建并测试)
- Java: 21+(已在 Java 25 上测试)
- 也可安全地在 Paper 1.21.x 上运行(此时桥接层仅作为无操作的调度器层存在)
已知限制
UniversalFolia 仅翻译 API;它无法改变 Folia 的架构:
- 运行时创建世界受限于 Folia 本身(例如 Multiverse 的
/mv create):请预先生成世界并导入它们
- 在非所属区域读取方块的插件(地图渲染器、全局回滚等)仍受限
- 从异步上下文解析的占位符可能会读取过时的玩家/世界数据
所有基于事件或任务的系统(经济、权限、封禁、RTP、传送点等)均可通过桥接正常运行。
构建
gradle build
需要 JDK 21。输出路径:build/libs/UniversalFolia-<version>.jar
由 Matelex 制作
UniversalFolia
Run Paper / Bukkit / Spigot plugins on Folia — without touching their code.
Created by Matelex
What is it?
Folia refuses to load classic plugins and removed the old scheduler. UniversalFolia bridges both gaps with an embedded Java agent:
- Loads anything — patches the plugin-description checks so Folia accepts plugins without
folia-supported: true
- Full scheduler compatibility — rewrites
Bukkit.getScheduler(), BukkitRunnable and every legacy task method on top of Folia's native schedulers (sync tasks run on the Global Region, async ones on the AsyncScheduler)
- Safe teleports — sync
Entity.teleport() calls automatically fall back to teleportAsync()
- Smart rescue system — plugins skipped during boot are recovered instantly during startup, ordered by dependencies (
depend, softdepend, loadbefore: Vault loads before Essentials), with automatic retries for late failures
- Zero setup — one single jar acts as both the plugin and the agent; dynamic self-attach with external-process fallback is built in
- Colored, structured startup logs with clear
[OK] / [!!] / [XX] markers
Installation
Recommended (agent loads first):
- Put
UniversalFolia-x.x.jar into your plugins/ folder
- Add this line to your JVM arguments (e.g.
user_jvm_args.txt):
-javaagent:plugins/UniversalFolia-x.x.jar
- Start the server
Easy mode: just drop the jar in plugins/. The plugin attaches the agent to its own process and rescues every skipped plugin automatically.
Commands
| Command |
Description |
/universalfolia status |
Agent state, mode, transformed classes, loaded plugins |
/universalfolia rescue |
Manually retry loading skipped plugins |
Permission: universalfolia.admin (default: OP)
Configuration
console-colors: true # ANSI colors in console logs
auto-attach: true # dynamic attach when -javaagent is missing
rescue:
enabled: true # recover plugins skipped at startup
instant: true # run before PlaceholderAPI registers expansions
delay-ticks: 20 # used if instant=false and for auto-retries
Compatibility
- Server: Folia 1.21.x and newer (built and tested on Folia 1.21.4)- Java: 21+ (tested up to Java 25)
- Also loads safely on Paper 1.21.x (the bridge simply becomes a no-op scheduler layer)
Known limitations
UniversalFolia translates the APIs; it cannot change Folia's architecture:
- Runtime world creation is blocked by Folia itself (e.g. Multiverse
/mv create): pre-generate worlds and import them instead
- Plugins reading blocks outside their region (map renderers, global rollbacks) stay limited
- Placeholders resolved from async contexts may read stale player/world data
Everything event-driven or task-based (economy, permissions, bans, RTP, warps...) works through the bridge.
Building
gradle build
Requires JDK 21. Output: build/libs/UniversalFolia-<version>.jar
Created by Matelex
评论 0
登录后参与评分
还没有评论,来抢沙发吧