How it works

⚙️ How It Works

Folia Phantom uses advanced bytecode manipulation to ensure compatibility between standard Bukkit APIs and Folia's multi-threaded environment.

🧠 Core Engine: ASM Transformation

We use the ASM Library to read, analyze, and rewrite .class files inside plugin JARs.

1. Fast-Fail Scanning

Before applying heavy transformations, the engine performs a "Fast Scan" using ScanningClassVisitor. It looks for keywords like BukkitScheduler, BukkitRunnable, and setType. If none are found, the class is skipped, drastically increasing patching speed.

2. Redirection Strategy

The engine intercepts method calls and redirects them to a "Bridge" class (FoliaPatcher) that is automatically bundled into the resulting JAR.

Example: Scheduler Redirection

• Original Code: Bukkit.getScheduler().runTask(plugin, runnable);
• Patched Code: FoliaPatcher.runTask(null, plugin, runnable);

The FoliaPatcher then determines whether to use:

• RegionScheduler (if a location context is found)
• GlobalRegionScheduler (for global tasks)
• AsyncScheduler (for async tasks)

3. Thread Safety Enforcement

Certain methods like Block.setType are inherently thread-unsafe in Folia if called from the wrong thread. Folia Phantom automatically wraps these calls to ensure they execute on the correct Folia tick/region thread.

📦 JAR Post-Processing

In addition to bytecode transformation, Folia Phantom performs:

• plugin.yml Update: Automatically adds folia-supported: true.
• Signature Removal: Deletes META-INF/*.SF, DSA, and RSA files to avoid security exceptions after modification.
• Runtime Injection: Bundles the FoliaPatcher classes so the patched plugin can run on any Folia server without external dependencies.

---

🏠 Back to Home