旅行地图（Survivalcraft Travel Map）

Survivalcraft Travel Map（SCTM）是一个功能完整的旅行地图 Mod，提供两个版本：

• 联机版（.netmod）：面向 Survivalcraft 联机版（NetMod），支持单人、主机与联机客户端，并额外提供多人邀请传送和服务器权威的远程坐标传送。
• 插件版（.scmod）：面向 Survivalcraft 插件版（SurvivalcraftApi），单人游玩。

两个版本共享同一套地图核心，均提供：持久化探索地图（含洞穴分层投影）、小地图与全屏大地图、完整 XYZ 坐标点、死亡地点标记、安全本地传送、日夜明暗、地形明暗分级、多种小地图朝向/形状/独立罗盘方向，以及手机/触屏操作支持。联机版在此之上还有多人邀请（电脑端按 N 打开邀请面板）与服务器权威的远程坐标传送；插件版不含任何联网功能（无邀请、无远程传送、无服务器设置），其余功能均可用。

安装

请根据你玩的游戏版本选择对应的 Mod 文件，两者不通用。

联机版（.netmod）

1. 退出游戏。
2. 将 SurvivalcraftTravelMap.netmod 作为独立文件放入游戏目录的 NetMods 文件夹（不要覆盖其他 Mod 文件）。
3. 启动游戏并进入世界。

远程联机坐标传送要求服务器也安装相同版本的 SCTM。只在客户端安装时仍可查看地图，但地图右键传送和坐标点传送不会由客户端直接修改玩家位置。联机版的单人世界实际以 WorkType.Server 集成主机运行；主玩家仍会创建地图界面，坐标传送则在同一进程内由服务器权威执行。

插件版（.scmod）

1. 退出游戏。
2. 将 SurvivalcraftTravelMap.scmod 放入插件版游戏目录的 Mods 文件夹。
3. 启动游戏并进入世界。

插件版为单人版本，不含多人邀请、远程坐标传送和服务器设置；地图、本地安全传送、坐标点、死亡标记、洞穴投影等其余功能均可用。当前随包提供 zh-CN / en-US / pt-BR / ru-RU 语言，其余语言会随翻译进度补充。

版本兼容

版本	目标	兼容范围
联机版（.netmod）	Survivalcraft 联机版，引擎 2.4.0.0（modinfo ScVersion 2.4.40.6），NetMod API 1.44	联机版按引擎程序集兼容，不用版本号严格卡。近期的 2.4.0.0 引擎日期构建（如 26.05–26.07）基本通用；只有当某个构建改动了引擎程序集时才需重新构建。
插件版（.scmod）	Survivalcraft 插件版（SurvivalcraftApi），modinfo ApiVersion 1.9.2.1	插件版按声明的 API 版本判定：1.9.2.1 表示该版本及以上（含 1.9.3）。低于 1.9.2.1 会提示不兼容。

联机版客户端在启动器里显示的是日期式发布号（如 26.07.01.01），那不是 API 版本；API 版本只在游戏日志的 Api Version: 行显示。两个版本各是独立构建，1.44 与 1.9.x 是不同的版本体系，不能互换。

操作

