repository·ver/26.2·Indexed 41 days ago
https://github.com/sparklypower/sparklypaperA high-performance Minecraft server software fork of Paper optimized for Survival servers with high player counts. It features Parallel World Ticking to distribute ticking loads across multiple threads, custom events like CraftItemRecipeEvent and PlayerPreMoveEvent, and specialized performance patches for high-concurrency environments.
When accessing NMS (net.minecraft.server) level methods setBlockEntity and getBlockEntity, you must be aware of the threading model to avoid server freezes.
getBlockEntity: Generally thread-safe, EXCEPT when accessed from a separate ServerLevelTickThread. Accessing it from a different world's tick thread will trigger a main-thread chunk load, causing the server to freeze.setBlockEntity: Requires strict thread checks.To ensure safety, the implementation uses ensureTickThreadOrAsyncThread for getBlockEntity and ensureTickThread for setBlockEntity. Developers should ensure that any custom logic interacting with block entities does not attempt to cross ServerLevelTickThread boundaries for different worlds.
SparklyPaper is a fork specifically made for SparklyPower. Users should be aware of the following:
Parallel World Ticking is an experimental feature in SparklyPaper that moves world ticking into separate threads, allowing multiple worlds to be ticked in parallel.
Key Characteristics:
ServerLevelTickThread bound to a specific world, or the main TickThread, can modify that world's data.SparklyPaper is tailor-made for the SparklyPower Survival server and is not intended to be a general-purpose stable public fork (unlike Purpur or Pufferfish).
Key considerations before using SparklyPaper:
SparklyPaper builds are provided via GitHub Actions. To download a build:
sparklypaper-server/src/main/.https://github.com/SparklyPower/SparklyPaper/actions/workflows/build.ymlIn a parallel world environment, teleporting a player and immediately opening a BlockEntity inventory (e.g., a chest) can cause the server to lock up. This happens because the inventory opening process may attempt to load chunks from the old world while the player is being ticked in the new world, leading to a deadlock.
To prevent this, the system implements two safeguards:
openMenu ignores requests until the player hasTickedAtLeastOnceInNewWorld.BaseContainerBlockEntity#canUnlock rejects containers attempted to be opened after a world switch.Workaround: If you are developing a plugin that teleports a player and then immediately opens an inventory, you must wait at least 1 tick before attempting to open the inventory to ensure the player has successfully transitioned to the new world.
// Avoid doing this immediately after teleportation:
@EventHandler
fun onInteract(e: PlayerInteractEvent) {
e.player.teleport(Location(Bukkit.getWorld("..."), 0.0, 0.0, 0.0))
// DO NOT open an inventory here immediately!
}
// Instead, wait at least 1 tick before opening the inventory.Because world data can only be modified by the thread bound to that specific world, plugins that attempt to modify other worlds from a different thread will fail.
Common Failure Scenario:
Teleporting players or entities to another world during events called on a ServerLevelTickThread will cause issues.
Workaround: To avoid thread-safety errors, schedule these API calls (like teleportation) to be run after all worlds have finished ticking (e.g., by scheduling a task on the main thread).
By default, Spark profiles the Server thread, which does not capture the activity of individual world tick threads. To profile the parallel worlds, you must configure Spark to dump all threads.
config.json, add the following setting:
"backgroundProfilerThreadDumper": "all"serverlevel-tick-worker [WorldNameHere]Note: Parallel execution is limited by a semaphore based on the parallel-world-ticking.threads value.
{
"backgroundProfilerThreadDumper": "all"
}If you are running a server on a downgraded Minecraft version, the server may throw errors when attempting to deserialize an ItemStack serialized on a newer version. You can bypass the item version check by setting the following system property:
-Dsparklypaper.ignoreItemDataVersion=true
-Dsparklypaper.ignoreItemDataVersion=truemapView.isLocked = true. This prevents hefty updates when a custom renderer is present. Note that while the map is locked, vanilla map data will not be updated.SparklyPaper may provide Spark Profile Results as compressed files using the zstd format. To analyze these results, you must first decompress the file and then upload the extracted content to the Spark Viewer.
Use the following command to decompress the .zst file:
zstd -d NameOfTheFile.zst