Minecraft Folia环境下使用WorldCreator加载世界的调度器选择问题

我正在使用Minecraft Folia服务端，需要加载一个已保存至磁盘的世界，但不确定应当使用哪种调度器：EntityScheduler、GlobalRegionScheduler、RegionScheduler，还是无需使用调度器。

原加载代码如下：

WorldCreator worldCreator = new WorldCreator("world");
worldCreator.environment(World.Environment.NORMAL);
worldCreator.generateStructures(true);
worldCreator.type(WorldType.NORMAL);
Bukkit.createWorld(worldCreator);

运行代码时抛出如下错误：

org.bukkit.command.CommandException: Unhandled exception executing command 'worldtp' in plugin Pluralistic v1.0.0
        at org.bukkit.command.PluginCommand.execute(PluginCommand.java:47) ~[folia-api-1.20.4-R0.1-SNAPSHOT.jar:?]
        at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:155) ~[folia-api-1.20.4-R0.1-SNAPSHOT.jar:?]
        at org.bukkit.craftbukkit.v1_20_R3.CraftServer.dispatchCommand(CraftServer.java:1042) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at org.bukkit.craftbukkit.v1_20_R3.command.BukkitCommandWrapper.run(BukkitCommandWrapper.java:64) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at com.mojang.brigadier.context.ContextChain.runExecutable(ContextChain.java:73) ~[brigadier-1.2.9.jar:?]
        at net.minecraft.commands.execution.tasks.ExecuteCommand.execute(ExecuteCommand.java:31) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.execution.tasks.ExecuteCommand.execute(ExecuteCommand.java:19) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.execution.UnboundEntryAction.lambda$bind$0(UnboundEntryAction.java:8) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.execution.CommandQueueEntry.execute(CommandQueueEntry.java:5) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.execution.ExecutionContext.runCommandQueue(ExecutionContext.java:103) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.Commands.executeCommandInContext(Commands.java:434) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.Commands.performCommand(Commands.java:336) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.commands.Commands.performCommand(Commands.java:323) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.server.network.ServerGamePacketListenerImpl.performChatCommand(ServerGamePacketListenerImpl.java:2285) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.server.network.ServerGamePacketListenerImpl.lambda$handleChatCommand$14(ServerGamePacketListenerImpl.java:2245) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at io.papermc.paper.threadedregions.EntityScheduler.executeTick(EntityScheduler.java:173) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at net.minecraft.server.MinecraftServer.tickServer(MinecraftServer.java:1646) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at io.papermc.paper.threadedregions.TickRegions$ConcreteRegionTickHandle.tickRegion(TickRegions.java:407) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at io.papermc.paper.threadedregions.TickRegionScheduler$RegionScheduleHandle.runTick(TickRegionScheduler.java:404) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at ca.spottedleaf.concurrentutil.scheduler.SchedulerThreadPool$TickThreadRunner.run(SchedulerThreadPool.java:525) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at java.lang.Thread.run(Unknown Source) ~[?:?]
Caused by: java.lang.UnsupportedOperationException
        at org.bukkit.craftbukkit.v1_20_R3.CraftServer.createWorld(CraftServer.java:1286) ~[folia-1.20.4.jar:git-Folia-"ec6b172"]
        at org.bukkit.Bukkit.createWorld(Bukkit.java:835) ~[folia-api-1.20.4-R0.1-SNAPSHOT.jar:?]
        at org.bukkit.WorldCreator.createWorld(WorldCreator.java:502) ~[folia-api-1.20.4-R0.1-SNAPSHOT.jar:?]
        at com.pluralistic.Pluralistic.onCommand(Pluralistic.java:57) ~[Pluralistic-1.0.0.jar:?]
        at org.bukkit.command.PluginCommand.execute(PluginCommand.java:45) ~[folia-api-1.20.4-R0.1-SNAPSHOT.jar:?]
        ... 20 more

问题分析与解决方案 #

• 错误原因：Folia的线程模型限制了在区域/实体线程中直接调用Bukkit.createWorld()，世界加载属于全局操作，必须在主线程执行。
• 正确调度器选择：使用GlobalRegionScheduler，它负责全局主线程任务，适合执行跨区域、需要主线程权限的操作。
• 修正后代码示例：

// 获取全局区域调度器
GlobalRegionScheduler globalScheduler = Bukkit.getGlobalRegionScheduler();
// 将世界加载任务提交到主线程执行
globalScheduler.run(yourPluginInstance, task -> {
    WorldCreator worldCreator = new WorldCreator("world");
    worldCreator.environment(World.Environment.NORMAL);
    worldCreator.generateStructures(true);
    worldCreator.type(WorldType.NORMAL);
    Bukkit.createWorld(worldCreator);
});

调度器适用场景说明 #

• GlobalRegionScheduler：处理全局主线程任务，如世界加载、服务端全局配置修改等。
• RegionScheduler：仅用于特定区域内的线程任务，不适合世界加载这类全局操作。
• EntityScheduler：绑定实体所在线程，同样不适用于世界加载。

内容的提问来源于stack exchange，提问作者PlaidMrdeer