Architecture
SilkMC keeps Folia's regional multithreading model as the core execution architecture. The SilkMC additions sit on top of that model as small, reviewable patches — a compatibility classifier, a scheduler bridge, a teleport bridge, and a plugin lifecycle wrapper.
Design goals
- Preserve upstream region ownership semantics.
- Improve plugin survivability around legacy assumptions.
- Keep upstream merges clean and understandable.
- Avoid compatibility hacks that compromise world correctness.
Execution model
- Nearby loaded chunks are grouped into ticking regions.
- Each region ticks independently on a scheduler-managed worker.
- Global tasks remain explicit instead of pretending there is a single main thread.
- Cross-region operations should bridge intentionally and fail loudly when unsafe.
SilkMC additions
gg.tame.silkmc.server.compat.SilkPluginCompatibility — warn vs strict mode for unmarked plugins, plus operator-friendly classification.
SilkSchedulerBridge routes legacy BukkitScheduler.runTask* calls to the Global Region Scheduler so they do not throw.
Legacy sync Entity.teleport() and Player.teleport() route to teleportAsync when safe.
beginLifecycle / endLifecycle thread-local context lets failures be classified with a phase like startup or async scheduler task.
Configurable compatibility modes via silkmc-compatibility.yml, plus per-plugin overrides and the /silkmc command.
Benchmarking helpers, smoke-test CI, and a curated plugin pack used to validate compatibility before tagging.
Testing →Component map
+----------------------------------------------------------+
| SilkMC Server |
| |
| +--------------------+ +---------------------------+ |
| | Plugin Manager |-->| SilkPluginCompatibility | |
| +--------------------+ | - policy (yml-backed) | |
| | | - lifecycle context | |
| | | - failure classifier | |
| v +---------------------------+ |
| +--------------------+ ^ |
| | CraftScheduler |--------------+ |
| | (legacy sync API) | |
| +--------------------+ |
| | |
| v |
| +--------------------+ +---------------------------+ |
| | SilkSchedulerBridge|-->| Global Region Scheduler | |
| +--------------------+ +---------------------------+ |
| |
| +--------------------+ +---------------------------+ |
| | CraftEntity |-->| teleportAsync | |
| | / CraftPlayer | | (region-aware teleport) | |
| +--------------------+ +---------------------------+ |
| |
| +--------------------+ +---------------------------+ |
| | Region Threading |-->| Per-region ticking worker | |
| | (upstream Folia) | +---------------------------+ |
| +--------------------+ |
+----------------------------------------------------------+Where the patches live
silkmc-server/paper-patches/features/— server-side compatibility and branding patches.silkmc-server/minecraft-patches/features/— server-side Minecraft-level region threading patches.silkmc-api/paper-patches/features/— API-side compatibility metadata and additions.silkmc-server/paper-patches/files/— new files added by SilkMC (e.g.SilkPluginCompatibility.java).
Where new compatibility shims should go
Add new shims in gg.tame.silkmc.server.compat (or a sibling package) and integrate them through small,
reviewable patches against paper-server. SilkMC favors additive compatibility layers over broad
rewrites of upstream code.