Folia - 区域化多线程的Minecraft服务器优化方案

Paper的分支，为专用服务器添加了区域化多线程。

概述

Folia将附近的已加载区块分组，形成"独立区域"。有关Folia如何对附近区块进行分组的具体细节，请参阅PaperMC文档。每个独立区域都有自己的tick循环，以常规Minecraft tick速率（20TPS）运行。这些tick循环在线程池中并行执行。不再有主线程，因为每个区域实际上都有自己的"主线程"来执行整个tick循环。

对于玩家分散的服务器，Folia将创建许多分散的区域，并在可配置大小的线程池中并行处理它们。因此，Folia应该能够很好地适应这类服务器。

Folia也是一个独立的项目，在可预见的将来不会合并到Paper中。

更详细但抽象的概述：项目概览。

常见问题

哪些类型的服务器可以从Folia中受益？

自然将玩家分散开的服务器类型，如空岛或生存多人游戏，将从Folia中获得最大收益。服务器还应该有相当数量的玩家。

Folia在什么硬件上运行最佳？

理想情况下，至少16个核心（而非线程）。

如何最佳配置Folia？

首先，建议预生成世界，这样可以大大减少所需的区块系统工作线程数量。

以下是基于Folia发布前在我们运行的测试服务器上进行的测试的非常粗略的估计，该服务器峰值约有330名玩家。因此，这并不准确，需要进一步调整 - 仅将其作为一个起点。

应考虑机器上可用的总核心数。然后，为以下内容分配线程：

netty IO：每200-300名玩家约4个
区块系统IO线程：每200-300名玩家约3个
如果预生成，区块系统工作线程：每200-300名玩家约2个
如果未预生成，区块系统工作线程没有最佳估计，因为在我们运行的测试服务器上，我们分配了16个线程，但在约300名玩家时区块生成仍然很慢。
GC设置：????但是，GC设置确实会分配并发线程，你需要确切知道有多少。这通常通过-XX:ConcGCThreads=n标志设置。不要将此标志与-XX:ParallelGCThreads=n混淆，因为并行GC线程只在应用程序被GC暂停时运行，因此不应考虑在内。

在所有这些分配之后，系统上剩余的核心直到80% 分配（总分配线程 < 可用CPU的80%）可以分配给tick线程（在全局配置下，threaded-regions.threads）。

你不应分配超过80%核心的原因是由于插件甚至服务器可能会使用你无法配置甚至预测的额外线程。

此外，以上都是基于玩家数量的粗略估计，但很可能线程分配不会是理想的，你需要根据最终看到的线程使用情况进行调整。

插件兼容性

不再有主线程。我预计现有的每一个插件都需要某种程度的修改才能在 Folia中运行。此外，任何类型的多线程都会引入插件持有数据的潜在竞争条件 - 所以，必然需要进行一些更改。

因此，请将兼容性期望值设为0。

API计划

目前，有很多API依赖于主线程。我预计基本上没有与Paper兼容的插件能够与Folia兼容。然而，我们计划添加一些API，允许Folia插件与Paper兼容。

例如，Bukkit调度器。Bukkit调度器本质上依赖于单个主线程。Folia的RegionScheduler和Folia的 EntityScheduler允许将任务调度到"拥有"位置或实体的区域的"下一个tick"。这些可以在普通Paper上实现，只是它们调度到主线程 - 在两种情况下，任务的执行都将发生在"拥有"位置或实体的线程上。这个概念普遍适用，因为当前的Paper （单线程）可以被视为一个包含所有世界中所有区块的巨大"区域"。

尚未决定是直接将此API添加到Paper本身还是添加到Paperlib中。

新规则

