RufusMap – WorldMap & Minimap

RufusMap 世界地图与小地图模组 – 适用于 Minecraft 1.21.1 / NeoForge

RufusMap 集方形或圆形小地图、持久化世界地图、带纹理的地形、自动洞穴图层、路径点、由服务器管理的领地和区块加载于一体。可选集成可连接 FTB Teams 和 Waystones。其地图绘制和领地管理系统可独立于 Xaero’s Minimap、JourneyMap 和 FTB Chunks 运行。

当前界面采用受 Frutiger Aero 启发的蓝青色调、玻璃风格面板、青柠色点缀、自定义图标按钮以及 Minecraft 当前使用的字体。此 Beta 版本新增了深度图层，并进行了一些改动以降低地图渲染开销。目前仍在开发中；兼容性和性能取决于整合包及运行环境。

相较最初 Alpha 版本的主要改进

• 方形或圆形小地图、玩家方向箭头、指南针和可配置的方块纹理。
• 自定义玻璃风格界面、紧凑工具栏和路径点提示。
• 地形颜色根据方块模型纹理、透明度和生物群系色调生成，并在近距离缩放时显示纹理细节。
• 自动或手动切换洞穴图层，每层间隔 16 格，包括负 Y 高度。
• 原版生物专属图标、通用备用图标，以及可配置的雷达图标数量上限。
• 区块加载队列、附近方块变更刷新、后台读取地图图块，以及平移或缩放时降低细节渲染。

依赖项

开发早期测试过的集成版本（本 Beta 版本尚未重新验证）：FTB Teams 2101.1.11、FTB Library 2101.1.37、Architectury 13.0.11、Waystones 21.1.46 和 Balm 21.0.66。其他版本需要单独检查兼容性。

操作

可在 Minecraft 的“控制”菜单中更改游戏操作按键。在世界地图界面中，也可以直接使用 Page Up 和 Page Down。小地图切换键默认未绑定。也可在 NeoForge 的“模组”界面中打开设置。

地图绘制与地形纹理

RufusMap 会记录客户端实际接收到的区块地形；未知地形会保持暗色。地图按世界/服务器标识和维度分别存储。如果服务器安装了 RufusMap，其持久化世界标识可区分托管在同一地址的不同世界。仅客户端进行地图绘制时，则会使用服务器地址作为备用标识。

新加载的区块会进入去重更新队列。附近方块发生变化时，也会将更新加入队列。默认情况下，系统会持续重新扫描玩家周围 3×3 区块范围；方块变更触发的刷新范围会稍微更大。远处已缓存的地形可能会保持不变，直到再次加载或扫描。更新是增量进行的，速度取决于队列和客户端负载，并不保证立即刷新。

地形颜色会优先使用方块模型的顶面，并结合透明度加权采样、生物群系染色和海拔明暗效果。水会使用对应的生物群系颜色。无法读取的模型或特殊模型则会回退为粒子贴图或地图颜色。

启用 方块纹理 后，近距离视图会添加取自当前资源包的 16×16 纹理细节。世界地图的细节从每方块 4 像素的比例开始；世界地图缩放范围为 25% 至 3200%。小地图在较近的纹理缩放级别下也可显示细节。较早生成的纯颜色图块会在重新扫描时补充方块 ID。纹理细节使用方块默认状态的模型，因此不会呈现所有朝向、变体或自定义方块实体渲染效果。

颜色、高度和方块 ID 会以压缩图块的形式存储在 `<instance>/rufusmap/<world-hash>/` 下，并使用 `blocks.json` 调色板。渲染请求会在后台线程中读取磁盘图块，内存图块缓存上限为 12,288 条。拖动或缩放时，世界地图会临时使用较粗略的采样，随后再以完整细节重绘。如果小地图所跟踪的输入没有变化，就会复用现有图像。这些属于实现方式，并非经过测量的 FPS 保证。

1## 洞穴图层

洞穴地图按 **16 格高的垂直切片**绘制，例如 Y -16 至 -1 或 Y 0 至 15。在每个切片内，扫描器会尽可能跳过实心天花板，并在开口下方寻找地面。实心柱体会显示得更暗，而在该切片内没有地面的柱体则保持暗色。这是切片地图，并非完整的 3D 洞穴重建。

洞穴图层有三种模式：

• 关闭：自动选择将始终停留在地表。
• 自动：当玩家头顶检测到至少连续三格实心遮挡方块时，跟随玩家所在的切片。树叶不计入检测。检测不到顶层后，地图会返回地表。
• 始终：无论是否检测到顶层，始终跟随玩家所在的洞穴切片。

按 Page Up、Page Down，或使用世界地图右侧的按钮手动选择图层。自动图层按钮会恢复跟随模式。手动选择会覆盖自动模式，直到重置为止。在下界和其他有顶层的维度中，自动模式会保持常规地形视图；这些维度的常规视图会扫描顶层下方。

