Xaero进阶雷达

Xaero 渐进式雷达

Xaero Progressive Radar 是一个 Forge 1.20.1 插件，它会在玩家完成配置的进度之前，隐藏 Xaero 实体雷达中选定的实体类型。

其渐进模型有意与 Revelationary 类似：数据包规则描述进度揭示的内容，进度是玩家状态的来源，客户端在收到 Minecraft 进度更新时重新计算可见性。

行为

• 未被任何雷达规则引用的实体类型不受影响，仅遵循 Xaero 自身的设置。
• 被引用的实体类型将被隐藏，直到玩家完成至少一个映射到它的进度。
• 撤销已完成的进度会再次隐藏该实体，除非另一条已完成的规则也映射到它。
• 规则按玩家区分，因为进度也是按玩家区分的。
• 在插件允许实体通过后，Xaero 自身的雷达类别、范围、图标和总开关仍然生效。

用集合符号表示，客户端计算：

隐藏 = 规则命名的所有实体类型
         - 已完成进度规则命名的实体类型

这有两个有用的结果。未配置的实体永远不会意外消失，重叠规则使用直观的 OR 语义。

要求和安装

• Minecraft 1.20.1
• Forge 47.x
• 每个客户端都需安装 Xaero 的小地图 23.6.1 或更新版本
• 服务端和每个客户端都需安装本插件
• Xaero 的世界地图是可选的

将构建好的 jar 放入服务端和客户端的 mods 目录。将雷达渐进规则放入世界中 datapacks 目录下的普通数据包中，然后运行 /reload 或重启服务端。

服务端配置生成于：

world/serverconfig/xaeroprogressiveradar-server.toml

其中仅包含 /progressiveradar 的权限等级。雷达可见性本身由数据驱动。

数据包规则格式

规则是位于以下路径的 JSON 文件：

data/<namespace>/xaero_progressive_radar/<path>.json

示例 data/modpack/xaero_progressive_radar/undead.json：

{
  "advancement": "modpack:progression/discovered_undead",
  "entity_types": [
    "minecraft:zombie",
    "minecraft:skeleton"
  ],
  "entity_type_tags": [
    "modpack:radar/tier_1"
  ]
}

字段：

字段	是否必需	含义
advancement	是	其完成状态将揭示所选实体的进度 ID。支持数据包和模组提供的进度。
entity_types	条件性	精确实体类型注册表 ID 的数组。
entity_type_tags	条件性	实体类型标签 ID 的数组，不带 #。

entity_types 或 entity_type_tags 中至少有一个必须存在且非空。两者可在一条规则中同时使用。未知实体 ID 只会展开为空，这允许规则引用可选模组中的实体。格式错误的规则会被跳过并在日志中记录其资源 ID。

实体类型标签

标签对于多个规则共享的等级非常方便。例如，创建 data/modpack/tags/entity_types/radar/tier_1.json：

{
  "replace": false,
  "values": [
    "minecraft:zombie",
    "minecraft:skeleton",
    "minecraft:spider"
  ]
}

在 entity_type_tags 中将其引用为 "modpack:radar/tier_1"。标签在服务端数据包加载后展开，然后具体的实体 ID 会发送给客户端。因此客户端不需要服务端数据包的副本。

多条和重叠规则

多个文件可以引用同一个进度；它们的实体选择会被合并。多个进度也可以引用同一个实体。在后一种情况下，任何一条已完成的进度都会揭示该实体：

规则 A：进度 modpack:first  -> 僵尸，骷髅
规则 B：进度 modpack:second -> 僵尸
均未完成 -> 僵尸和骷髅被隐藏
仅完成第二个 -> 僵尸可见，骷髅隐藏
任一规则完成使僵尸可见 -> 僵尸可见

如果需要严格的顺序等级，请在进度定义本身中表达该依赖关系。进度定义拥有所有等级依赖关系。

命令

命令默认需要权限等级 2。它们会修改映射进度的条件，遵循 Revelationary 的命令工具行为。它们从不写入雷达专属的解锁值。

面向实体的命令

实体选择器会被解析回所有已加载雷达规则选择它们的进度：

progressiveradar set @a minecraft:creeper true
progressiveradar grant @p minecraft:zombie
progressiveradar revoke @p minecraft:zombie
progressiveradar grant @s #modpack:radar/tier_1

grant/true 授予映射进度的所有条件；revoke/false 撤销所有条件。由于命令会改变进度本身，所有映射到同一进度的其他实体也会随之改变。当没有已加载规则映射该实体选择时，命令失败。

