PlayerCulling

# PlayerCulling [](https://github.com/MinceraftMC/PlayerCulling) [](https://opensource.org/license/agpl-v3/)  [](https://discord.gg/zC8xjtSPKC) ## 描述 PlayerCulling 是一个 Minecraft 服务器的反作弊插件和模组。它防止玩家使用作弊透视墙外的其他玩家。它利用了一种独特的无分配异步体素步进面对射线投射算法。 ## 特性 - 异步、多线程剔除 - 无分配体素射线投射算法 - 高级调度系统 - 支持标签可见性、药水、发光和旁观 - 2x2x2 比例的体素遮挡，用于非完整方块 - 高效存储遮挡方块数据 - 几乎即时的方块更新 - 轻松启用/禁用全局/每个玩家的剔除

调度器概述

PlayerCulling 使用自定义的多线程剔除执行系统。通过该系统，PlayerCulling 可以根据服务器负载进行缩放，并且可以剔除很少的玩家和很多玩家，只要有足够的 CPU 可用。 调度器将根据需要的线程数量动态地启动/停止线程（“容器”）。 为了限制 PlayerCulling 可以使用的资源量，请参阅插件配置中的线程限制。 默认情况下，它将其限制为 (CPU 线程数 / 3)。 以下是一些关于 PlayerCulling 调度器工作方式的例子。 以下示例是在具有 AMD Ryzen 5 3600X CPU 的 arch linux 桌面环境中测试的：

• 一个容器

  一个容器能够在没有很多问题的情况下处理 42 个玩家的负载。
  
  
• 两个容器

  如果负载增加，调度器将自动创建第二个 容器并将玩家分发以保持缓冲区。在此示例中，在区域内共有 55 名玩家。
  
  
• 容器清理

  如果容器不再被使用，因为负载降低，它将被暂停。 在它的生存时间 (TTL) 过期并且负载没有再次增加之后， 它将被自动清理。
  
  
• 高负载

  调度系统在理论上能够扩展到无限数量的容器。 只要负载增加（并且容器数量限制尚未达到），调度器 将自动继续添加更多容器。在此示例中，在区域内共有 112 名玩家。
  
  
• 容器合并

  如果多个容器的负载过低，它们将被 在几秒钟后合并在一起。
  
  

性能概述

使用此视图可以跟踪 PlayerCulling 的性能。 第一个 Boss 栏显示有关负载最高的容器以及通用 容器调度统计信息： - **R**unning 容器数 - **P**arked 容器数 - 总容器 **T**hreads 数 - 每剔除周期总 **R**aysteps 数 第二个 Boss 栏显示遮挡世界缓存的负载， 工作线程、**C**ompleted 任务数量、 存储的 **S**tored 块数量以及以字节为单位的块缓存大小。 第三个 Boss 栏显示有关剔除玩家的信息。最大数量 剔除玩家可以计算为 (玩家数量) * (玩家数量 - 1)。 在此示例中，在区域内共有 112 名玩家。服务器运行在具有 AMD Ryzen 5 3600X CPU 的 arch linux 桌面 环境中。