• 小地图：默认逻辑尺寸为 160，显示已探索地形、玩家方向、坐标点、可选 XYZ 坐标、游戏时间、生物标记和最近一次死亡地点。死亡地点使用骷髅图标；发生新死亡后地图只显示最新位置。支持北方朝上/行进方向朝上、圆形/方形/圆角方形、独立罗盘方向和字号。捕食者、鸟类和其他生物分别显示为红、黄、绿色。可用鼠标或触摸调整位置；轻触小地图或按 M 均可打开大地图。
• M：打开或关闭大地图；聊天输入、文本输入或其他模态对话框占用焦点时不会触发。背包、角色、合成、睡眠、大地图或其他模态界面出现时，小地图和邀请图标会自动隐藏，关闭后按原设置恢复。
• 屏幕左上角的“地图”按钮：始终显示的开图入口，主要面向没有 M 键的手机/触屏玩家。即使在设置里关闭了小地图，这个按钮仍然可用；点击即可打开大地图。它与小地图、邀请图标一样，在有模态界面或大地图已打开时自动隐藏。
• 鼠标滚轮：光标位于地图上时缩放。
• 按住鼠标左键拖动：平移大地图。
• 右键已探索区域：传送到附近安全地面，或选择“保存当前位置”把玩家此刻的真实 XYZ 保存为坐标点。右键位置不会被伪造为一个远处 Y。
• 右键坐标点：传送、重命名或删除。
• 触屏长按（约 0.5 秒按住不移动）等同于右键，用于打开传送菜单——手机没有右键，这是触屏玩家的传送入口。长按已探索区域、坐标点或死亡点，会弹出与右键相同的传送/坐标点/死亡点菜单；轻微移动会被识别为平移而不触发。
• 上次死亡地点始终按方向追踪：若骷髅不在当前大小地图视野内，会贴在对应方向的地图边缘。鼠标或触屏点骷髅会打开并定位大地图；右键骷髅或使用大地图右下角“返回死亡点”可执行安全传送。
• 大地图左下角可切换“地表 / 洞穴”。洞穴模式使用游戏真实的 Y=1～254，每次 Y− / Y+ 调整 1 格，也可点击中间的 Y 数值直接输入高度或跟随玩家 Y 轴。地图会投影所选 Y 上下 8 格内最接近的可通行空间，使斜坡、台阶和起伏洞穴保持连续，并用明暗表示相对高度。洞穴地图继承地表地图已经探索的 X/Z 范围，并在对应区块加载时自动生成当前高度投影；未探索的地表范围仍保持隐藏。洞穴地图右键传送会按当前 Y 层寻找安全落脚点。
• 大地图“设置”：开关小地图、坐标、时间、生物标记、罗盘方向、朝向、日夜明暗和邀请；调整标记、字号、尺寸、形状、缩放与位置。大地图支持跟随玩家、鼠标拖动/滚轮缩放和触屏单指拖动/双指缩放，并始终保持北方朝上。
• “恢复默认设置”会先显示确认对话框，只复位地图显示配置；探索区域、坐标点、服务器设置和“接受玩家传送邀请”不会改变。未来版本的只读设置文件禁止复位和写入。
• 界面语言随游戏自动加载并合并进游戏完整文本表；随包提供多语言地图文本，详见下文“语言”一节。
• 多人邀请图标：仅在邀请功能可用且当前还有其他玩家时显示；单击后打开玩家列表，每页 4 人。单人时不显示，旧 ID 41 邀请协议保持兼容。

未探索区域不会被地图渲染或允许右键传送。地图地形随日夜变暗，玩家箭头、坐标点和文字保持可读亮度。

地形阴影

地图会根据地形高低起伏叠加明暗阴影，帮助辨认山脉、峡谷、台阶和洞穴轮廓。阴影强度分为四档，可在大地图“设置”中按当前地图形状以按钮组切换：

• 关闭（Off）：不叠加高度阴影，只保留地形基础颜色。
• 柔和（Soft）：低对比度，阴影轻微，画面更平缓。
• 标准（Standard）：默认档，对比度适中。
• 高对比（High Contrast）：强化明暗差，起伏更立体。

阴影强度在渲染时叠加到已烘焙的地形数据上，因此切换档位会即时重着色整张地图，包括早先探索、以旧存档保存的区块，无需重新探索或删档。各档只改变明暗对比，不改变光照方向，所以切换时地形的立体朝向保持一致。日夜明暗为独立选项，可与高度阴影同时开启；夜间地形整体变暗，而玩家箭头、坐标点和文字保持可读亮度。

语言

界面语言随游戏语言自动加载，并合并进游戏的完整文本表。

联机版

• 直接可用（Survivalcraft 联机版内置的 5 种）：zh-CN、en-US、es-MX、pt-BR、ru-RU。
• 安装配套语言包后额外可用的 13 种：ar-SA、de-DE、fr-FR、hi-IN、id-ID、it-IT、ja-JP、ko-KR、pl-PL、th-TH、tr-TR、uk-UA、vi-VN。这些不是游戏本体内置的语言，需要额外安装配套的全量语言包 SurvivalcraftLangPack 为游戏本体补齐对应翻译，否则它们在游戏语言列表中会是残缺的“孤儿语言”（整屏显示 key 名的坏条目）。把语言包和本 Mod 一起放进 NetMods/ 后，上述 13 种即可正常显示。

插件版

• 当前提供 zh-CN、en-US、pt-BR、ru-RU，均为插件版基础游戏内置语言，无需额外语言包；其余语言会随翻译进度陆续补充。

翻译通过社区协作平台维护，可持续新增和校对更多语言；个别缺失的条目会显示其原始键名，不影响其他界面正常使用。

安全传送

联机版单人世界由集成主机直接执行服务器权威安全传送：