面向进度的命令

对于明确的数据包脚本，直接操作映射的进度：

progressiveradar advancement grant @p modpack:progression/discovered_undead
progressiveradar advancement revoke @p modpack:progression/discovered_undead

只接受已加载雷达规则引用的进度。Tab 补全会建议这些 ID。

授予所有条件会完成实际进度，并可能运行其奖励、奖励函数、公告或依赖条件。这是有意为之。当数据包只需要雷达专属里程碑时，请使用没有奖励的专用隐藏进度。

批量检查和查询命令

progressiveradar all @p true
progressiveradar all @p false
progressiveradar query PlayerName minecraft:skeleton
progressiveradar query PlayerName #modpack:radar/tier_1

all 授予或撤销所有被已加载雷达规则引用的进度。query 将未管理的类型与进度管理的类型分开，然后报告有多少管理类型已解锁或仍被隐藏。“未管理”表示本插件不过滤该类型；Xaero 自身的设置仍决定其是否被渲染。

普通的 Minecraft 命令同样有效：

advancement grant @p only modpack:progression/discovered_undead
advancement revoke @p only modpack:progression/discovered_undead

任何改变映射进度进度的机制都会产生相同的雷达结果。

同步设计

同步路径仿照 Revelationary：

1. 服务端重载监听器解析雷达 JSON 规则。
2. 实体类型标签根据实时服务端注册表展开。
3. 在登录和数据包重载时，服务端只发送 进度 -> 具体实体 ID 的映射。
4. 客户端监听 Minecraft 进度更新数据包并维护已完成的进度 ID 集合。
5. 客户端根据规则映射和已完成集合推导出隐藏的实体集合。
6. Xaero 的雷达实体可迭代对象会针对该不可变快照进行过滤。

数据包顺序不重要。如果 Minecraft 的初始进度数据包先到达，其完成 ID 会保留到规则映射到达。如果规则先到达，受管理的实体保持隐藏直到初始进度数据包被处理。登出会清除客户端的两个集合。

进度持久化、命令、同步和数据包重载行为保持权威性。

Xaero 小地图和世界地图兼容性

该插件支持 legacy 23.x 系列和较新版本使用的两种 Xaero 小地图雷达实现。Xaero 目前不提供公开的按实体雷达过滤回调，因此集成使用了两个可选的、范围狭窄的 mixin。每个只包装 Xaero 雷达更新器消费的 Iterable<Entity>。

Xaero 的世界地图确实有实体雷达渲染，但它不收集独立的实体列表。在全屏雷达渲染期间，它通过兼容层请求 Xaero 的小地图更新共享的雷达状态。因此过滤小地图雷达输入可以同时覆盖两者：

• 小地图实体雷达；
• 全屏 Xaero 世界地图实体雷达。

该插件不改变 ClientLevel 实体存储、实体追踪数据包、Minecraft 渲染、生成、AI、碰撞箱、命令或其他模组的实体查询。其他实体显示不受影响，除非它们有意消费 Xaero 自身的共享雷达状态。

数据包开发工作流程

1. 创建或选择拥有解锁的进度。
2. 在 xaero_progressive_radar 下添加一个或多个雷达规则文件。
3. 运行 /reload。
4. 检查服务端日志中的 Loaded <n> progressive radar advancement rule(s)。
5. 在授予进度前后使用 /progressiveradar query。
6. 测试授予和撤销；撤销行为能捕获过时客户端状态的错误。
7. 使用标签时，用数据包代表的所有可选模组组合进行测试。

完整示例可在 examples/xaero-progressive-radar-example 获取。

故障排除

• 实体始终可见：验证其确切的注册表 ID 是否被已加载规则选择，且 Xaero 的实体雷达本身已启用。
• 实体始终隐藏：使用 /advancement test 或 /progressiveradar query 验证进度 ID 存在且实际已完成。
• 命令改变了超出预期的实体：这些实体共享相同的映射进度。如果它们需要独立解锁，请将它们拆分到专用进度中。
• 标签未选择任何内容：验证文件位于 tags/entity_types 下，而不是 tags/entities，并在雷达 JSON 中省略 #。
• 规则未更新：检查服务端日志中的重载错误。无效的 JSON 规则会被跳过而不是部分应用。
• 解锁后世界地图仍不显示图标：Xaero 小地图自身的雷达设置和世界地图雷达选项仍需要允许这些图标。