### 支持的软件 | 服务器版本 | Paper | Folia | Fabric | |:--------------:|:-----:|:-----:|:------:| | 1.21.8 | ✅ | ✅ | ❌ | | 1.21.7 | ✅ | ✅ | ✅ | | 1.21.6 | ✅ | ✅ | ✅ | | 1.21.5 | ✅ | ✅ | ✅ | | 1.21.4 | ✅ | ✅ | ✅ | | 1.21.3 | ✅ | ❌ | ❌ | | 1.21.2 | ✅ | ❌ | ❌ | | 1.21.1 | ✅ | ❌ | ❌ | | 1.21 | ✅ | ❌ | ❌ | #### Fabric 依赖： - [Fabric API](https://github.com/FabricMC/fabric) ## 使用方法 PlayerCulling 可以像安装任何其他 bukkit 插件一样安装。 将 jar 文件放在你的 `plugins` 目录中。同样，在 Fabric 上，只需将 jar 文件和上面列出的依赖项 放在你的 `mods` 目录中，然后重启你的服务器。 ### 配置 首次启动后，PlayerCulling 将自动创建一个配置文件。在 paper 下 `plugins/PlayerCulling/config.yml` 或者在 Fabric 上 `config/playerculling.yml`。 在其中，你可以配置 以下选项： - `config-version`: 不要修改此项 - `scheduler`: - `max-threads`: 允许使用的最大线程数 (默认: `cpu threads / 3`) - `cleanup-interval`: 检查线程清理的间隔（秒） (默认: `30`) - `container-ttl`: 未使用线程的生存时间 (默认: `30`) - `max-cull-time`: 线程允许参与的最大时间（毫秒） (默认: `45`) - `max-transfer-factor`: 如果线程负载百分比低于此因子，则允许从其他过载线程接受更多任务 (默认: `0.7`) - `max-merge-factor`: 如果两个线程的合并负载百分比低于此因子，则允许这两个线程 合并在一起 (默认: `0.5`) - `updater`: - `enabled`: 启用/禁用更新检查器 (默认: `true`) - `notify-admins`: 是否通知管理员有关 PlayerCulling 新版本的信息 (默认: `true`) - `interval-hours`: 更新检查间隔（小时） (默认: `24`) - `waypoint-mode`: 指示栏系统的模式，请参阅 [指示栏 / 指示器](#locator-bar--waypoints) 部分 获取更多信息。 (默认: `HIDDEN`) 注意：如果您不确定配置选项的作用，最好将其保留在默认值中。 ### 权限 | 权限 | 描述 | |-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `playerculling.update-notify` | 如果未禁用，具有此权限的玩家将收到更新通知 | | `playerculling.bypass` | 具有此权限的玩家将被 PlayerCulling 忽略，因此始终能够看到所有人。 如果可能，请使用命令 (`/playerculling toggle`) 或 API 而不是此权限 | 请参阅以下表格了解命令权限。 ### 命令 | 命令 | 描述 | 权限 | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| | `/playerculling blockdebug [raw] [block]`
`/playerculling blockdebug [block]` | 检查目标实体视线内的块的遮挡状态或由 `block` 参数指定的块。 `raw` 参数指定，如果为 `true` 获取 minecraft 世界的状态，如果为 `false` 获取 PlayerCulling 遮挡缓存的状态。 | `playerculling.command.blockdebug` | | `/playerculling chunkcache` | 提供有关 PlayerCulling 遮挡缓存中存储的块的信息。 如果执行者是实体，你将获得更多关于实体块的信息。 | `playerculling.command.chunkcache` | | `/playerculling chunksizes` | 提供执行者世界中每个块的字节大小。 你可以点击块条目以传送。 | `playerculling.command.chunksizes` | | `/playerculling cleancontainers [force]` | 手动触发清理过程。 `force` 参数决定是否检查 TTL 或不检查。 | `playerculling.command.cleancontainers` | | `/playerculling viewcontainers` | 切换容器调度器的视图。 它显示状态、负载和玩家计数。 请注意：Boss 栏计数受你的 GUI 大小限制，minecraft 只会渲染窗口上三分之一大小的 Boss 栏。 | `playerculling.command.viewcontainers` | | `/playerculling hidden` | 显示执行者的隐藏列表。 | `playerculling.command.hidden` | | `/playerculling performance` | 切换 PlayerCulling 性能视图、整体遮挡缓存大小和剔除玩家数。 请注意：Boss 栏计数受你的 GUI 大小限制，minecraft 只会渲染窗口上三分之一大小的 Boss 栏。 | `playerculling.command.performance` | | `/playerculling raycastdebug [showRay]`
`/playerculling raycastdebug [blocks]`
`/playerculling raycastdebug [blocks] [showRay]` | 检查执行者是否能看到 `target-player`，执行者必须是玩家。 `showRay` 参数启用射线粒子。 `blocks` 参数打印射线中检查的所有块。 | `playerculling.command.raycastdebug` | | `/playerculling reloadconfig` | 重新加载配置。 | `playerculling.command.reloadconfig` | | `/playerculling toggle global [enabled]`
`/playerculling toggle player [enabled]` | 切换 PlayerCulling，无论是全局还是针对 `player-list`。 `enabled` 参数可用于始终启用 (`true`) 或禁用 (`false`) PlayerCulling 以供目标使用 -> 无切换。 | `playerculling.command.toggle`, `playerculling.command.toggle.global`, `playerculling.command.toggle.player` | 注意：`[...]` 是一个可选参数，`<...>` 是一个必需的参数 PlayerCulling 使用 brigadier 用于命令，这意味着命令块和数据包也能够使用这些命令。 此外，这意味着 `/execute` 可以识别这些命令，并且你可以更改执行命令的执行器/位置。 例如： - `/execute as Notch run playerculling hidden` 将显示玩家 `Notch`（如果在线）的隐藏玩家 - `/execute as @a run playerculling hidden` 将显示所有在线玩家的隐藏玩家 ### API 设置 `PlayerCulling` 无论使用哪种构建系统，都必须作为依赖项添加到 `plugin.yml` 中。 在 Fabric 上，将 `playerculling` 添加到 `fabric.mod.json` 文件。

