Folia Plugin Compatibility: What to Require Before a Port
Before moving a community to Folia, require an explicit compatibility statement for every essential plugin, a review of your custom code and a rehearsal of the complete player workflow. A plugin loading successfully is only the first gate. Do not change its compatibility declaration yourself to force it to load.
This is a commissioning checklist for operators considering Folia or asking a developer to port an existing plugin. It does not certify any plugin, recommend a particular server build or promise a higher player capacity. The outcome should be a documented decision: proceed with a tested scope, fund the missing work, or retain the current platform.
First establish why Folia fits the project
Folia distributes ticking across independent regions. The official Folia overview explains that regions advance independently; it is not simply a switch that makes every existing operation parallel. Ask what workload you want to improve before changing the software.
The Folia FAQ identifies communities with naturally dispersed players as stronger candidates. A busy shared spawn and a dispersed survival session should therefore be separate evaluation scenarios. That is a planning inference, not a benchmark. The FAQ also lists disabled commands: check those used by your actual event scripts and administration procedures against the target release.
Write a short problem statement: where players experience delays, when they happen, which mechanics run there and what evidence you have collected. If the only justification is “more cores should mean more players”, the proposal is not ready for a migration quote. Keep architecture evaluation separate from a promise that one custom plugin can be ported cheaply.
Build a compatibility register before requesting a port
List the exact Minecraft version, Folia build, Java runtime and plugin artifacts proposed for the rehearsal. For each plugin, record its essential features, dependencies, maintainer's support statement and the person responsible for resolving gaps. Include shared libraries and integrations that are easy to overlook because players do not invoke them directly.
Use four statuses: confirmed for the stated version, requires development, unsupported, and unknown. An unanswered support question stays unknown. A statement about a different release does not automatically confirm yours. Ask for the relevant release notes or project documentation, rather than relying on an old compatibility list.
Identify a blocker before spending time testing optional features. For example, if the community cannot operate without its claims system, unresolved support there prevents a production decision even if the chat plugin works. The general plugin acceptance guide helps define the delivery contract; this register adds the specific Folia dependency gate.
Ask the developer to explain ownership and shared state
Paper's Folia support guide warns that folia-supported: true does not implement compatibility. It distinguishes region scheduling for locations, entity scheduling that follows an entity, and asynchronous work. Request a code review of the relevant execution paths, not merely an edited descriptor.
For the review, supply a feature inventory in ordinary operational language: delayed rewards, teleports, block changes, scheduled resets and shared team scores. Ask the developer to map each feature to its execution context and explain what happens if its target disappears before completion. You do not need to approve individual Java statements; you need a clear account of responsibility and failure handling.
Folia's project documentation also distinguishes server-owned data from data owned by the plugin. Correct scheduling alone does not settle concurrent access to the plugin's shared state. Ask how two players requesting the last available event place are handled and where the authoritative reservation lives.
Rehearse one feature across the difficult transitions
Consider an illustrative custom event plugin that reserves a place, teleports the player and records attendance. Agree what “accepted” means before testing. A reservation might remain pending until arrival is confirmed; alternatively, a failed transfer might cancel it. Those are product decisions that the developer must make explicit.
Use an isolated environment with copied test data and external integrations redirected to test endpoints. Follow the backup restore rehearsal for isolation and recovery preparation. Never let the rehearsal send real rewards or modify the live event database.
| Proposed scenario | Evidence required for acceptance |
|---|---|
| Two players request the final place from separate areas | One reservation; a clear result for the other player |
| Player moves while a delayed action is pending | The action affects the intended player or is cancelled as agreed |
| Player disconnects during admission | Reservation and attendance have an explained final state |
| Teleport or dependency request fails | No false arrival confirmation; a documented recovery action |
| The process restarts with pending admissions | Stored state is reconciled without duplicate attendance |
These are proposed checks, not results from a test we ran. Have the developer confirm that the selected setup actually exercises different regions where required; distance alone is not your acceptance evidence. Repeat failures deliberately in the test environment and keep request identifiers, relevant logs and the observed player outcome together.
Separate correctness from capacity
A correct feature can still be too slow for the intended opening. Agree a representative workload, machine, configuration, test duration and acceptance limits before comparing implementations. Record both dispersed activity and the gathering that matters to the community. Report the measurement method and its blind spots alongside the figures.
Do not translate a successful rehearsal into an unlimited player claim. A test with only the custom plugin does not establish the behavior of the full production stack. Conversely, a concurrency defect is a release blocker even when average response times appear acceptable. Preserve the exact artifacts and configuration so a later build can be assessed against the same scenario.
Make the deployment decision reviewable
Require the compatibility register, review findings, completed scenario table, unresolved limitations and recovery procedure in the handover. Assign who can approve opening and who handles a failed deployment. If an essential dependency remains unknown, postpone the switch or explicitly redesign the feature; do not silently remove it on launch day.
For custom Minecraft development, bring the existing plugin, dependency list, target environment and player journeys you need to preserve. Mineando scopes paid projects individually. Compatibility work, maintenance for future releases and support responsibilities need an explicit agreement; a Folia label alone is not that agreement.
