地下城指南

Valheim 地下城指南

一个用于在 Valheim 地下城中导航、探索各楼层，并找回遗留宝箱的客户端 BepInEx 模组。

**版本：** 0.1.2 | **开发目标：** Valheim **1.0.21** 搭配
BepInExPack Valheim **5.4.2351**。
有关记录的环境与验证状态，请参阅[兼容性与验证](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/development.md#compatibility-and-verification)。
本仓库构建的游戏内验证仍在进行中。

## 地下城地图

- 在原生 **M** 地图和小地图中显示平面图，默认显示已探索区域。
自动激活需要身处地下城内部且属于已生成的房间；
室外基地保留普通的 Valheim 地图。
- 以深色轮廓和柔和地图配色连续采样覆盖楼层。
- 不透明的云雾遮挡未访问的房间。探索会揭示一个十米半径的圆形区域，
该区域被墙壁和玩家实际所在楼层裁剪，已探索区域内边缘柔和。
- 可切换显示所选楼层上所有已扫描的几何结构；它绝不会将未见的区域标记为已探索。
- 紧凑的两行工具栏使用已加载的 Valheim 按钮精灵、字体和可选中状态。
**更多**会打开键盘和鼠标提示，且每次打开时初始为关闭状态。
- 自动选择当前楼层，并可浏览更高和更低的楼层。
- 首次打开及切换楼层时，视图适配整个所选楼层。
重新打开会保留手动缩放和位置；**Home** 再次适配你的当前楼层。
- 相对于入口的楼层编号：已知入口处为 **0**，向下为负，向上为正。
入口未知时会明确标注并采用自下而上的编号。
- 通往未探索区域、已知宝箱、入口及相邻楼层的路线。
楼层导航会指向下一个检测到的建筑层级上的宽阔落脚点。
- 持久化探索记录、宝箱内容快照、笔记和收集标记。
- **Alt+M** 切换到 Valheim 的世界地图，以使用原生图钉和多人游戏标记。
- 可按需使用独立的叠加地图；它初始为隐藏状态。

界面遵循 Valheim 所选语言：默认英语，仅当 Valheim 设置为捷克语时才使用捷克语。
所有其他语言均回退到英语。
更改游戏语言会更新地图控件和导航文本。已保存的宝箱名称和个人笔记会保留。
配置描述、日志和仓库文档均为英语。

## 安装

使用 Thunderstore Mod Manager 或 r2modman，将 Dungeon Guide 及其
BepInExPack 依赖安装到你的 Valheim 配置文件中，然后通过管理器启动。
英语已嵌入主程序集；`cs/` 目录包含捷克语。

首先安装 BepInExPack Valheim 5。从成功拉取请求的 **CI** 运行中，
下载 `DungeonGuide-<version>` 工件，并将其中的 `BepInEx` 目录
解压到 Valheim 安装目录中。或者，[构建解决方案](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/development.md#build)
并将 `src/DungeonGuide/bin/Release/net48/` 中的 **两个** `DungeonGuide.dll` 和
`DungeonGuide.Domain.dll` 都复制到 `BepInEx/plugins/DungeonGuide/`。
同时将 `cs/` 子目录复制到它们旁边；其中包含
`DungeonGuide.Domain.resources.dll`，即捷克语翻译附属程序集。

开发工件的命名格式为 `DungeonGuide-<major.minor.patch>.<run>-dev.<attempt>`，
例如 `DungeonGuide-0.1.1.83-dev.1`。CI 运行名称包含完整的 `0.1.1.83` 版本号；
其摘要显示组装版本和包下载链接。
它们的 `build-info.json` 记录确切的提交、CI 运行、PR 及 Valheim 目标；
启动日志会报告相同的构建标识。报告问题时请附上该信息。
这些工件是测试构建而非稳定版本。它们包含
Thunderstore 清单、256 x 256 图标和本 README，直接位于 ZIP 根目录中。
要发布经过审核的构建，请将 ZIP 上传到
[Thunderstore](https://thunderstore.io/package/create/) 的你的团队和
Valheim 社区下。发布仍需手动进行。公开包版本来自
`Version.props`（例如 `0.1.1`）；DLL 保留确切的开发
标识。每个公开版本仅发布一次，并在下次更新前递增版本号。

替换 DLL 前请关闭游戏。保持此插件仅安装一份；
移除其他插件目录中的旧副本。在同一配置文件中禁用与之竞争的地下城地图
模组。无需服务器安装。正常的 BepInEx、
Harmony、Unity 和 Valheim 程序集由游戏环境提供，
不得从构建引用复制到插件目录中。

## 操作

| 操作 | 动作 |
| --- | --- |
| **M** | 打开或关闭原生地图 |
| **Alt+M** | 切换地下城/世界地图 |
| **Page Up / Page Down** | 地图打开时浏览楼层 |
| **Home** | 跟随并适配你的当前楼层 |
| **F6** | 切换可选的独立叠加地图 |
| **F7** | 将打开或直接瞄准的宝箱标记为待收集 |
| **Shift+F7** | 命名实际宝箱或添加笔记 |
| **Ctrl+F7** | 将实际宝箱标记为已收集 |
| **F8** | 循环切换已知宝箱目的地 |
| **F9 / Shift+F9** | 开始探索导航 / 停止导航 |
| **F10** | 导航到已知入口或明确标注的扫描原点 |

地图按钮用于选择揭示模式和导航目标。已验证的跳跃和
可破坏路线是自动的；两者都不需要开关。鼠标滚轮缩放；
拖动平移地下城地图。几何结构会在需要时自动刷新。
通过打开宝箱或瞄准其交互目标来标记宝箱。使用 F8 循环
选择导航目的地；它不会选择 F7 影响的宝箱。
收集标记记录你的确认；插件不会移动物品。

### 个人返回位置

个人返回位置：Alt+F7 在此处标记，Alt+F8 循环切换返回目标，Alt+Shift+F7 命名
所选位置，Alt+Ctrl+F7 将其移除。在单层地下城地图上，使用 Alt+点击
添加粉色菱形，点击进行导航，Shift+点击命名，右键点击将其移除。
位置按世界/地下城持久化保存在 schema 4 中；它们不会阻止掉落物品消失。

## 设置与已保存的探索

首次运行会创建 `BepInEx/config/zip.dungeonguide.cfg`。快捷键可在
该文件中配置。没有手动重新扫描按钮或快捷键。F5 仍
可用于 Valheim 控制台。
`Display.RevealAll` 默认为 `false`。叠加地图始终初始为隐藏。
已验证的跳跃/下落和可破坏路线始终启用。原先的
`Routes.AllowJumps`、`Routes.AllowBreakables`、预制体批准和手动扫描
设置会被忽略；保存的 false 值无法禁用已验证的通行。
仅检测到的地下城内部会激活地图绘制。室外基地保留原生地图。
离开地下城会恢复普通地图，包括在仍处于其原先扫描范围内时
传送到内部之外。

探索、宝箱笔记和已验证通行按世界和地下城存储在
`BepInEx/config/DungeonGuide/` 下。状态会定期保存、在离开时
以及宝箱编辑后保存。保存使用版本化 JSON 和原子替换，并保留
上一文件的 `.bak`。损坏或未来版本的数据会使该会话变为只读，
而不会覆盖现有文件。现有的版本 1 记录会迁移，
同时不改变其既定字段名。

已完成楼层的几何结构也会在地下城退出和游戏重启后保留。
返回最近访问过的地下城会复用其实时会话和准备好的
细节/小地图纹理。新游戏会异步加载单独校验的几何
缓存；对于未变更的布局，不会重复进行楼层采样。
观察到的门口到达点会随该几何结构保留。门权限和
特殊通行证据在导航前仍需当前世界验证。
不完整或结构已更改的布局会恢复自动扫描，同时
之前的地图仍然可见。缓存文件位于 JSON 存档旁边的 `DungeonGuide/Geometry/` 中；
请参阅[格式与恢复规则](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/geometry-cache-format.md)。

## 限制与验证

地图从已加载的碰撞几何结构采样；完整扫描视图并不
保证地下城中的每个房间都已加载或捕获。狭窄楼层、
复杂楼梯和阳台可能存在歧义。门交互会刷新
通行权限；观察到的结构性破坏会安排自动
替换。大型扫描会分布在多帧中，并有可配置的上限。

扫描在单个样本和通道候选之间进行产出，默认
软预算为**每帧 1 毫秒**（`Scan.MillisecondsPerFrame`）。它不会暂停
游戏、锁定输入或禁用其他插件。纯楼层分析在后台线程上运行，
并在离开会话时取消；替换完成前，之前的地图仍然可用。
Unity 物理仍在游戏线程上运行：单个引擎查询无法被中断，
因此该预算不是硬性帧时间保证。实际帧时间及与其他模组的兼容性
需要游戏内检查。

优先选择普通步行路线。可破坏候选需要实际
原生可破坏物、薄障碍物以及两侧的楼层支撑。验证
会检查当前生命值为正、携带可用的武器/工具、匹配的弹药、
伤害抗性以及游戏的工具/世界等级规则。无需预制体批准列表
或事先破坏。装备/钥匙变化会刷新权限而无需
重新采样楼层。玩家建造的部件和未知的可破坏物实现
仍属保守排除项。在先前观察到方向性通行且当前
几何结构/能力检查通过后，跳跃和下落始终被允许。
如果普通寻路失败，导航可以检查一次抓钩跨越。
钩索段为橙色，其附着表面用橙色十字标记，
且 HUD 会明确警告该路线需要钩索。所有路线线条
均更粗且有轮廓。请参阅[钩索寻路与当前限制](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/grappling-routes.md)。
本指南不会开门、破坏物体、发射钩索、跳跃或控制你的角色。

## 贡献

请参阅[开发](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/development.md)、[CONTRIBUTING.md](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/CONTRIBUTING.md) 和
[C# 编码约定](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/coding-conventions.md)。AI 编码助手还必须
遵循 [AGENTS.md](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/AGENTS.md)。

## 许可证

[MIT](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/LICENSE)。Valheim 和第三方组件仍归其
各自所有者所有。外部引用程序集不包含在插件工件中。

## 响应式地图开发

目标 Valheim 1.0.21。地图使用增量 CPU 合成来处理楼层颜色、探索和访问。
请参阅[雾更新](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/incremental-fog.md)和[房间访问](https://github.com/Zip83/Valheim-Dungeon-Guide/blob/master/docs/room-visits.md)。

**图例**按钮会打开一个单独的、可滚动的颜色图例，使用原生字体
和实际颜色样本。使用**关闭**或点击面板外部来关闭它。
图例初始为隐藏，并在离开大型地下城地图时关闭；图例打开时
地图指针交互会被阻止。