Maven

```xml minceraft https://repo.minceraft.dev/releases/ ``` ```xml de.pianoman911 playerculling-api 2.1.0-SNAPSHOT provided ```

Gradle (groovy)

```groovy repositories { maven { url = 'https://repo.minceraft.dev/releases/' name = 'minceraft' } } dependencies { compileOnly 'de.pianoman911:playerculling-api:2.1.0-SNAPSHOT' } ```

Gradle (kotlin)

```kotlin repositories { maven("https://repo.minceraft.dev/releases/") { name = "minceraft" } } dependencies { compileOnly("de.pianoman911:playerculling-api:2.1.0-SNAPSHOT") } ```

### API 使用 基本 paper 插件示例： ```java public class ExamplePlugin extends JavaPlugin { @Override public void onEnable() { // 此处加载 bukkit 服务管理器的 player culling api PlayerCullingApi api = Bukkit.getServicesManager().load(PlayerCullingApi.class); // 示例：禁用玩家 "Notch" 的剔除，如果在线 Player player = Bukkit.getPlayer("Notch"); if (player != null) { api.setCullingEnabled(player.getUniqueId(), false); } } } ``` 基本 fabric 模组示例： ```java public class ExampleMod implements ModInitializer { @Override public void onInitialize() { FabricLoader.getInstance().getObjectShare().whenAvailable("playerculling:api", (__, obj) -> { if (!(obj instanceof PlayerCullingApi api)) { return; } // 切换全局剔除 api.setCullingEnabled(false); }); } } ``` ## 构建 1. 克隆项目 (`git clone https://github.com/MinceraftMC/PlayerCulling.git`) 2. 切换到克隆的目录 (`cd PlayerCulling`) 3. 构建 jar (`./gradlew build` 在 Linux/MacOS 上，`gradlew build` 在 Windows 上) PlayerCulling jar 文件可以在 `build` → `libs` 目录中找到。 ### 贡献 如果您想为 PlayerCulling 做出贡献，请随意分叉存储库并创建拉取请求。 请确保遵循项目中使用的代码风格和约定。 如果您有任何问题或需要帮助， 请在我们的 [Discord](https://discord.gg/zC8xjtSPKC) 上提问。 您可以通过运行 `./gradlew plugin-paper:runServer` 或 `./gradlew platform-fabric:runServer` 来测试您的更改。 这 将启动带有自动安装的编译插件或模组的本地开发服务器。 这可以与您的 IDE 中的调试器结合使用。
请注意，在开发环境运行时，更新检查器将自动禁用。