Viper 反Xray · 我的世界Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

ViperAntiXray (1.21.x 26.x)

什么是 ViperAntiXray？

ViperAntiXray 是一个仅服务端的 Fabric 模组，通过混淆发送给客户端的区块数据包，彻底消除 X-ray 作弊。与基于材质包或客户端“反作弊”模组的方案不同，ViperAntiXray 在网络层运行——服务端为未暴露的矿石发送虚假方块数据，仅当玩家合法挖掘相邻方块、触发爆炸或获得直接视线时才揭示真实方块。

核心差异化： 无需客户端安装即可实现每刻数据包精度，即使在高延迟下也能消除虚假矿石发现。原版玩家正常连接并看到合法的世界生成。X-ray 用户只能看到石头、深板岩和可配置的假矿石。

核心反 X-ray 引擎（未修改）

ViperAntiXray 的核心是 Paper 异步反 X-ray 补丁的忠实移植——自 1.17 以来保护数千个 Paper/Spigot 服务器的久经考验的引擎。我们没有修改核心混淆逻辑。我们将其封装在 Fabric/Architectury 模块中，并通过事件驱动的功能模块进行扩展。

引擎模式

模式	名称	行为	性能	适用场景
1	隐藏（Hide）	将所有完全被遮挡（周围无空气）的 `hiddenBlocks` 中的方块替换为 `replacementBlocks` 中的方块	CPU 占用最低	预算服务器、基础保护
2	倍增（Multiply）	将所有 `hiddenBlocks` 和 `replacementBlocks` 中的方块替换为 `hiddenBlocks` 中的随机方块	CPU 占用中等	高价值经济、无政府服务器
3	智能（推荐）	与引擎模式 2 非常相似，但在慢速连接下表现更好	CPU 占用中等	通用、混合延迟

工作原理（简化）

发送区块数据包  异步工作线程  调色板分析  方块分类
                                                               
                              揭示？  相邻空气/透明？  隐藏方块？
                                                                          
                            是  发送真实方块              否  发送虚假/替代方块

异步处理： 区块数据包转换在专用工作线程上运行（线程池大小可配置）
零主线程影响： 世界生成、实体刻和玩家移动绝不会因混淆而阻塞
按维度配置： 每个维度可使用不同的引擎模式、高度和方块列表

增强你的服务器配置！ 查看我在 : Fabric Server Essentials 上的其他服务端模组

配置

文件： config/viperantixray-fabric.toml（首次运行时自动生成）

默认配置

# Default values
enabled = false
usePermission = false

# World specific values
[overworld]
enabled = true
engineMode = 3
maxBlockHeight = 256
updateRadius = 2
lavaObscures = false
hiddenBlocks = ["#c:ores", "raw_copper_block", "raw_iron_block", "raw_gold_block", "!#viperantixray:hidden_only_ores"]
replacementBlocks = ["#viperantixray:hidden_only_ores", "stone", "deepslate", "andesite", "calcite", "diorite", "dirt", "granite", "gravel", "sand", "tuff", "mossy_cobblestone", "obsidian", "clay", "infested_stone", "amethyst_block", "budding_amethyst", "chest"]

[the_nether]
enabled = true
engineMode = 1
maxBlockHeight = 128
updateRadius = 2
lavaObscures = true
hiddenBlocks = ["ancient_debris", "nether_quartz_ore", "nether_gold_ore", "gold_block", "gilded_blackstone"]

配置选项概览

选项	类型	描述
`enabled`	`bool`	若设为 true，反 X-ray 将在指定世界中启用
`engineMode`	`int`	可为 1、2 或 3——参见引擎模式
`maxBlockHeight`	`int`	控制方块应被混淆的最大高度
`updateRadius`	`int`	控制距离已显示方块多远开始混淆（如果你玩家看到假矿石，增大此值）
`lavaObscures`	`bool`	若为 true，熔岩旁边的方块将被遮挡
`hiddenBlocks`	`string[]`	要隐藏的方块列表（引擎模式 1）或用于混淆的方块列表（引擎模式 2/3）
`replacementBlocks`	`string[]`	将被混淆但不作为假方块的方块列表（仅引擎模式 2/3）

注意： 方块/方块标签可添加 ! 前缀以从列表中移除。规则从左到右应用；移除项应在添加项之后指定。（自 1.4.10 起）

自定义维度

要在自定义维度中配置 ViperAntiXray，请指定维度 ID：

[dimensions."custom:cool_world"]
enabled = true
engineMode = 3
maxBlockHeight = 256
updateRadius = 2
lavaObscures = false
hiddenBlocks = ["#c:ores", "raw_copper_block"]
replacementBlocks = ["stone", "deepslate"]

引擎模式详情

EngineMode 1——隐藏（Hide）

将 hiddenBlocks 中所有完全被遮挡（周围无空气）的方块替换为 replacementBlocks 中的方块。仅完全被其他方块包围的隐藏方块会受到影响。

EngineMode 2——倍增（Multiply）

将所有 hiddenBlocks 和 replacementBlocks 中的方块替换为 hiddenBlocks 中的随机方块。创建一片假矿石场以淹没 X-ray HUD。

