斯威夫特地图

斯威夫特地图

SwiftMap 是一个 Minecraft 小地图/世界地图模组,围绕两个目标构建:快速渲染和低资源占用。

SwiftMap 迅捷地图 · 模组使用说明(中文)

版本 1.0.5

一、这是什么

SwiftMap 是一个 Minecraft 小地图 / 世界地图模组,主打「渲染快、资源占用低」。

核心设计是「1 方块 = 1 像素」的自绘瓦片地图:把已加载区块的地表颜色烘焙成瓦片文件存到磁盘,之后显示地图只需读瓦片,不再采样世界,因此对帧率几乎无影响。

同时提供区块操作(保存 / 粘贴)、路径点、临时高亮、结构标注等功能。

二、支持的版本

本包内含四个独立构建,请按你的游戏环境选择对应的 jar:

游戏版本 加载器 成品 jar
Minecraft 1.21.1 NeoForge swiftmap-1.0.5-mc1.21.1-neoforge.jar
Minecraft 26.3 NeoForge swiftmap-1.0.5-mc26.3-neoforge.jar
Minecraft 26.3 Fabric SwiftMap-1.0.5-mc26.3-fabric.jar
Minecraft 26.3 Fabric SwiftMap-1.0.5-bubbleworld-mc26.3-fabric.jar

注意:同一游戏版本只能装一个 SwiftMap。

泡世界版是 26.3-Fabric 的特化分支:检测到泡世界(bubbleworld)模组时自动关闭小地图与世界地图,只保留路径点。这是因为泡世界自己已在 HUD 上绘制大量世界结构信息,两套地图叠在一起既挡视线又做重复的事;而路径点是它没有的能力,保留下来才互补。

三、安装

  1. 确认已装好对应版本的加载器(NeoForge 或 Fabric)。
  2. 把对应的 jar 放进 .minecraft/mods/ 目录。
  3. 启动游戏。

依赖:

  • 26.3 版本需要 Java 25
  • 1.21.1 版本需要 Java 21
  • 26.3-Fabric 另需 Fabric API

首次启动会在 config/swiftmap-settings.json 生成默认设置。

四、主要功能

【小地图】

  • 屏幕角落的常驻小地图,可配置位置、尺寸(64~256)、缩放、朝向
  • 默认跟随玩家朝向,也可锁定正北向上
  • 底部显示当前坐标
  • 方位标记(东南西北)
  • 显示范围内的其他玩家、友好生物、敌对生物
  • 洞穴模式:单独采集洞穴层数据,可查看地下结构
  • 边缘平滑采样:不是硬边马赛克,方块之间有过渡
  • 地形明暗:山坡有立体感(见下方「地形明暗」说明)
  • 虚空显示为天空:空岛/虚空世界里,主世界无方块处画成淡天蓝
  • 实时跟随地形:放置/破坏方块后小地图会自动更新,不需要移动或重进世界

【世界地图】

  • 按 M 键打开(可在设置里改键)
  • 可缩放、可拖动浏览
  • 显示区块网格(可开关)
  • 显示群系边界(可开关)
  • 标注已发现的结构(村庄、要塞、矿洞等)
  • 显示刷怪笼、末地传送门等特殊方块的坐标

【路径点】

  • 在世界地图上右键添加路径点
  • 按 U 打开路径点管理界面
  • 新建路径点时坐标自动填入玩家当前位置
  • 支持命名、简介、图标、颜色
  • 可设为高亮,游戏中会在视野里显示方位标记
  • 每个路径点和高亮标记旁会显示到玩家的距离

【临时高亮】

  • 快速标记某个坐标,不需要建路径点
  • 支持命令:/swiftmap highlight <x> <y> <z>
  • 可一键清除全部

【区块操作】

  • 在地图上框选区块(最多 7×7 = 49 个区块)
  • 保存为 .smclip 文件,存在 <游戏目录>/swiftmap/clips/
  • 可粘贴到其他位置,支持三种对齐方式:原始坐标 / 自定义 Y / 对齐地表
  • 粘贴可选是否包含:空气方块、群系、实体、方块实体数据
  • 羽化过渡:粘贴边缘做渐变过渡,避免生硬接缝
  • 权限规则:

    • 存档:有玩家即可
    • 粘贴:需要创造/旁观模式,或拥有 GAMEMASTER 权限 (生存模式不能粘贴,防止误覆盖建筑)
  • 安全限制:

    • 不允许跨存档粘贴(dataVersion 不同会拒绝)
    • 不允许跨维度粘贴