• 目标区块最多等待 10 秒。
• 在目标水平半径 8 格内寻找实体地面与连续两格空气。
• 拒绝水、岩浆、火、仙人掌、尖刺、树叶、下落方块及其他危险/碰撞位置。
• 最终位置落在方块中心，并清除速度和坠落状态。
• 移动后一帧再次验证；失败时回退到原位置的安全静止状态。

坐标点保存完整 XYZ。传送到坐标点时只围绕保存的 Y 上下各搜索 8 格，不会改用地表高度；因此洞穴坐标点不会把玩家送到山顶。

远程联机中，客户端只发送目标 XZ 或 XYZ；服务器重新加载区块、计算安全 Y 并执行传送。远程 ID 61 协议的客户端响应窗口为 5 秒，服务器执行截止时间为 4 秒；截止或掉线会取消并回退未完成事务，避免客户端已超时后又发生迟到传送。集成主机不经过这条远程协议期限，安全搜索可使用完整的 10 秒区块等待上限。服务器确认传送成功后会广播 PositionSet，使已连接客户端同步服务器上的权威位置。服务器未安装 SCTM、禁用该功能或无能力响应时，远程客户端每次会话只提示一次“服务器不支持地图传送或请求超时”。

数据与备份

所有路径均位于游戏的 app:/SurvivalcraftTravelMap：