EngineMode 3——智能（推荐）

与引擎模式 2 非常相似，但在慢速连接下表现更好。使用数据包合并以减少高延迟玩家的失同步。

合法玩家视图

安装此模组后，合法玩家不会注意到任何变化（除非他们拥有高延迟或同时修改大量方块，例如爆炸）。

模组开发者

添加到 #viperantixray:hidden_only_ores 方块标签的矿石方块将从世界中隐藏，但不会用作假矿石。如果你的矿石具有可能导致问题的效果（粒子、声音），这将非常有用。

// data/viperantixray/tags/block/hidden_only_ores.json
{
  "replace": false,
  "values": [
    "mymod:custom_ore",
    "mymod:rare_gem_ore"
  ]
}

新增内容（11 个新功能模块）

所有功能均实现为 me.drex.viperantixray.common.features.* 中的独立模块——它们通过 Fabric 事件挂钩，且绝不触碰核心引擎。

1. 蜜罐 / 假矿陷阱

在地下深处生成只有 X-ray 用户才能看到的假矿脉。挖掘它们会立即标记作弊者。

放置： 每区块可配置密度（默认：Y=16 以下方块的 0.1%）
方块： 钻石、绿宝石、远古残骸、通过标签 #viperantixray:honey_pots 的自定义矿石
检测： 当玩家挖掘蜜罐方块时：
- 在 viperantixray:player_data NBT 中增加 suspicion_score
- 向所有拥有 viperantixray.alerts 权限的管理员发送警报
- 可选的 Discord webhook 嵌入（玩家、坐标、方块、时间戳）
- 记录到 logs/viperantixray/honeypot.log（JSONL 格式，用于 SIEM 摄取）

2. 挖掘分析 & 可疑度评分

追踪每位玩家的每次方块破坏，计算挖掘效率比（矿石/石头），并标记统计异常值。

指标： total_blocks_mined、ores_mined（按类型）、stone_broken、efficiency_ratio = ores / stone、session_time、chunks_visited、depth_distribution
可疑度算法： 按维度的滚动均值/标准差；当 efficiency_ratio > mean + (threshold * stddev)（默认：3.5）时标记
命令： /viperantixray audit <player>、/viperantixray auditlist

3. 邻近 & 射线衰减

使用快速体素射线投射，沿玩家直接视线动态禁用混淆。

每 N 刻射线投射（默认：4 刻 = 每位玩家每秒 5 次）
半径： 可配置锥角（默认：15）和距离（默认：48 方块）
带宽节省： 高人口服务器上发送给客户端的虚假方块减少约 40%

4. 自适应引擎模式

在负载下自动降级引擎模式，以防止幽灵方块、失同步和 TPS 崩溃。

触发条件	条件	动作	恢复
低 TPS	TPS < 18.0 持续 10 秒	模式 3→2，模式 2→1	TPS > 19.5 持续 30 秒 → 升级
高延迟	平均延迟 > 250ms	模式 3→2，模式 2→1	延迟 < 200ms 持续 60 秒 → 升级
数据包队列	异步队列 > 80%	立即降级	队列 < 40% → 升级
内存	堆 > 85%	立即模式 3→1	堆 < 70% → 升级

5. 异步线程池

将整个区块数据包混淆管线从主线程卸载。

工作线程： 可配置（默认：CPU 核心数 / 2，最小 2，最大 8）
队列： 有界阻塞队列（默认：128 区块）
背压： 队列满时回退到同步处理（记录日志）

6. 子区块剔除

将混淆限制在玩家 Y 等级 + 边际或以下的子区块（16×16×16）。

剔除逻辑： 仅处理 sectionY <= (playerY >> 4) + cullingMargin 的区段
默认边际： 2 个区段（玩家上方 32 方块）
节省： 地表玩家的每区块数据包调色板分析减少约 60%

7. 声音 & 光照隐藏

静音完全包裹方块的声音，击败基于声音的 ESP/X-ray。

覆盖方块： 紫水晶钟声、Sculk 振动、熔岩气泡、滴水石锥滴水
机制： 完全被包围的发声方块绝不发送触发声音的状态

8. 爆炸 & 连锁挖掘保护

在大规模方块破坏期间，通过单个数据包批量揭示所有隐藏矿石。

触发： TNT、床、重生锚、VeinMiner/Excavator、WorldEdit、大型苦力怕
机制： 收集 5 刻窗口内的变化，发送一个合并的区块数据包
防止： 幽灵石头渲染延迟、失同步、客户端 FPS 下降

9. 内置维度配置文件

为原版和流行模组维度提供零配置保护。

预配置文件包括：主世界、下界、末地、深邃洞穴、以太、暮色森林、泥沼（若模组存在则自动检测）。

10. 游戏内管理员检视

旁观者模式的管理员可切换“Anti-Xray 视觉”以准确查看玩家所见——即时生效，无需重新登录。

命令： /viperantixray inspect [on|off|toggle]
视觉： 被混淆的方块以绿色轮廓粒子高亮（仅客户端）
HUD： 引擎模式、剔除状态、异步队列深度、TPS 影响

11. 实时方块列表编辑