单人游戏和纯客户端模式均可使用洞穴图层。在运行 RufusMap 的专用服务器上，需设置 `allowCaveMap=true` 才能使用。新洞穴数据会存储在 `s<Y>` 目录中，与旧版洞穴缓存布局分开。

如果带有矿石标签的矿石顶面被遮挡方块覆盖，显示时会以近似的宿主岩石外观呈现。暴露在外的矿石仍可能可见。这只是显示规则，并非服务端反 X 光系统。

小地图、世界地图与雷达

小地图支持方形和圆形外观，并可选择旋转、调整大小、位置、透明度和缩放。它会显示玩家朝向、罗盘信息、坐标、生物群系、维度、路径点，以及最近的 HUD 路径点距离。领地覆盖层只显示在世界地图上，不会显示在小地图上。

世界地图包含领地、已加载领地高亮、路径点标签和悬停详情、队友标记、维度选择、区块坐标及缩放读数。可选网格会显示区块边界，每隔 512 格会以更粗的线条标示。玩家身处主世界时，会显示主世界出生点标记。个人路径点也可以作为投影标记显示在游戏画面中。

实体雷达会为受支持的原版生物和玩家使用专属图标，并为敌对和被动生物提供通用图标。世界地图上的实体图标会在玩家当前维度的缩放比例达到 50% 时显示。仅会检测客户端可见的生物实体；隐形实体和旁观者不计入。雷达不会单独按洞穴层的 Y 坐标筛选实体。

每种图标类别的默认生物上限为 24，可设置为 8、16、24、48 或无限。优先显示附近的实体，玩家不受上限限制。共用同一通用图标的模组实体也共用该上限。运行 RufusMap 的服务器可以禁用雷达。图标 PNG 文件可以通过资源包替换。

路径点

路径点支持名称、坐标、十六进制颜色、类别，以及钻石、旗帜或十字图标。小地图、世界地图和游戏内显示可分别控制。临时路径点仅在当前会话中保留。死亡时会创建单独的红色路径点。

使用管理器可按名称、类别或维度搜索，编辑个人路径点、删除路径点，以及复制团队位置。在编辑器中，共享对象栏留空会与团队共享；输入在线玩家名称则会向该玩家发送个人副本。删除团队路径点会影响团队共享条目。共享条目可以复制并在本地编辑；不支持直接编辑共享条目。

领地与保护

领地由服务器管理，保存在世界的 `data/rufusmap.dat` 文件中，并与客户端同步。服务器会根据所有权和权限检查领地变更。权限等级为 2 的管理员可以管理其他领地。

已实现的保护包括：方块破坏与放置、多方块放置、常见的方块/物品/实体交互、农田践踏、玩家攻击非玩家实体、受保护区块内的 PvP、爆炸效果、生物破坏检查，以及跨越所有权边界的活塞移动。原版流动液体无法从其他领地流入某个领地。

领地设置允许配置访客访问、PvP 和 FTB Teams 盟友权限。请站在当前团队拥有的领地内修改这些设置。此测试版中的访客访问权限同时控制建造和交互。团队成员可以管理团队的领地和共享路径点。启用了访问权限的盟友可以使用该领地，但不能管理其所有权。

第三方机器、假玩家、自定义武器、火焰蔓延、方块转移机制和自定义破坏行为需要针对具体整合包逐一验证。本版本不保证能全面防护所有模组中的每种机制。

区块加载

强制加载的领地会在世界地图上高亮显示。RufusMap 使用自己的 NeoForge 加载票据控制器，不会移除其他模组的加载票据。区块必须已被圈入领地才能加载。

服务器配置控制团队上限和离线加载。默认情况下，领地所属团队中有成员在线时，其已加载的领地才会保持激活。状态每五秒同步一次。启用离线加载后，选定的区块可在其所有者离线时继续保持激活。重启后，加载票据会根据已保存的领地重新构建，协调延迟最长可达五秒。

团队与共享探索

FTB Teams 通过自身的命令和界面提供成员管理、队伍管理和盟友关系。RufusMap 使用 FTB 团队 ID 来管理所有权、共享上限、队友标记和共享路径点。若未安装 FTB Teams，每位玩家拥有个人所有权。

只有在服务器启用后，队友位置才会同步。旁观者和隐身的队友不会显示。实时地形共享需要在客户端设置中主动启用，也需要服务器授权。在此测试版中，它会将附近地表区块的颜色和高度信息发送给当前在线且启用了共享功能的队友。发送的地形共享数据不包含洞穴切片和方块 ID 贴图数据。此功能不提供服务器范围的历史地图存档或批量地图合并。离开队伍后，玩家本地缓存中已接收的探索记录仍会保留。

## Waystones

服务器会定期发送玩家已激活收藏中的 Waystones。无效的 Waystones 不会显示。地图会列出名称、坐标和维度，并在同步时更新列表。

要从地图开始旅行，玩家必须处于与起点相同的维度内，且距离已激活的 Waystone 不超过四格。RufusMap 会通过 Waystones 的默认传送上下文和常规传送 API 传递起点与目的地。费用、要求和维度规则仍由 Waystones 控制。此测试版不支持使用 Warp Stones、Warp Scrolls 或物品栏传送按钮发起地图旅行。