首先，Folia会破坏许多插件。为了帮助用户确定哪些插件可用，只有被作者明确标记为与Folia兼容的插件才会被加载。通过在插件的plugin.yml中放置"folia-supported: true"，插件作者可以将其插件标记为与区域化多线程兼容。另一个重要规则是区域并行运行，而非并发运行。它们不共享数据，也不期望共享数据，数据共享将导致数据损坏。在一个区域运行的代码在任何情况下都不能访问或修改另一个区域的数据。尽管名字中包含多线程，但这并不意味着所有内容现在都是线程安全的。实际上，只有少数几项被设置为线程安全以实现这一点。随着时间推移，线程上下文检查的数量只会增加，即使会影响性能 - 没有人会使用或为一个充满bug的服务器平台开发，防止和发现这些bug的唯一方法是让错误访问在源头处严重失败。

这意味着Folia兼容的插件需要利用RegionScheduler和EntityScheduler等API来确保其代码在正确的线程上下文中运行。

一般来说，可以安全地假设一个区域拥有事件源（如玩家破坏方块）周围大约8个区块的数据。但这并不保证 - 插件应利用即将推出的线程检查API来确保正确行为。

线程安全的唯一保证来自单个区域拥有特定区块中的数据 - 如果该区域正在运行，那么它就可以完全访问该数据。这些数据特指实体/区块/兴趣点数据，与任何插件数据完全无关。

普通的多线程规则适用于插件存储/访问自己的数据或其他插件的数据 - 事件/命令等并行调用，因为区域并行运行（我们不能同步调用它们，因为这会导致死锁问题并影响性能）。没有简单的解决方法，这完全取决于访问的数据。有时使用并发集合（如ConcurrentHashMap）就足够了，但经常会出现粗心使用并发集合只会隐藏线程问题的情况，这些问题随后变得几乎无法调试。

当前API添加

要正确理解API添加，请阅读项目概览。

RegionScheduler、AsyncScheduler、GlobalRegionScheduler和EntityScheduler作为BukkitScheduler的替代品。实体调度器通过Entity#getScheduler获取，其他调度器可以从Bukkit/Server类获取。
Bukkit#isOwnedByCurrentRegion用于测试当前运行区域是否拥有位置/实体

API的线程上下文

要正确理解API添加，请阅读项目概览。

一般规则：

实体/玩家的命令在拥有该实体/玩家的区域上调用。控制台命令在全局区域执行。
涉及单个实体的事件（如玩家破坏/放置方块）在拥有该实体的区域上调用。涉及对实体操作的事件（如实体伤害）在拥有目标实体的区域上调用。
事件的异步修饰符已废弃 - 从区域或全局区域触发的所有事件都被视为同步，尽管不再有主线程。

当前损坏的API

大多数与传送门交互/重生玩家/某些玩家登录API相关的API已损坏。
所有记分板API都被视为已损坏（这是全局状态，我还没有找到正确实现的方法）
世界加载/卸载
Entity#teleport。这在任何情况下都不会恢复，请使用teleportAsync
可能还有更多

计划中的API添加

正确的异步事件。这将允许事件结果稍后在不同的线程上下文中完成。这对于实现一些功能（如选择出生点位置）是必需的，因为在区域外访问区块数据时需要异步加载区块。
世界加载/卸载
更多内容将添加到此处

计划中的API更改

全面激进的线程检查。这对于防止插件开发者发布可能以完全无法诊断的方式随机破坏服务器各个部分的代码是绝对必要的。
更多内容将添加到此处

Maven信息

Maven仓库（用于folia-api）：

<repository>
    <id>papermc</id>
    <url>https://repo.papermc.io/repository/maven-public/</url>
</repository>

工件信息：

<dependency>
    <groupId>dev.folia</groupId>
    <artifactId>folia-api</artifactId>
    <version>1.20.1-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

许可证

PATCHES-LICENSE文件描述了API和服务器补丁的许可证，位于./patches及其子目录中，除非另有说明。

此分支基于PaperMC的分支示例，可在此处找到。因此，本项目包含对其的修改，请参阅该存储库以获取修改文件的许可证信息。