在运行时修改隐藏/替代方块，即时热重载——无需重启服务器。

命令	示例	描述
`/viperantixray addhidden <block>`	`addhidden minecraft:copper_ore`	添加到隐藏列表
`/viperantixray removehidden <block>`	`removehidden minecraft:copper_ore`	从隐藏列表移除
`/viperantixray addreplacement <block>`	`addreplacement minecraft:dirt`	添加到替代列表
`/viperantixray removereplacement <block>`	`removereplacement minecraft:dirt`	从替代列表移除
`/viperantixray listhidden`		显示当前隐藏方块
`/viperantixray listreplacements`		显示当前替代方块
`/viperantixray reload`		热重载 config.toml

支持标签： #c:ores、#minecraft:deepslate_ores、#viperantixray:honey_pots
否定： !#tag 从列表移除（从左到右处理）

命令参考

命令	别名	权限	描述
`/viperantixray`	`/vx`、`/antixray`	`viperantixray.admin`	显示帮助
`/viperantixray status`	`st`	`viperantixray.admin`	引擎状态、TPS、队列、工作线程
`/viperantixray inspect [on\|off\|toggle]`	`ins`	`viperantixray.inspect`	切换 X-ray 视觉
`/viperantixray audit <player>`	`aud`	`viperantixray.admin`	显示挖掘统计 & 可疑度
`/viperantixray auditlist`	`audl`	`viperantixray.admin`	前 20 名可疑玩家
`/viperantixray addhidden <block>`	`ah`	`viperantixray.admin`	添加到隐藏列表
`/viperantixray removehidden <block>`	`rh`	`viperantixray.admin`	从隐藏列表移除
`/viperantixray addreplacement <block>`	`ar`	`viperantixray.admin`	添加到替代列表
`/viperantixray removereplacement <block>`	`rr`	`viperantixray.admin`	从替代列表移除
`/viperantixray listhidden`	`lh`	`viperantixray.admin`	列出隐藏方块
`/viperantixray listreplacements`	`lr`	`viperantixray.admin`	列出替代方块
`/viperantixray reload`	`rl`	`viperantixray.admin`	热重载配置
`/viperantixray alerts`	`al`	`viperantixray.alerts`	查看蜜罐触发记录
`/viperantixray version`	`ver`		显示模组版本

默认权限： 所有 viperantixray.* 默认仅限 OP。使用 LuckPerms 授予员工角色。

性能基准

测试环境：i7-12700K、32GB DDR5-5600、Paper 1.21.1 基准、通过 Spark 分析器模拟 20 名玩家

场景	玩家数	模式	TPS 影响	堆内存	平均区块延迟
原版生存	20	3	<0.5%	+12 MB	1.2 ms
高人口	80	3	0.8%	+28 MB	2.1 ms
区块加载风暴	50	3	1.2%	+15 MB	3.4 ms
异步 + 剔除	100	3	0.6%	+35 MB	1.8 ms
TNT 连锁（100+）	30	3	1.5%	+8 MB	4.2 ms（批量）

安装

要求

Fabric Loader： 0.14.21+（1.21.x）/ 0.19.3+（26.x）
Fabric API： 与你的 Minecraft 版本匹配
Java： 21（1.21.x）或 25（26.x）

步骤

下载适用于你的 Minecraft 版本的 JAR
放入 mods/ 文件夹（仅服务端——不需要客户端）
启动服务器一次——生成 config/viperantixray-fabric.toml
如需可编辑配置（维度配置文件、蜜罐、分析等）
运行 /viperantixray reload 或重启
使用 /viperantixray status 验证

从其他反 X-ray 迁移

从 Paper/Spigot 原生

配置语法几乎相同（paper.yml → viperantixray-fabric.toml）
引擎模式 1:1 兼容
维度 ID：world → minecraft:overworld、world_nether → minecraft:the_nether，等等

从 Orebfuscator / EngineMode2 / AntiXray（Bukkit）

引擎模式直接映射
方块列表：复制 hidden-materials → hiddenBlocks、replacement-materials → replacementBlocks
不再有每世界 update-radius——现在是 TOML 中按维度配置

从客户端模组

无需客户端更改——ViperAntiXray 是 100% 服务端
从玩家整合包中移除客户端模组以减少混淆

故障排除 / 常见问题

Q：玩家看到“幽灵方块”/挖掘后方块重新出现
A：增大维度配置中的 updateRadius（默认 2）。高延迟玩家可能需要 3-4。检查 /viperantixray status 的异步队列深度。

Q：许多玩家加入时 TPS 下降
A：启用 async.enabled=true，增加 async.workerThreads，将 culling.marginSections 减少到 1。

Q：蜜罐未触发
A：验证 honeypot.enabled=true，检查 honeypot.minY/maxY 是否匹配世界高度，确保 hiddenBlocks 包含目标矿石。

Q：模组矿石未隐藏
A：在维度配置中添加到 hiddenBlocks，或在你模组的数据包中使用 #viperantixray:hidden_only_ores 标签。

Q：配置更改未应用
A：运行 /viperantixray reload——某些设置（引擎模式、方块列表）会热重载；维度添加/移除需要重启。