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):

1. Put UniversalFolia-x.x.jar into your plugins/ folder
2. Add this line to your JVM arguments (e.g. user_jvm_args.txt):

   -javaagent:plugins/UniversalFolia-x.x.jar
   

3. 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