PlayerCulling
描述
PlayerCulling 是一款用于 Minecraft 服务器的反作弊插件和模组。它防止玩家利用作弊手段透过墙壁观察其他玩家。它采用了一种独特的无分配异步体素步进面射线投射算法。
特性
- 异步、多线程剔除
- 无分配的体素射线投射算法
- 高级调度系统
- 支持显示名称可见性、药水效果、发光效果和旁观模式
- 针对非完整方块的 2x2x2 缩放体素遮挡
- 高效的遮挡方块数据存储
- 近乎瞬时的方块更新
- 易于全局/按玩家启用或禁用剔除
调度器概览
PlayerCulling 使用自定义的多线程剔除执行系统。利用该系统,PlayerCulling 能够根据服务器负载进行扩展,只要 CPU 资源充足,它可以处理极少或极多玩家的剔除任务。调度器会根据所需线程数动态启动/停止线程(“容器”)。
若要限制 PlayerCulling 可使用的资源量,请参阅插件配置中的线程限制。默认情况下,它将自己限制为(CPU 线程数 / 3)。
以下是一些关于 PlayerCulling 调度器工作原理的示例。
以下示例在配备 AMD Ryzen 5 3600X CPU 的 Arch Linux 桌面环境中测试:
-
一个容器
一个容器能够轻松处理 42 名玩家的负载。
-
两个容器
如果负载增加,调度器将自动创建第二个容器并分配玩家以维持缓冲。在此示例中,共有 55 名玩家聚集在一个区域内。
-
容器的清理
如果一个容器因负载降低而不再需要,它会先被暂停。
当它的存活时间(TTL)到期且负载未再次增加时,
它将被自动清理。
-
高负载
理论上,调度系统可以扩展到无限数量的容器。
只要负载增加(且未达到容器数量上限),调度器
就会自动继续添加更多容器。在此示例中,共有 112 名玩家聚集在一个区域内。
-
容器的合并
如果多个容器的负载过低,它们将在几秒后
合并在一起。
性能概览
通过此视图,您可以跟踪 PlayerCulling 的性能。
第一个 Boss 条显示了负载最高的容器的信息以及一般的
容器调度统计信息:
- Running(运行中)容器的数量
- Parked(已暂停)容器的数量
- 总的容器 Threads(线程)数量
- 每次剔除刻的总 Raysteps(射线步数)
第二个 Boss 条显示了遮挡世界缓存的负载、
工作线程、Completed(已完成)任务的数量、
Stored(已存储)区块的数量以及字节单位的区块缓存大小。
第三个 Boss 条显示了被剔除玩家的信息。最大被剔除玩家数量可以通过 (玩家数量) * (玩家数量 - 1) 计算得出。
在此示例中,共有 112 名玩家聚集在一个区域内。服务器在配备 AMD Ryzen 5 3600X CPU 的 Arch Linux 桌面环境中运行。
支持的软件
| Server Version |
Paper |
Folia |
Fabric |
| 26.3.x |
✅ |
❌ |
✅ |
| 26.2.x |
✅ |
✅ |
✅ |
| 26.1.x |
✅ |
✅ |
✅ |
| 1.21.11 |
✅ |
✅ |
✅ |
| 1.21.10 |
✅ |
✅ |
✅ |
| 1.21.9 |
✅ |
✅ |
✅ |
| 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 依赖项:
用法
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,即 CPU 核心数的三分之一)
cleanup-interval:检查并清理线程的间隔时间,单位为秒(默认值:30)
container-ttl:未使用线程的存活时间(TTL),单位为秒(默认值:30)
max-cull-time:单个线程允许运行的最长时间,单位为毫秒(默认值:45)
max-transfer-factor:如果某个线程的负载百分比低于此阈值,则允许它从其他过载线程接收更多任务(默认值:0.7)
max-merge-factor:如果两个线程的合并负载百分比低于此阈值,则允许这两个线程合并(默认值:0.5)
culling(剔除):
nametag-visibility-distance:PlayerCulling 用于检测玩家名称标签可见性的距离,单位为方块。设置为 0 可完全忽略名称标签(默认值:64,与原版一致)
blacklisted_worlds:应禁用 PlayerCulling 的世界列表(默认值:[])
updater(更新器):
enabled:启用或禁用更新检查器(默认值:true)
notify-admins:是否通知管理员有关 PlayerCulling 的新版本发布(默认值:true)
interval-hours:更新检查的时间间隔,单位为小时(默认值:24)
waypoint-mode:定位栏/航点系统的模式,更多信息请参阅 Locator Bar / Waypoints 部分。(默认值:HIDDEN)
注意:如果您不确定某项配置选项的作用,最好将其保留为默认值。
Locator Bar / Waypoints
定位栏是在 Minecraft 1.21.6 中引入的功能,允许玩家查看其他玩家的方向。由于这会暴露玩家的真实位置,从而违背 PlayerCulling 的目的,因此 PlayerCulling 默认会禁用所有与玩家相关的航点。如果您仍想使用定位栏,可以在配置文件中设置 waypoint-mode 选项,详见下文。
注意:玩家仍然可以通过三角测量推算出其他玩家的真实 X 和 Z 坐标,请使用 hidden 模式以防止这种情况
以下模式可用:
| Mode |
Description |
HIDDEN |
PlayerCulling 将禁用所有与玩家相关的航点(默认值) |
AZIMUTH |
PlayerCulling 会将玩家之间的角度发送给查看者 |
CULLED_AZIMUTH |
如果其他玩家对查看者可见,PlayerCulling 会将玩家之间的角度发送给查看者 |
VANILLA |
PlayerCulling 不会更改定位栏的行为,这使得 PlayerCulling 实际上无效 |
Permissions
| Permission |
Description |
playerculling.update-notify |
若未禁用,拥有此权限的玩家将收到更新通知 |
playerculling.bypass |
拥有此权限的玩家将被 PlayerCulling 忽略,从而始终能看到任何人。如果可能,请优先使用命令(/playerculling toggle)或 API,而非此权限 |
有关命令权限,请参见下表。
Commands
| 命令 |
描述 |
权限 |
/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 <target-player> [showRay] /playerculling raycastdebug <target-player> [blocks] /playerculling raycastdebug <target-player> [blocks] [showRay] |
检查执行者是否能看到 target-player,执行者必须为玩家。showRay 参数启用射线的粒子效果。blocks 参数会打印射线中检查过的所有方块。 |
playerculling.command.raycastdebug |
/playerculling reloadconfig |
重新加载配置文件。 |
playerculling.command.reloadconfig |
| /playerculling toggle global [enabled]
/playerculling toggle player <玩家列表> [enabled] | 切换 PlayerCulling 对指定 玩家列表 或全局的生效状态。可通过 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 设置
无论使用何种构建系统,都必须在 plugin.yml 中将 PlayerCulling 添加为依赖项。在 Fabric 上,需要将
playerculling 添加到 fabric.mod.json 文件中。
Maven
<repositories>
<repository>
<id>minceraft</id>
<url>https://repo.minceraft.dev/releases/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>de.pianoman911</groupId>
<artifactId>playerculling-api</artifactId>
<version>2.1.5</version>
<scope>provided</scope>
</dependency>
</dependencies>
Gradle (groovy)
repositories {
maven {
url = 'https://repo.minceraft.dev/releases/'
name = 'minceraft'
}
}
dependencies {
compileOnly 'de.pianoman911:playerculling-api:2.1.5'
}
Gradle (kotlin)
repositories {
maven("https://repo.minceraft.dev/releases/") {
name = "minceraft"
}
}
dependencies {
compileOnly("de.pianoman911:playerculling-api:2.1.5")
}
API 用法
基本的 Paper 插件示例:
public class ExamplePlugin extends JavaPlugin {
@Override
public void onEnable() {
// 这将从 Bukkit 的服务管理器加载玩家剔除 API
PlayerCullingApi api = Bukkit.getServicesManager().load(PlayerCullingApi.class);
// 示例:如果玩家 "Notch" 在线,则为其禁用剔除
Player player = Bukkit.getPlayer("Notch");
if (player != null) {
api.setCullingEnabled(player.getUniqueId(), false);
}
}
}
基本的 Fabric 模组示例:
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);
});
}
}
构建
- 克隆项目 (
git clone https://github.com/MinceraftMC/PlayerCulling.git)
- 进入克隆的目录 (
cd PlayerCulling)
- 构建 jar 文件 (
./gradlew build 适用于 Linux/MacOS,gradlew build 适用于 Windows)
PlayerCulling 的 jar 文件位于 build → libs 目录中。
贡献
如果你想为 PlayerCulling 做出贡献,请随意 fork 仓库并创建拉取请求。
请确保遵循项目中使用的代码风格和约定。如果你有任何问题或需要帮助,
欢迎在我们的 Discord 中提问。
你可以通过运行 ./gradlew plugin-paper:runServer 或 ./gradlew platform-fabric:runServer 来测试你的更改。这将
启动一个本地开发服务器,并自动安装编译后的插件或模组。这可以与 IDE 的调试器结合使用。
请注意,在开发环境中运行时,更新检查器将被自动禁用。
PlayerCulling
Description
PlayerCulling is an anti-cheat plugin and mod for Minecraft servers. It prevents players from seeing other players
through walls using cheats. It utilizes a unique allocationless asynchronous voxel stepping-faced-ray-casting algorithm.
Features
- Asynchronous, multithreaded culling
- Allocationsless voxel raycasting algorithm
- Advanced scheduler system
- Support for nametag visibility, potions, glowing and spectating
- 2x2x2-scale voxel occlusion for non-full blocks
- Efficient storage of occlusion block data
- Nearly instant block updates
- Easily enable/disable culling globally/per-player
Scheduler Overview
PlayerCulling uses a custom multi-threaded culling execution system. Using this system, PlayerCulling is able to scale
according to server load, and can cull both very few players and very many players, as long as enough CPU is available.
The scheduler will dynamically start/stop threads ("containers") based on how many threads are needed.
To limit the amount of resources PlayerCulling can use, see the thread limit in the plugin configuration.
By default it limits itself to (number of CPU threads / 3).
Here are some examples on how the PlayerCulling scheduler works.
The following examples were tested on an arch linux desktop environment with an AMD Ryzen 5 3600X CPU:
-
One Container
One container is able to handle the load of 42 players without many problems.
-
Two Containers
If the load increases, the scheduler will automatically create a second
container and distribute the players to maintain a buffer. In this example, a total of 55 players are together in an area.
-
Cleanup of Containers
If a container is no longer used because the load decreased, it gets parked first.
After its time-to-live (TTL) runs out because the load didn't increase again,
it will get cleaned up automatically.
-
Heavy Load
The scheduling system is theoretically able to scale to an infinite amount of containers.
As long as the load increases (and the limit of containers hasn't been reached yet), the scheduler
will automatically continue to add more containers. In this example, a total of 112 players are together in an area.
-
Merging of Containers
If the load of multiple containers is too low, they will be
merged together after a few seconds.
Performance Overview
Using this view you can keep track of PlayerCulling's performance.
The first bossbar shows info about the container with the highest load and general
container scheduling statistics:
- The count of Running containers
- The count of Parked containers
- The count of total container Threads
- The count of total Raysteps per cull tick
The second bossbar shows the load of the occlusion world cache,
the working threads, amount of Completed tasks,
amount of Stored chunks and the chunk cache size in bytes.
The third bossbar shows info about culled players. The maximum amount
of culled players can be calculated by (playercount) * (playercount - 1).
In this example, a total of 112 players are together in an area. The server was running in an arch linux desktop
environment with an AMD Ryzen 5 3600X CPU.
Supported Software
| Server Version |
Paper |
Folia |
Fabric |
| 26.3.x |
✅ |
❌ |
✅ |
| 26.2.x |
✅ |
✅ |
✅ |
| 26.1.x |
✅ |
✅ |
✅ |
| 1.21.11 |
✅ |
✅ |
✅ |
| 1.21.10 |
✅ |
✅ |
✅ |
| 1.21.9 |
✅ |
✅ |
✅ |
| 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 |
✅ |
❌ |
❌ |
Dependencies on Fabric:
Usage
PlayerCulling can be installed like any other bukkit plugin.
Place the jar file in your plugins directory. On Fabric as well, just place the jar file and the dependencies listed
above in your
mods directory and restart your server.
Configuration
After the first start, PlayerCulling will automatically create a configuration file. On paper under
plugins/PlayerCulling/config.yml or on Fabric config/playerculling.yml. In there, you are able to configure the
following options:
config-version: Don't touch this
scheduler:
max-threads: The maximum amount of threads allowed to use (default: cpu threads / 3)
cleanup-interval: The interval to check for cleanup of threads in seconds (default: 30)
container-ttl: The time-to-live of unused threads (default: 30)
max-cull-time: The maximum time a thread is allowed to have in milliseconds (default: 45)
max-transfer-factor: If the load percentage of a thread is below this factor, it is allowed to accept more tasks
from other overloaded threads (default: 0.7)
max-merge-factor: If the combined load percentage of two threads is below this factor, the two threads are
allowed to merge together (default: 0.5)
culling:
nametag-visibility-distance: The distance in blocks PlayerCulling will check for nametag visibility. Set to 0 to
ignore nametags completely (default: 64, vanilla)
blacklisted_worlds: A list of worlds where PlayerCulling should be disabled (default: [])
updater:
enabled: Enables/disables the update checker (default: true)
notify-admins: Whether to notify admins about new PlayerCulling releases (default: true)
interval-hours: The update check interval in hours (default: 24)
waypoint-mode: The mode for the waypoint system, see the Locator Bar / Waypoints section
for more information. (default: HIDDEN)
Note: If you're not sure what a configuration option does, it's best to leave it at its default value.
Locator Bar / Waypoints
The locator bar was introduced in Minecraft 1.21.6 and allows players to see the direction of other players. As this
would reveal the real location of players and defeat the purpose of PlayerCulling, PlayerCulling will disable all player
related waypoints by default. If you still want to use the locator bar, you can use the waypoint-mode option in the
configuration file, see below for more info.
Note: Players can still triangulate the real X and Z coordinates of players, use the hidden mode to prevent
this
The following modes are available:
| Mode |
Description |
HIDDEN |
PlayerCulling will disable all player related waypoints (default) |
AZIMUTH |
PlayerCulling will send the angle between players to the viewer |
CULLED_AZIMUTH |
PlayerCulling will send the angle between players to the viewer, if the other player is visible to the viewer |
VANILLA |
The locator bar will not be changed by PlayerCulling, this makes PlayerCulling effectively useless |
Permissions
| Permission |
Description |
playerculling.update-notify |
If not disabled, players with this permission will receive update notifications |
playerculling.bypass |
Players with this permission will be ignored by PlayerCulling and therefore be able to always see anyone. Use commands (/playerculling toggle) or API instead of this permission if possible |
See the table below for command permissions.
Commands
| Command |
Description |
Permission |
/playerculling blockdebug [raw] [block] /playerculling blockdebug [block] |
Checks the occluding status of a block in sight of the target entity or specified by the block argument. The raw argument specifies, if true get status from minecraft world, if false get status from PlayerCulling occlusion cache. |
playerculling.command.blockdebug |
/playerculling chunkcache |
Gives information about the stored chunks in the PlayerCulling occlusion cache. If the executor is an entity, you will get more information about the entity's chunk. |
playerculling.command.chunkcache |
/playerculling chunksizes |
Gives the byte size of each chunk in the executors world. You can click on a chunky entry to teleport. |
playerculling.command.chunksizes |
/playerculling cleancontainers [force] |
Triggers the cleanup process manually. The force argument decides if you check for the ttl or not. |
playerculling.command.cleancontainers |
/playerculling viewcontainers |
Toggles the view of the container scheduler. It shows the status, load and player count. Please note: The boss bar count is limited by your gui size, minecraft only renders boss bars over one third of the windows size. |
playerculling.command.viewcontainers |
/playerculling hidden |
Shows the hidden list of the executor. |
playerculling.command.hidden |
/playerculling performance |
Toggles the view of the PlayerCulling performance, overall occlusion cache size, and culled players count. Please note: The boss bar count is limited by your gui size, minecraft only renders boss bars over one third of the windows size. |
playerculling.command.performance |
/playerculling raycastdebug <target-player> [showRay] /playerculling raycastdebug <target-player> [blocks] /playerculling raycastdebug <target-player> [blocks] [showRay] |
Checks if the executor can see the target-player, the executor must be a player. The showRay argument enables particles of the rays. The blocks arguments prints all checked blocks in the ray. |
playerculling.command.raycastdebug |
/playerculling reloadconfig |
Reloads the configuration. |
playerculling.command.reloadconfig |
/playerculling toggle global [enabled] /playerculling toggle player <player-list> [enabled] |
Toggles PlayerCulling either for a player-list or global. The enabled argument can be used to always enable (true) or disable (false) PlayerCulling for the target -> no toggle. |
playerculling.command.toggle, playerculling.command.toggle.global, playerculling.command.toggle.player |
Note: [...] is an optional argument, <...> is a required argument
PlayerCulling uses brigadier for commands which means command blocks and datapacks are also able to use these commands.
Additionally, this also means /execute can recognize these commands and you are able to change the executor/location
of the executed command. For example:
/execute as Notch run playerculling hidden will show you the hidden players of the player Notch, if online
/execute as @a run playerculling hidden will show you the hidden players of everyone online
API setup
PlayerCulling has to be added as a dependency to the plugin.yml regardless of the build system used. On Fabric add
playerculling to the fabric.mod.json file.
Maven
<repositories>
<repository>
<id>minceraft</id>
<url>https://repo.minceraft.dev/releases/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>de.pianoman911</groupId>
<artifactId>playerculling-api</artifactId>
<version>2.1.5</version>
<scope>provided</scope>
</dependency>
</dependencies>
Gradle (groovy)
repositories {
maven {
url = 'https://repo.minceraft.dev/releases/'
name = 'minceraft'
}
}
dependencies {
compileOnly 'de.pianoman911:playerculling-api:2.1.5'
}
Gradle (kotlin)
repositories {
maven("https://repo.minceraft.dev/releases/") {
name = "minceraft"
}
}
dependencies {
compileOnly("de.pianoman911:playerculling-api:2.1.5")
}
API usage
Basic paper plugin example:
public class ExamplePlugin extends JavaPlugin {
@Override
public void onEnable() {
// this loads the player culling api from bukkit's services manager
PlayerCullingApi api = Bukkit.getServicesManager().load(PlayerCullingApi.class);
// example: disable culling for the player "Notch", if online
Player player = Bukkit.getPlayer("Notch");
if (player != null) {
api.setCullingEnabled(player.getUniqueId(), false);
}
}
}
Basic fabric mod example:
public class ExampleMod implements ModInitializer {
@Override
public void onInitialize() {
FabricLoader.getInstance().getObjectShare().whenAvailable("playerculling:api", (__, obj) -> {
if (!(obj instanceof PlayerCullingApi api)) {
return;
}
// Toggle global culling
api.setCullingEnabled(false);
});
}
}
Building
- Clone the project (
git clone https://github.com/MinceraftMC/PlayerCulling.git)
- Go to the cloned directory (
cd PlayerCulling)
- Build the jar (
./gradlew build on Linux/MacOS, gradlew build on Windows)
The PlayerCulling jars can be found in the build → libs directory.
Contributing
If you want to contribute to PlayerCulling, feel free to fork the repository and create a pull request.
Please make sure to follow the code style and conventions used in the project. If you have any questions or need help,
feel free to ask in our Discord.
You can test your changes by running ./gradlew plugin-paper:runServer or ./gradlew platform-fabric:runServer. This
will start a local development server with the compiled plugin or mod automatically installed. This can be combined with
the debugger of your IDE.
Please note that the update checker will be automatically disabled when running in a development environment.
评论 0
登录后参与评分
还没有评论,来抢沙发吧