## 配置

• 客户端偏好设置：`<instance>/config/rufusmap-client.json`。
• 服务器规则：`<world>/serverconfig/rufusmap-server.toml`。
• 个人航点：`<instance>/rufusmap/<world-hash>/waypoints.json`。
• 导出文件：`<instance>/rufusmap-exports/`。

此测试版中，每个世界的 RufusMap 领地全局上限为 2,048 个，每支队伍最多可共享 128 个航点。更改领地上限不会自动删除已有领地。队伍颜色会根据队伍 ID 以一致的方式生成，而不是复制 FTB Teams 选定的显示颜色。

管理员航点传送需要权限等级 2 以及 allowOperatorTeleport=true。传送目的地为所选维度中的地表位置，与 Waystones 旅行功能相互独立。此功能并非生存模式下的快速旅行功能。

命令

• rufusmap — 简要帮助。
• /rufusmap claim — 认领你所在的区块。
• rufusmap unclaim — 在获得许可时移除该领地。
• rufusmap load — 启用该领地的区块加载。
• rufusmap unload — 禁用该领地的区块加载。
• rufusmap admin clear <chunkX> <chunkZ> — 仅限管理员在执行玩家当前所在维度中移除领地。
• ftbteams — 安装后可打开 FTB Teams 自带的队伍管理界面。

当前实现限制

• 特殊模型、方块实体、依赖状态的纹理和高透明度方块可以使用近似效果或纯色回退。动画纹理使用固定帧。
• 洞穴地图会显示每列在一个 16 格切片内的地面，而不是所有重叠的隧道。自动检测也可能将厚实的建筑屋顶识别为地下覆盖层。
• 雷达基于客户端可见的生物实体，且不受所选洞穴层限制。
• 夜间视图使用较暗的调色板；它不会计算光照或生成安全性。
• PNG 导出会保存当前地形纹理，不含标签或领地覆盖层。它不会拼接整个已探索世界。
• 领地访问权限涵盖建造和交互。尚未实现精细到每个方块的权限及按等级管理。
• 不会导入现有的 FTB Chunks 领地以及 JourneyMap/Xaero 地图数据。保护设置独立于 FTB Chunks。
• 地形共享会发送地表颜色和高度，而非完整的历史地图或详细的方块纹理档案。
• 不包含浏览器/网页地图、路线查找、定时区块加载过期功能或完整翻译的界面。按键绑定翻译包含英语和巴西葡萄牙语。
• 在将此 Beta 版描述为稳定版，或称其功能与成熟的地图模组相当之前，还需要在更广泛的多人游戏、整合包、资源包和性能环境中进行验证。

构建与开发测试

使用 JDK 21，然后运行：

“`powershell
.\gradlew.bat build

The result is written under `build/libs/`. Normal development launches:

powershell
.\gradlew.bat runClient
.\gradlew.bat runServer

`build` executes the JUnit tests. The bundled JUnit Platform standalone JAR is used only by tests and is not included in the mod. Its license notices are embedded inside that test JAR.

The `-Psmoke` development profile uses separate `run-server` and `run-client` folders, an isolated localhost-only server on port 25574, and automated checks enabled by `rufusmap.selftest`. The server's test profile is offline solely for local development. Do not reuse its `server.properties` for a public server.

powershell
.\gradlew.bat runServer -Psmoke
.\gradlew.bat runClient -Psmoke

The automated client records screenshots and closes itself. The smoke setup can place test Waystones and edit the disposable test world. To stop the smoke server gracefully, create an empty `run-server/rufusmap-stop-test` file; delete it before starting another test. These actions are disabled unless the smoke system property is explicitly set.

### Validation of the latest 0.6.5-beta build

The latest supplied source ZIP compiled successfully with JDK 21 and NeoForge 21.1.256. Both included JUnit tests passed, with no skipped tests. They cover core coordinate/claim rules and persistent world identity; they do not verify the new cave renderer, UI or frame-rate performance.

The smoke-test profile is available, but it was not run for this latest beta compilation. Earlier client/server smoke tests must not be presented as runtime validation of this build. The newly compiled JAR has not been launched through PrismLauncher in this compilation session.

## Project structure

text
src/main/java/dev/rufusmap/          模组入口、模型、网络通信、存档数据和服务器规则
src/main/java/dev/rufusmap/client/  地形/纹理缓存、洞穴图层、小地图、雷达和自定义界面
src/main/java/dev/rufusmap/mixin/    流体边界保护和客户端地形更新钩子
src/main/resources/                NeoForge 元数据、按键翻译、界面精灵图、实体图标和徽标
src/test/java/                    核心回归测试
gradle/wrapper/                    Gradle 包装器
“`

RufusMap 与 Xaero’s Minimap、JourneyMap、FTB Chunks、FTB Teams 或 Waystones 的作者无关，也未获得他们的认可。

 
RufusMap 团队