【多语言】

  • 支持 10 种语言:简体中文、繁体中文、英语、日语、韩语、德语、法语、西班牙语、葡萄牙语(巴西)、俄语
  • 语言文件全部独立,无硬编码文本

五、设置项详解

按 K 打开设置,小地图页有以下可调项:

设置项 说明
开关小地图 总开关
显示位置 四个角任选
尺寸 64 / 96 / 128 / 192 / 256
缩放 0.5× ~ 4×(1 格对应多少像素)
朝向 跟随玩家 / 正北向上
显示坐标 底部是否显示当前坐标
显示方位 边缘是否显示东南西北
显示玩家/生物 各类实体的显隐
洞穴模式 单独采集与显示地下层
虚空显示为天空 仅主世界生效,把无方块处画成淡天蓝
地形明暗 0% ~ 200%,控制山坡立体感强弱

【地形明暗】

地图是正俯视,纯色块看不出高低。开启明暗后,按高度梯度给地表加亮度变化:假想光从西北方斜射,朝光的坡面变亮、背光的坡面变暗,于是山丘和悬崖有立体感。

默认 50%。觉得不明显可以拉到 100% 或 150%;觉得太夸张可以降到 25%。

重要:明暗是在采集时烘焙进瓦片数据的,所以改强度只影响之后新采集的区域。已有区域需要删除对应的 *.smr 瓦片文件才会重新计算(路径见「数据存放位置」一节)。

六、按键

按键 功能
M 打开 / 关闭世界地图(可在设置里修改)
K 打开 SwiftMap 设置界面
U 打开 / 关闭路径点管理
鼠标拖拽 在地图上平移
滚轮 缩放地图
右键 在世界地图上呼出菜单(加路径点 / 加高亮)

七、数据存放位置

路径 内容
<游戏目录>/swiftmap/clips/ 区块操作存档(全局,不分存档)
<存档>/swiftmap/dimensions/<维度名>/lod0/ 地表地图瓦片
<存档>/swiftmap/dimensions/<维度名>/lod0/caves/ 洞穴层地图瓦片
<存档>/swiftmap/waypoints.jsonl 路径点
<存档>/swiftmap/structures.jsonl 结构记录
config/swiftmap-settings.json 全局设置

瓦片按「容器」组织,一个容器 512×512 格(32×32 区块)。删除 lod0 下的 *.smr 即可让该区域重新采集,不影响路径点和结构记录。这也是让「地形明暗」强度改动生效的方法。

八、性能特性

  • 地图显示只读瓦片,不采样世界,帧时间恒定
  • 明暗在采集时烘焙进瓦片,显示时零额外开销
  • 采集在独立后台线程,每 tick 有硬预算(默认 8 个区块),不抢占渲染
  • 瓦片按 LRU 缓存打开的文件句柄,上限 32 个
  • 小地图只在「该重画」时才重画:玩家移动/转向/设置变化/瓦片更新,站着不动时完全不重算
  • 数据用 deflate 压缩,容器内定长槽位,随机读取

九、已知行为说明

【沼泽草色的成块差异】

沼泽群系的草色在原版就是「按噪声二选一」的硬切换(深绿 / 浅绿,周期约 44 格),不是连续渐变。地图按 1 方块 = 1 像素如实呈现,因此会看到成块的深绿/浅绿区域。这是原版特性,不是 bug,三个平台均按原版行为呈现。

【刚采集的区域可能颜色偏】

区块刚加载时周围邻区可能还没到位,地表颜色(草/叶色的群系着色)会略有偏差。该区块会在邻区加载完成后自动重采修正。

【地形明暗需要重采才生效】

见「设置项详解 · 地形明暗」。

十、问题排查

  1. 地图一片空白

    • 确认曾在该区域走动过(地图只记录走过的区域)
    • 检查 <存档>/swiftmap/dimensions/ 下是否有 lod0 目录
  2. 地图颜色发灰 / 像没加载

    • 多为该区域刚采集完,稍等或走动几格触发重采
  3. 小地图不跟随方块变化

    • 1.0.4 已修复该问题。若仍有问题,确认 jar 版本为 1.0.5
  4. 存档损坏风险

    • 模组只读写自己目录下的文件,不修改原版存档数据
    • 但区块操作会真实改变世界方块,粘贴前建议先备份存档
  5. 崩溃

    • 查看 logs/latest.log 与 crash-reports/
    • 提交问题时请附上完整日志

十一、版权

详见包内 LICENSE 文件。