Xaero的小地图 Xaero's Minimap

Xaero的小地图 (Xaero's Minimap)

这款模组能够在你的屏幕角落展开一副详尽的战术图表，实时显示周边的地形地貌、玩家动向、生物群落以及各类实体信息。它赋予你创建“路径点”的能力，指引你从容寻回曾经涉足的地点。

警示：切勿将 XaeroPlus 与本模组混用！

请务必注意，XaeroPlus 并非本人开发，且与官方毫无关联。该第三方插件会引发难以追踪的严重错误乃至游戏崩溃。更令人担忧的是，据称它与某些服务器破坏团伙存在瓜葛，这可能会导致你在服务器中的建筑成果面临极大风险。

与市面上众多同类模组不同，Xaero的小地图极其注重保留 原版 Minecraft 的美学风格，旨在成为游戏界面中浑然天成的一部分，而非突兀的附加组件。值得一提的是，它是 Minecraft 历史上首个采用旋转方形设计的地图模组。在极其丰富的自定义选项中，你依然可以选择传统的 圆形地图，或者设定 锁定地图旋转（转而使用方向箭头来指示方位）。

雷达系统能够以 自定义颜色的圆点 或 图标（通常是头像） 的形式，精准显示周围的实体，涵盖 玩家、生物及掉落物。除了提供基础的 指南针方位，你还可以自行部署 路径点，这些标记将在小地图和游戏世界中同步显现。路径点不仅能助你重返旧地或抵达特定坐标，更支持 传送功能。此外，该模组具备透视能力，能够显示地表之上的结构以及地下的深邃环境（即 洞穴模式）。

这仅仅是该模组众多特性中的冰山一角。为了全面了解其潜能，请详细阅读下方的“小地图特性”章节。为了适应多人服务器的规则环境，本模组提供了两个版本：完整版与公平竞争版（Fair-play），后者专为公平 PVP 环境设计。本模组主要在客户端运行。将其安装在服务端并非必须，但能解锁诸如“世界识别”等额外功能。

特性概览

• 完美复刻原版 Minecraft 的视觉风格。
• 提供多种小地图尺寸选项，包括自动调整模式。
• 具备多级缩放功能，视野掌控随心所欲。
• 两种地图形状可供选择：方形或圆形。
• 性能优化卓越，运行流畅度超越市面上绝大多数同类竞品。
• 通过“更改位置”设置，你可以将地图安置在屏幕的任意角落。甚至支持以 1 像素为单位的微调，这在与其他 UI 模组共存时尤为实用。
• 两种方块颜色模式：原版模式（采用原版地图颜色）和 精准模式（直接采用方块纹理和生物群系的颜色）。你还可以在原版模式下单独开启生物群系着色。
• 支持自定义按键（默认为 Z 键）暂时放大地图，以便更清晰地观察周围环境。所有按键绑定均位于原版控制菜单中。 此外，你还可以定制放大时的行为，例如让地图居中显示或自动切换至最大缩放级别。
• 通过“地形深度”和“地形坡度”设置，你可以自定义地图的阴影效果，增强立体感。
• 与 Xaero的世界地图 (Xaero's World Map) 完美兼容。默认情况下，它会直接调用世界地图模组生成的纹理，而非重复加载，从而在使用双模组时显著提升性能。
• 支持服务端配置，并提供游戏内 UI 界面。你可以实时管控服务器上玩家使用模组的权限。支持基于等级/权限系统的管理（xaero.minimap.enforced_server_profile），兼容 FTB Ranks、Odyssey Roles、LuckPerms 以及通用权限 API。
• 支持通过绑定特定物品来限制小地图的使用。例如，在配置文件中添加 minimapItemId:minecraft:compass，即可实现只有当玩家在快捷栏持有或装备指南针时，小地图才会显示。
• 引入药水效果机制，用于控制服务器/地图中玩家的小地图功能权限。目前支持的效果包括：xaerominimap:no_minimap（禁用地图）、xaerominimap:no_entity_radar（禁用雷达）、xaerominimap:no_waypoints（禁用路径点）、xaerominimap:no_cave_maps（禁用洞穴图）。这些效果默认为中性，但你也可以通过在 ID 后添加 _harmful（如 xaerominimap:no_entity_radar_harmful）将其指定为有害类型。
• 已被翻译成多种语言，打破语言壁垒。
• 支持 锁定北方 选项，停止地图旋转，转而用箭头指示角色朝向。
• 得益于 自动洞穴模式，无论是地表还是地下探索均能应对自如。该模式在进入建筑物内部时也应能自动激活。你可以自定义触发洞穴模式所需的“实体屋顶”尺寸。例如，设置 3x3 及以上的屋顶尺寸，可以防止你在砍树站在原木下时误触洞穴模式。
• 路径点系统。支持创建几乎无限数量的路径点。若拥有传送指令权限，可直接传送至路径点。这些标记将在游戏世界内渲染并在小地图上高亮。你可以隐藏全部或特定的路径点。按 B 键创建新路径点，按 U 键列出所有路径点。在列表中，你可以管理单点或多点，进行排序，或查看其他子世界/维度的路径点。
• 局部与全局路径点机制。 为了避免屏幕杂乱，你可以创建受“最大绘制距离”限制的局部路径点。这允许你为大区域设置一个全局路径点，而在区域内部设置多个局部路径点。当你超出绘制距离时，仅全局路径点可见。
• 路径点集管理。 你可以通过将路径点归类到不同的“集”中来组织它们，并通过按键快速切换当前的路径点集。所有按键绑定均在原版控制菜单中。
• 路径点分享功能。 你可以在游戏聊天栏中与服务器上的其他玩家分享你的路径点，此操作在路径点列表（按 U）中进行。
• 死亡标记。每次角色死亡时，系统会自动在死亡地点创建一个 骷髅形状的路径点。旧的死亡点会自动转换为普通路径点，如果不希望保留，可以通过“保留旧死亡点”设置将其禁用。
• 支持显示来自 Open Parties and Claims 模组的区块声明和盟友玩家。
• 可切换的 区块网格。网格线将清晰标示区块的起始与结束位置。
• 可切换的 史莱姆区块 模式。能够生成史莱姆的区块将覆盖绿色显示。
• 自定义光照覆盖层。你可以设置一个光照覆盖层，用自定义颜色标记特定光照范围内的方块（默认为 0 到 7）。此功能本来用于寻找怪物生成的温床，但你也可以将其用于任何用途。
• 多人游戏中的多世界检测。若在服务端同时也安装了本模组，每个服务器世界不仅会有独立的世界地图，还将拥有独立的路径点“子世界”。若未能安装服务端模组，则会采用基于世界出生点的可靠性较低的分离方案。如果服务器只有一个“单一世界”，建议关闭多世界检测。此选项位于 路径点菜单（按 U） -> 选项 界面。
• 生物雷达：在地图上将 生物 显示为 黄色圆点。敌对与友好 生物可配置 不同颜色。亦支持显示为 图标/头像。请查阅 “实体雷达” 设置。
• 玩家雷达：在地图上将 玩家 显示为 白色圆点或玩家头像。亦支持显示为 图标/头像。请查阅 “实体雷达” 设置。
• 物品雷达：在地图上将 掉落物 显示为 红色圆点。请查阅 “实体雷达” 设置。
• 显示所有 其他实体（如箭矢和物品展示框）为 紫色圆点，且支持在设置中禁用特定类型的实体。请查阅 “实体雷达” 设置。
• 在“实体雷达”设置中，提供 在小地图上显示实体名称 的选项。
• 支持放大和缩小按键 （默认为 I 和 O），以便高效调整缩放级别以适应你的使用场景。
• 小地图下方显示 坐标。
• 小地图下方显示 当前生物群系名称。默认禁用，需在设置中开启（按 Y）。
• 小地图下方显示 光照等级。同样默认禁用，需手动开启。
• 小地图下方显示 当前游戏时间。默认禁用，支持 12 小时制和 24 小时制。
• 小地图下方显示 当前视角角度。默认禁用。
• 支持一键隐藏/取消隐藏所有界面中的路径点坐标，这对于直播或视频录制非常有用。
• 支持完全隐藏/取消隐藏下拉菜单中提及的所有服务器地址。默认设置为“部分隐藏”，这在大多数情况下能够提供足够的隐私保护。
• 海量设置选项。功能繁多，不胜枚举。请在游戏中按 Y 键打开设置界面亲自探索。
• 两个模组版本：完整版与公平竞争版。完整版 功能无限制。公平竞争版 不显示任何实体或洞穴地图，更适合与不使用小地图的玩家进行 PVP 对抗。

常见问题解答 (FAQ)

为何路径点传送功能对我失效？

造成此现象的原因可能多种多样。该模组通过发送聊天命令来执行传送操作，默认指令为 /tp @s x y z，因此你必须拥有相应的权限。原版的 /tp 命令通常需要管理员权限（作弊开启），但在非原版服务器上，通过特定插件可能拥有独立的命令权限。如果是指令不匹配，你可以在小地图设置中的“默认传送命令”选项，或在路径点菜单的“传送聊天命令”选项中（针对特定服务器）进行更改。非原版传送指令通常不支持 @s 这样的选择器，因此你可能需要从配置的命令中移除它。此外，世界地图上的右键传送使用的是另一套独立设置，详情请参阅世界地图说明页面的 FAQ。

如果“传送”按钮呈现为灰色禁用状态，这也暗示了多种可能性。最常见的原因是你正在尝试使用并非来自当前“自动（auto）”子世界、但同属一个维度的路径点。如果当前的“自动”子世界并非你应该使用的那个，请手动选中正确的子世界，并在路径点菜单的选项中点击“设为自动子世界（Make Sub-world Auto）”。这将交换两个子世界的数据，使你能够传送到现已归入“自动”子世界的路径点。

若“自动”子世界选择无误但按钮依旧禁用，那很可能是服务器或该世界手动禁用了传送功能。请检查路径点菜单选项中的传送开关。如果确被禁用，你只能通过修改游戏目录下 xaero/minimap（旧版本为 XaeroWaypoints）文件夹中的服务器特定配置文件来启用它。强烈建议在编辑任何配置文件前退出 Minecraft，并养成定期备份的习惯。

为何我的路径点在特定服务器上神秘消失了？

请保持冷静，你的数据几乎肯定没有被删除。如果你同时使用了世界地图模组且地图也发生了重置，请务必先参照世界地图描述页面 FAQ 中的 “为何我的世界地图在特定服务器‘重置’了？” 一节进行恢复。如果已完成该步骤，请继续阅读。

首先，按 U 键打开完整的路径点菜单（若 U 键无效请检查原版控制设置）。浏览右上角下拉菜单中列出的子世界。当前服务器地址的所有路径点子世界都应罗列于此。如果其中没有任何一个包含你当前所在维度的数据，那么很可能是服务器地址发生了变更。请在 左上角 的下拉菜单中找到旧的服务器地址，选中它，然后执行 选项 -> 设为当前世界/服务器（Make World/Server Auto）。此时，你应该能在右上角的菜单中找到正确的子世界了。如果该子世界已被标记为 (auto)，意味着它已被自动选中，那么问题应当已解决。若标记为 (auto) 的是错误的子世界，请继续阅读。

<ins>正在使用世界地图模组？</ins> 导致错误子世界被自动选中的最常见原因之一，是在多人游戏中未能正确使用世界地图模组（自 1.6 版本起）。请务必在确认前为当前世界选择正确的地图，这直接决定了哪些路径点会对你可见。地图选择菜单位于世界地图界面的左下角图标（除非默认已打开）。如果服务器环境允许，建议将地图选择模式更改为自动模式之一。 你当前确认的地图决定了哪个路径点子世界被视为“自动”。这允许每个创建的地图拥有独立的数据。在任何时候，你都可以通过路径点菜单（按 U）右上角的下拉列表查看非自动的子世界。若要将任意子世界绑定到当前地图并设为自动，请选择 选项 -> 设为自动子世界。

<ins>未使用世界地图模组？</ins> 如果错误的子世界被视为 (auto) 并自动选中，这通常是由于服务器插件改变了原版指南针的行为，从而干扰了模组的“多世界”检测功能（如果已开启该功能，默认是关闭的）。在此类情况下，指南针通常指向玩家床的位置而非世界出生点。如果是睡在另一张床上导致路径点消失，只需重新睡回原本的床通常能修复问题。 如果是由于新添加的插件导致（且无法移除该插件），你可以按以下步骤恢复路径点：

1. 在路径点界面的右上角下拉菜单中找到包含你所需数据的正确“子世界”（先从主世界尝试）。
2. 使用 选项 -> 设为自动子世界。
3. 对每个维度重复此操作（操作前需先进入对应维度！）。
4. 如果这是一个简单的单世界服务器（没有大厅世界、小游戏世界、创造地皮世界等），请在同一 选项 菜单中关闭“多世界检测”。日后若有需要，可随时重新开启。

如有疑问，请随时联系我！

如何添加自定义实体图标或覆盖默认图标？

首要前提是：请确保你已在 小地图设置 -> 实体雷达类别 中启用了实体图标/头像显示，无论是设为“总是”还是“玩家列表”。你必须先知道如何显示它们，本节内容才对你有意义。

从模组版本 21.6.0 开始，你可以通过制作资源包（或将其包含在你自己的模组中）来用自定义精灵图/图像覆盖实体的默认图标。此外，你还可以通过编写简单的模组或代码，为实体变体（即同一种实体的不同形态拥有不同图标）添加或改进支持。不过，对于大多数简单的多变体实体类型而言，这通常是不必要的。 默认情况下，小地图模组使用绑定到实体的渲染器/模型来渲染所有图标。这支持所有原版生物以及一些头部模型部件易于识别（如头、耳、鼻等）的简单双足/四足生物。如果模组无法识别，则会退而求其次显示彩色圆点。

用于覆盖图标的相关资源目录位于 /assets/xaerominimap/entity/icon/。你可以在模组的 jar 文件中找到此路径并提取文件作为参考。jar 包内包含一个示例文件 /assets/xaerominimap/entity/icon/definition/example_mod/example_entity.json，用于演示如何覆盖模组实体的图标。该文件对应假设存在的实体类型 example_mod:example_entity。请仔细阅读 example_entity.json 中的注释，了解其结构，以便创建你自己的图标定义文件。 此外，/assets/xaerominimap/entity/icon/definition/minecraft/ 目录下包含多个原版实体类型的示例文件，其中可能包含关于默认实体变体支持的额外说明。默认情况下，实体变体支持非常简单，变体 ID 仅仅是实体的主纹理资源位置。 如果你在小地图配置文件中将 debugEntityVariantIds 选项设为 true，那么新遇到的实体（变体）的变体 ID 将会打印在聊天栏和日志/控制台中。

从版本 21.8.0 开始，你还可以配置自定义的基于模型的渲染。请阅读示例文件 /assets/xaerominimap/entity/icon/definition/example_mod/example_entity.json 中的注释以获取所需的全部信息。

如果你想查看自定义图标的实际应用案例或直接使用它，请查看 babybluetit 的这个精彩项目：https://www.curseforge.com/minecraft/texture-packs/xaeros-minimap-modded-support

如何在我的服务器上禁止使用洞穴模式和/或实体雷达？

要实现此目的，请在服务端安装本模组（撰写本文时需 NeoForge/Forge/Fabric/Quilt 服务端）。

如果你的小地图版本至少为 25.3.0，请设置并使用“小地图服务器设置”按键绑定来打开服务器设置界面。你可以在那里强制执行几乎任何选项，包括洞穴模式、实体雷达，甚至创建自定义实体雷达类别。

在旧版本模组中，当你启动服务器时，服务器目录（非世界文件夹）的 config 文件夹中通常会生成一个新的“common”配置文件。在该文件中，你可以找到多个选项来禁用玩家的特定模组功能。更改后需要重启服务器。

另外，如果你无法安装该模组，可以在玩家登录时发送包含以下字符串的服务器/系统消息，这些隐藏代码将触发相应功能：

§f§a§i§r§x§a§e§r§o - 强制客户端禁用洞穴模式（包括世界地图）和实体雷达（公平竞争模式）。

§x§a§e§r§o§m§m§n§e§t§h§e§r§i§s§f§a§i§r - 允许小地图洞穴模式在下界工作，即便处于公平竞争模式下。世界地图有一个几乎相同的独立代码。

§n§o§m§i§n§i§m§a§p - 完全禁用小地图。

§r§e§s§e§t§x§a§e§r§o - 重置所有系统消息标记。

这里有一个第三方 Spigot 插件可简化此操作（非本人制作）：XMMForceFairPlay 以及一个具有类似功能的第三方数据包（非本人制作）：Xaero's Map Server Utils 使用任何第三方插件风险自负。

安装了模组的服务器如何允许原版客户端玩家加入？

请在服务器目录（非世界文件夹）下的 config 文件夹中找到“common”配置文件，通常路径为 config/xaero/minimap。其中有一个选项允许你 禁用状态效果的注册，正是这种状态效果注册阻止了原版玩家的加入。更改设置后需要重启服务器。如果使用了世界地图模组，也请执行相同的操作。

开发者指南

若想将你的模组与本模组挂钩，首先请将以下仓库添加到你的构建脚本中：

repositories {
    maven {
        url "https://chocolateminecraft.com/maven"
        name "Xaero's Maven"
    }
}

如果你使用的是 Forge，请确保在你的项目中应用了 Mixin gradle 插件 (org.spongepowered.mixin)，除非你的版本是 1.12.2。

最后，添加以下一个或多个依赖声明，请将 <minecraft version> 和 <mod version> 替换为 https://chocolateminecraft.com/maven/xaero/minimap 页面上显示的实际值。

Forge (使用 1.21.1 之前的官方 Mojang 映射):

implementation "xaero.minimap:xaerominimap-forge-<minecraft version>:<mod version>:dev"//特意不进行反混淆！

Forge (使用 1.21.1 及之后的官方 Mojang 映射):

implementation "xaero.minimap:xaerominimap-forge-<minecraft version>:<mod version>"

Forge (使用其他映射):

implementation fg.deobf("xaero.lib:xaerolib-forge-<minecraft version>:+")
implementation fg.deobf("xaero.minimap:xaerominimap-forge-<minecraft version>:<mod version>")

Fabric:

modImplementation "xaero.minimap:xaerominimap-fabric-<minecraft version>:<mod version>"

NeoForge:

implementation "xaero.minimap:xaerominimap-neoforge-<minecraft version>:<mod version>"

在多加载器设置中的“common”项目里:

compileOnly "xaero.minimap:xaerominimap-common-<minecraft version>:<mod version>"