entity-broadcast-range-percentage 设置无效？为何实体广播范围未按百分比生效？

Question

在 Minecraft 服务端（如 Paper/Spigot）中，`entity-broadcast-range-percentage` 配置项常被误认为可动态缩放所有实体的广播距离（如生物感知、红石信号、音效传播等），但实际该参数**仅影响部分特定事件的网络广播范围（如 EntityTeleportEvent 的客户端同步）**，且自 Paper 1.19+ 起已被标记为遗留配置，多数实体行为（如僵尸感知玩家、凋灵AOE判定、TNT爆炸影响）由硬编码逻辑或独立配置（如 `mob-spawn-range`、`max-entity-collisions`）控制。若修改后无效果，常见原因包括：① 未重启服务端（该值不可热重载）；② 客户端缓存或模组干扰；③ 误用于非广播类逻辑（如 AI 感知半径由 `entity-tracking-range` 或 NMS 实现决定）。建议优先查阅对应版本 Paper 官方文档的 `paper.yml` 配置说明，并使用 `/paper debug entity-broadcast` 命令验证生效状态。

Answer 1

```html

一、基础认知：什么是 entity-broadcast-range-percentage？

该配置项位于 paper.yml 的 world-settings.<world>.entity-broadcast-range-percentage 路径下，初始默认值为 100.0（即 100%）。它并非“实体感知半径”或“AI 视野”，而是专用于控制 服务端向客户端广播实体状态变更事件的网络可见距离比例。典型影响场景包括：EntityTeleportEvent 同步、部分 EntityDamageEvent 可见性、以及 EntitySpawnEvent 的初始客户端接收范围。

二、核心误区解析：为什么调大它不会让僵尸“看得更远”？

• ❌ 僵尸感知玩家 → 由 net.minecraft.world.entity.monster.Zombie#canHear 硬编码逻辑决定（基于 getSensing().canSee(Player) + 障碍物射线检测）
• ❌ 凋灵AOE爆炸判定 → 由 WitherBoss#doAreaDamage 中硬编码的 12.0D 半径控制
• ❌ TNT连锁反应 → 依赖 Explosion#doExplosionB 中的 getBlocksToBlow() 和邻接方块扫描，与广播无关
• ✅ 真正受影响的仅限：客户端是否收到某次传送后的实体位置更新包（PacketPlayOutEntityTeleport）

三、版本演进与兼容性断层（Paper 1.19+ 关键变化）

版本区间	状态	行为说明
Paper 1.16–1.18.x	功能完整	对 EntityTeleport / EntityMetadata 更新广播有效
Paper 1.19.0+	DEPRECATED	日志中输出警告；部分广播路径已绕过该参数（如使用 EntityTracker 动态范围）
Paper 1.20.4+	仅保留向后兼容	完全不参与 PlayerConnection#sendPacket 的距离裁剪逻辑

四、失效归因诊断树（Mermaid 流程图）

flowchart TD
    A[修改 entity-broadcast-range-percentage] --> B{是否重启服务端？}
    B -->|否| C[❌ 失效：该值不可热重载]
    B -->|是| D{客户端是否连接新会话？}
    D -->|否| E[⚠️ 客户端缓存旧 EntityTracker 数据]
    D -->|是| F{是否启用 OptiFine/Forge 模组？}
    F -->|是| G[⚠️ 模组劫持 Packet 发送链路，绕过 Paper 广播逻辑]
    F -->|否| H{执行 /paper debug entity-broadcast}
    H --> I[✅ 输出当前生效百分比 & 实际广播实体数]

五、替代方案与精准调控矩阵

针对不同目标行为，应切换至对应配置或代码层干预：

• 生物AI感知距离 → 修改 paper.yml 中 entity-tracking-range.monsters（影响 EntityTrackerEntry 的 tick 频率与感知触发）
• 红石信号传播 → 属于世界区块加载逻辑，受 view-distance 与 simulation-distance 控制（spigot.yml）
• 音效传播范围 → 由 SoundCategory#volume 与客户端 options.txt 中 sounds 设置共同决定，服务端无广播缩放权
• 自定义实体广播逻辑 → 使用 Player#sendPluginMessage 或 NMS PlayerConnection#sendPacket 手动推送

六、实证验证：三步法确认配置真实生效

1. 启动服务端后执行：/paper debug entity-broadcast world_nether（替换为实际世界名）
2. 观察控制台输出类似：[DEBUG] Broadcast range for world_nether: 64.0 blocks (64.0% of 100)
3. 使用 Wireshark 抓包过滤 minecraft.packet.id == 0x2C（PacketPlayOutEntityTeleport），对比修改前后广播目标 Player 数量
4. 禁用所有插件后复测，排除 ProtocolLib 或 PacketListenerAPI 的中间拦截

七、高阶开发者建议：从配置到源码的穿透式理解

深入 Paper 源码可发现关键路径：

// Paper-1.20.4/src/main/java/io/papermc/paper/world/WorldManager.java
public double getEntityBroadcastRange(World world) {
    return this.worldSettings.get(world.getName()).entityBroadcastRangePercentage() / 100.0 * 100.0;
}
// 注意：该值仅在 EntityTrackerEntry#broadcastChanges() 中作为 fallback 调用，
// 现代实现优先使用 WorldServer#shouldSendToPlayer() 的动态距离评估。

因此，任何试图通过该配置“全局扩距”的运维操作，在 Paper ≥1.19 场景下本质是反模式。

```