• 全局界面设置：settings.json（当前 schemaVersion: 3；v1/v2 均以 MigratedPreviousSchema 迁移并重写为 v3。仅 v1 MiniMapSize=384 会一次改为 192；v2、无版本 JSON 和 v3 的 384 保持不变；旧 travel-map-settings.json 仍会一次性迁移且保留原文件）
• 每世界、每玩家地图：maps/<world-key>/<player-guid>/tiles/*.sctm
• 每世界、每玩家洞穴投影：maps/<world-key>/<player-guid>/caves/projection_v2/y_<Y值>/*.sctm
• 每世界、每玩家坐标点：maps/<world-key>/<player-guid>/waypoints.json
• 服务器开关：server-settings.json

本地世界键由规范化世界目录生成；联机世界键由服务器地址、端口和服务器世界标识生成。玩家目录使用玩家 GUID，避免不同世界、服务器或玩家的数据混用。若可靠身份、存储目录或初始地图/坐标点持久化无法建立，该玩家组件保持未激活，不创建地图 UI，并显示提示；游戏本身继续运行。

探索按玩家进入的 16×16 地形区块驱动：一进入新区块就立即调度，只揭示玩家本人进入的区块，不会顺带揭示相邻区块。地形更新完成后，区块达到 surface-readable 阈值 TerrainChunkState.InvalidPropagatedLight 或更高状态，且 256 个地表采样全部非透明时，整个区块才一次性原子写入并在地图上出现；不会先显示零散像素。尚未就绪、瓦片缓存压力或单次采样异常都不会把区块误标完成，而会保留在 pending 队列中持续重试；单个永久失败区块也不会阻塞其他待处理区块。

玩家离开后再次进入同一区块会重新调度并刷新完整 256 像素，因此 World2 等旧世界里已经存在的 partial legacy cache 会在重入时补全，无需删除地图目录。格式版本 1 将 A=0 保留给空气/不可用采样哨兵；旧缓存中“探索位已设置但颜色透明”的像素仍会自动按未探索处理。

一般设置文件读取失败时会使用只读的安全默认设置继续初始化；检测到 schemaVersion > 3 的 settings.json 时，本版本同样只在内存中使用安全默认值并提示一次，所有保存均被禁止，原文件字节保持不变。地图已成功初始化后，若后续瓦片写入持续失败，缓存达到上限会暂停接收新区块探索并提示一次；已有脏瓦片继续保留和重试，成功刷新后自动恢复。

备份时退出游戏，然后复制整个 SurvivalcraftTravelMap 数据目录。卸载 Mod 前也建议这样做。

服务器设置

首次以服务器模式启动后会创建：

{
  "schemaVersion": 1,
  "surfaceTeleportEnabled": true,
  "waypointTeleportEnabled": true
}

修改后重启服务器。未来版本的未知 schema 会以只读方式处理，并使用安全默认值，避免覆盖新格式。

卸载

1. 退出游戏并备份 app:/SurvivalcraftTravelMap。
2. 联机版：从 NetMods 删除 SurvivalcraftTravelMap.netmod；插件版：从 Mods 删除 SurvivalcraftTravelMap.scmod。
3. 若不再需要探索记录和坐标点，可手动删除 app:/SurvivalcraftTravelMap；卸载 Mod 本身不会删除这些数据。

隐私与兼容性

SCTM 不扫描、统计或上报已安装 Mod 的数量，也不包含旧的 Mod 数量校验/上报协议。联机版只注册玩家邀请 ID 41 和服务器权威坐标传送 ID 61；插件版为单人版本，不涉及任何网络协议。

已知限制：

• 联机版针对 Survivalcraft 引擎 2.4.0.0 / NetMod API 1.44 构建，插件版针对 SurvivalcraftApi 1.9.2.1 及以上构建；两版均以 Windows PC 为主要运行平台，具体兼容范围见上文“版本兼容”。
• 联机坐标传送要求服务器安装 SCTM；旧服务器只能使用其已有的邀请传送能力。
• 全细节地图在 64 格瓦片接缝处，探索边界青线可能出现一小段不连续；探索数据本身不受影响。
• 当前 feature/travel-map 候选已通过 Debug 与 Release 全量测试 870/870（0 failed，0 skipped）、warnings-as-errors 构建（0 warnings / 0 errors）及 PACKAGE_OK 封包校验。最新隔离包 SHA-256 为 91C79C880ADC6000B1A45CB63F810F24208BCE6766435C4B16DF02E7557B26BC。
• “生物标记”阶段通过 Release 测试 770/770（0 failed，0 skipped），warnings-as-errors 构建 0 warnings / 0 errors。连续两次封包及校验均得到 PACKAGE_OK，package SHA-256 均为 64B75540EA0F5B9E1F320CCF53524169DDD51F7CA753E4A58AFDC7E7CD9627FE（177792 bytes，精确 8 entries）；包内 DLL 与 Release DLL SHA-256 均为 0774AC5D49E9E55A89B9C45CF4BB4490CF69D70610E46D63B677B65164FBA423（402432 bytes）。用户已在隔离版确认该阶段可以进入下一项。
• “地图朝向”阶段通过 Release 测试 780/780（0 failed，0 skipped），warnings-as-errors 构建 0 warnings / 0 errors。连续两次封包及校验均得到 PACKAGE_OK，package SHA-256 均为 EF8C3570FCE57BCB25E96D651F33EEDCB8DBFA598CEAEE120F8100BF00AF8BEF（178676 bytes，精确 8 entries）；包内 DLL 与 Release DLL SHA-256 均为 5D60E6841EA4FDF5E803F920B9E7DF824C44215665314A6EA1EEBAE2E873812D（405504 bytes）。用户已在隔离版确认小地图两种朝向和固定北方朝上的大地图正常，可以进入下一项。
• “罗盘方向 + 小地图位置”阶段通过 Debug 与 Release 测试 800/800（0 failed，0 skipped），warnings-as-errors 构建 0 warnings / 0 errors。连续两次封包及校验均得到 PACKAGE_OK，package SHA-256 均为 47B7F64F134D88AF8655A019AE5C8486447F3CBDB3B4617DD24090213503718E（182975 bytes，精确 8 entries）；包内 DLL 与 Release DLL SHA-256 均为 A7D4A15C547892E20C969BEF2F62548A712E451B5F985C3F8063D5FEDB4AB890（419328 bytes）。用户已在隔离版确认罗盘选项、鼠标拖动、确认/取消和界面布局正常，可以进入下一项。
• 当前候选已按精确路径安装到 worktree 的隔离 smoke-game，artifact 与 installed SHA-256 相同；隔离 World2 和现有 travel-map cache 均保留。
• 小地图逻辑坐标、entered-chunk 原子探索、全局地图 LOD 与集成主机/联机传送链路均有自动测试覆盖，但不等于游戏内验收。批准的 10 项基础矩阵和 7 项公开分享前扩展矩阵（共 17 项）仍全部 PENDING；实际游戏内布局（含 UI 缩放 0.75 / 1.0 / 1.25）、World2 旧缓存补全、地表/坐标点/失败回退传送、运行模式/绑定同步和多人邀请均须按 烟雾测试清单 由用户确认。

更完整的操作、故障恢复与测试步骤见 用户指南。

公开发布与再分发前置检查

公开发布、创建 tag 或再分发前，仓库所有者/发布者必须确认其对拟发布的全部代码和资产拥有相应权利或已获得许可。当前仓库、构建成功和自动测试不构成该权利确认；在确认完成并记录前，不得创建公开 release/tag 或分发构建。本说明不授予额外许可，也不声明整个项目具有尚未确认的完整原创权利。