视角书签 Mod —— 把相机机位存成书签，一键切过去，一键切回来。
用 Freecam（灵魂出窍）类 Mod 找机位时，想回到之前看过的那一个视角，往往只能靠手动一点点飘回去。
QuickView 把「相机机位」变成可保存的书签：记录坐标 + 朝向 + 维度，按 V 打开菜单点一下，视角立刻切过去（可选平滑过渡），不需要来回找路。切换期间玩家本体留在原地不动，移动输入被拦截，可以自由飞行地勘察机位；按 B 或在菜单里点「恢复视角」即可回到本体。
- 视角书签：保存相机坐标（X/Y/Z）+ 朝向（Yaw/Pitch）+ 维度，跨维度自动隔离
- 一键切换：点击书签切到该机位，
- 一键恢复：
B立刻回到玩家本体视角；在菜单里点「恢复视角」同样立即恢复并关闭菜单 - 本体不动：切换期间拦截 WASD 移动输入，不会把角色带下悬崖
- 自由移动：切过去之后可以自由飞行（WASD + 空格/Shift），带加速与减速的手感调节
- 自由视角下继续存点：新增书签（含「设为当前」与快捷键快存）取的是当前正在看的相机机位，不是玩家本体的视角
- 跟随鼠标：默认第一人称，按
F5切第三人称时能看到并检查玩家本体 - 自由视角下隐藏手持物品，避免手臂遮挡画面
- 可自定义按键：设置页内置按键捕获按钮，支持重置为默认
- 拼音搜索：书签列表支持中文、全拼、声母三种输入，且多音字按词组上下文取音
（
家里蹲可搜jia/jialidun/jld；矿洞Boss房可搜kdbf；重庆可搜cq/chongqing） - 拖拽排序：点「排序」按钮进入排序模式，按住条目拖动即可调整顺序（条目跟着光标走、落点有预览框），松手才落位并保存
- 分组与筛选：给书签填一个分组名，主界面左上角的分组按钮点开即可按分组筛选
- 批量删除：进入「删除」模式后逐个点击条目勾选（红色边框标记，不会真的删），底部按钮显示已选数量，一次确认批量删除
- 批量归组：「归组」模式下勾选书签（绿色标记），点「归组已选 (N)」从下拉里选目标分组（或「（无分组）」移出），一次批量移入，不弹确认（随时可再改）
- 书签克隆：编辑面板「复制」，复制出一份连名字（自动加「副本」后缀）、分组、坐标都一样的新书签，并直接切到编辑副本
- 受伤立即恢复：自由视角下受到伤害时马上回到本体视角，同时关闭打开中的 QuickView 界面，默认开
- 可选用 Tweakeroo 的灵魂出窍：装了 Tweakeroo 时，可在设置页把「切换视角」 交给它的自由相机实现（默认关；此时移动与输入由 Tweakeroo 控制，QuickView 只负责把相机摆到书签位置）
- 可选平滑过渡：切换视角时可以瞬间跳过去，也可以平滑飞过去（设置页开关）
- 分类存储：多人服务器按服务器地址、单人按存档名，再按维度分文件
| 项目 | 版本 |
|---|---|
| Minecraft | 1.21.11 |
| Fabric Loader | ≥ 0.18.3（LibGui 15.1.0 自身的要求） |
| Fabric API | 必需 |
| LibGui | 15.1.0（>=15.1.0 <16） |
| Java | 21+ |
纯客户端 Mod：不需要安装在服务端。
- 安装 Fabric Loader（1.21.11）
- 把 Fabric API 与 LibGui 放进
mods/ - 把
quickview-<版本>.jar放进mods/ - 启动游戏，按键设置在「选项 → 控制 → 按键绑定 → QuickView」
- 走到想记录的机位，按
V打开菜单 → 点+新增书签（自动填入当前视角的坐标与朝向，可在编辑面板里微调或点「设为当前」重新取值） - 换个位置，再存几个书签
- 之后任意时刻按
V，点书签即可切到该机位 - 按
B（或在菜单里点「恢复视角」）恢复本体视角
再按一次 V 也能直接关闭菜单，不必按 ESC。
想边看边挪？切到书签后按 G 打开自由移动，用 WASD + 空格/Shift 飞行，鼠标控制朝向；此时再按 V → + 或 N 存点，记下的就是你现在看到的位置。
| 按键 | 功能 |
|---|---|
V |
打开 / 关闭 QuickView 菜单 |
B |
恢复本体视角 |
N |
快速保存当前视角为书签（View N） |
G |
切换自由移动（自由视角下生效，游戏内会提示开关状态） |
H |
切换「灵魂出窍优先」 |
全部可在设置页（主菜单右下角 ⚙）里改键，重置 按钮可恢复默认。
主菜单从上到下是四行：顶栏（分组 / 搜索）→ 书签列表 → 模式开关 → 动作行。
- 顶栏：左上角是分组按钮（点开就是分组下拉，选「全部」或某个分组）；右侧是搜索框，框内右端的
×可一键清空- 搜索支持中文原文、全拼、声母（不区分大小写，自动忽略首尾空格）。多音字由词级分词处理
- 书签列表：网格排列，滚动浏览；搜索与分组筛选叠加生效
- 模式开关（
编辑/排序/归组/删除，四者互斥，同一时刻只有一种「点条目」的含义）- 编辑：点条目进入编辑面板
- 排序：按住条目拖动调整顺序 —— 源条目变暗、半透明条目跟着光标走、目标格子显示落点预览框， 松手才真正落位并写入存档；排序模式下单击条目不做任何事，避免误切换视角
- 删除：点条目勾选（红色边框 + 浅红底色标记，不会立刻删除），勾选后底部按钮变成「删除已选 (N)」， 点它才会弹一次二次确认，确认后批量删除
- 归组：点条目勾选（绿色边框 + 浅绿底色标记），勾选后底部按钮变成「归组已选 (N)」，点它从上方展开的 下拉里选目标分组（「＋ 新建分组…」/「（无分组）」/ 各已有分组），选中即批量移入该分组并刷新列表
- 动作行：
+新增书签，中间一格会随模式变化 —— 无模式时是「恢复视角」按钮， 编辑/排序/删除/归组模式下则显示对应的操作提示文字（如「拖动书签调整顺序」）， 删除模式勾选后变成「删除已选 (N)」、归组模式勾选后变成「归组已选 (N)」； 最右是齿轮（设置） - 编辑面板：名称、分组（可选，可从下拉列表选已有分组或新建）、X / Y / Z / Yaw / Pitch（仅允许数值）；
「设为当前」把当前相机机位写入该书签，右侧红色垃圾桶图标用于删除该书签（会先关面板再弹确认）。
底部按钮按场景变化：
- 新建书签（点
+后）：取消/保存—— 保存才留下，取消直接丢弃，不会留下空书签 - 编辑已有书签：
取消/保存/复制—— 取消会回滚本次所有改动， 复制则克隆出一份（名字加「副本」后缀）并直接编辑副本
- 新建书签（点
- 设置页：双 Tab
- 功能：快速添加、自由移动、灵魂出窍优先、切换视角平滑过渡、受伤立即恢复视角、使用 Tweakeroo 灵魂出窍（说明文字里的快捷键会自动跟随你改键）
- 快捷键：改键 + 重置
| 设置 | 说明 |
|---|---|
| 快速添加 | 是否允许用 N 快速保存（默认开） |
| 自由移动 | 切换视角后是否允许自由飞行（默认开，可用 G 随时切换） |
| 灵魂出窍优先 | 与其他 Freecam 类 Mod 共存时，优先以「相机实体」而不是玩家本体取景（默认开） |
| 切换视角平滑过渡 | 点书签时是否从当前位置飞过去而不是瞬间跳过去（默认关；过渡期间鼠标不接管视角） |
| 受伤立即恢复视角 | 自由视角下受到伤害时是否立刻回到本体视角、并关闭打开中的 QuickView 界面（默认开） |
| 使用 Tweakeroo 灵魂出窍 | 切换视角时改用 Tweakeroo 的自由相机（默认关；未安装 Tweakeroo 时该项置灰。启用后平滑过渡不生效，移动/输入由 Tweakeroo 控制） |
这几项现在会持久化到
.minecraft/config/quickview.json，改了就存，重启后保持。
书签以 JSON 保存在游戏目录下，按「上下文 / 维度」分文件：
.minecraft/quickview/<服务器地址或存档名>/<维度>.json
文件内容是带版本号的对象，便于以后升级格式：
{ "version": 1, "viewpoints": [ { "name": "Home", "dimension": "minecraft:overworld", "x": 0.0, ... } ] }（1.0.1 及更早版本的裸数组格式仍可正常读取，保存时会自动升级。）
- 多人服务器：用服务器地址作为上下文，切换服务器不会串数据
- 单人存档：用存档名作为上下文
- 维度：
minecraft:overworld/minecraft:the_nether/minecraft:the_end等各存一份 - 写入采用「临时文件 + 原子替换」，中途崩溃不会损坏已有书签
直接删除对应 JSON 即可清空该书签列表。
设置项另存在 .minecraft/config/quickview.json（同样是带 version 的对象，缺字段时按默认值处理）。
需要 JDK 21。
.\gradlew build产物在 build/libs/，命名随 git 分支自动切换：
| 构建所在分支 | 产物 |
|---|---|
dev |
quickview-<版本>-dev.jar |
main / tag |
quickview-<版本>.jar |
| 任意分支 | gradlew build -Prelease 强制使用正式版本号 |
src/main/java/dev/quickview/
├── QuickViewClient.java # 客户端入口
├── QuickViewManager.java # 核心状态机：切视角、自由移动、书签增删改、拖拽排序落盘
├── QuickViewConfig.java # 全局设置（config/quickview.json）
├── QuickViewKeybindings.java # 按键注册与轮询
├── Viewpoint.java # 书签数据模型（含分组）
├── ViewpointStorage.java # Gson JSON 存取（按上下文/维度分文件）
├── JsonFile.java # JSON 落盘：临时文件 + 原子替换
├── PinyinSearch.java # 搜索匹配键：原文/全拼/声母（内置 houbb/pinyin）
├── gui/ # LibGui 界面
│ ├── 界面主体：主菜单、编辑面板、设置页、确认框、滚动列表（拖拽排序 + 勾选）
│ └── 自绘控件：齿轮/垃圾桶/下拉箭头图标、搜索框内清空图标、下拉面板与挡板
└── mixin/
├── CameraMixin.java # 视角激活时覆盖相机 pos/rotation
├── KeyboardInputMixin.java # 拦截本体移动输入，转给自由相机
├── EntityMixin.java # 把鼠标视角变化转给自由相机
└── HeldItemRendererMixin.java # 隐藏手持物品
main：只放正式发布版本，first-parent 链即发布线dev：日常开发分支，功能与修复都提交在这里- 发布时：
main合并dev→ 在main上升版本号并打 tag → 构建正式 jar → 版本号改动合并回dev - Release 说明：发版前把面向用户的说明放到
.github/release-notes/<tag>.md（例如.github/release-notes/v1.0.2.md），打 tag 后 CI 会用它作为 Release 正文； 没有这个文件时才回退到自动生成的 commit 列表
新增
- 使用 Tweakeroo 灵魂出窍（设置页开关，默认关）：装了 Tweakeroo 时，切书签改由它的自由相机实现，
移动/输入/视角恢复都归它；没装则自动使用自带实现，该开关置灰。该模式下「受伤立即恢复」照常生效，
按
B会连同它的自由相机一起关掉。已知取舍：平滑过渡在该模式下不生效 - 编辑面板补「取消 / 保存」：新建时底部是 取消/保存（取消不留空书签）；编辑时是 取消/保存/复制， 其中取消会回滚本次所有改动；原「复制为新书签」文案精简为「复制」
改进
- 书签列表以内存为准，只在换世界/维度时读盘；打开界面也不再重复读盘
- 搜索过滤复用已建条目控件，拼音转换对 ASCII 走快路径
- 快捷存点的默认书签名改用语言键（中文环境为「视角 3」而非
View 3）
修复
- 自由视角偏航角未归一化：长时间转视角后数值会持续累加（配置里可能出现
4321.0这类值，角度换算精度下降），现统一归一到[-180, 180)
新增
- 受伤立即恢复视角：自由视角下受到伤害时立刻回到本体，并关闭打开中的 QuickView 界面（默认开，可在设置里关）
- 批量归组：「归组」模式勾选书签（绿色标记）→「归组已选 (N)」→ 从下拉选目标分组（含「＋ 新建分组…」/「（无分组）」），一次批量移入
- 书签克隆：编辑面板「复制为新书签」，复制坐标/朝向/分组并直接切到副本
改进
- 分组下拉里「当前所在的分组」置灰（编辑页按该书签、归组按勾选项的共同分组；分属不同分组时不置灰）
- 设置页说明里的快捷键跟随实际改键立即刷新（以前要重进设置页）
- 编辑面板改为「值真变了才落盘」：不再每次失焦都写盘，也不会因崩溃/强杀丢改动
- 拼音搜索加缓存，书签多时输入更跟手
- 依赖写准确：LibGui
15.x、Fabric Loader≥ 0.18.3（原写 0.17.0 实际无法满足）
修复
- 编辑面板垃圾桶删除静默失效（1.0.2 起：确认框关闭但书签仍在）
- 从「删除/归组」切到「编辑/排序」后列表残留红/绿勾选框
相对 v1.0.1，这一版补齐了日常使用最需要的几件事（搜索 / 排序 / 分组 / 批量删除），并重新排布了主界面。
新增
- 拼音搜索：中文原文、全拼、声母三种输入，多音字按词组上下文取音（
家里蹲可搜jld，重庆可搜cq/chongqing） - 拖拽排序：排序模式下按住条目拖动，条目跟着光标走、落点有预览框，松手才落位并保存
- 分组与分组筛选：主界面左上角分组按钮点开即可按分组筛选
- 批量删除：删除模式下勾选条目（红色边框标记），底部「删除已选 (N)」一次确认批量删除
- 设置项持久化：设置页开关保存到
config/quickview.json，重启后保持 - 可选平滑过渡、删除前二次确认
- 中文 README（本文件）
改进
- 再按一次
V直接关闭菜单；菜单里点「恢复视角」立即恢复并关闭菜单 - 存档改为「临时文件 + 原子替换」（写一半崩溃不再损坏文件），格式升级为带版本号对象（旧裸数组仍可读、保存时自动升级）
- 清空改为搜索框内部的
×图标；按钮改用自绘图标（齿轮 / 垃圾桶 / 下拉箭头）；动作行会随模式显示操作提示 - 设置页说明里的快捷键跟随你的实际改键
修复
- 书签名留空不再把书签改成无名（旧版清空名称框会存成空名，删除确认还会显示成「删除「」」）
首个公开发布版本：视角书签（坐标 + 朝向 + 维度）、一键切换与恢复本体、自由移动飞行、 第三人称可见本体、隐藏手持物品、编辑面板、可自定义按键。
完整变更见 Releases。
- 书签 JSON 导入 / 导出（跨设备迁移、分享机位）
- 空列表 / 搜索无结果时显示提示文字
- 主界面显示当前存档·服务器与维度
- 书签条目悬停显示坐标
- 单个书签绑定独立快捷键，或「上一个 / 下一个」循环切换
- 可选的 ModMenu 入口
自由视角类功能在部分多人服务器可能被规则禁止，请在服务器游玩前自行确认；由此产生的后果与本 Mod 无关。
本项目采用 MIT 许可（fabric.mod.json 中的 license 字段为 MIT）。
以下库通过 Loom 的 include 打进 mod jar（jar-in-jar，位于 META-INF/jars/），无需用户单独安装：
| 库 | 版本 | 许可 | 用途 |
|---|---|---|---|
| houbb/pinyin | 0.4.0 | Apache License 2.0 | 汉字转拼音、多音字词级消歧 |
| houbb/heaven | 0.2.0 | Apache License 2.0 | houbb/pinyin 的运行时依赖 |
| houbb/nlp-common | 0.0.5 | Apache License 2.0 | 分词用的 trie/dfa，houbb/pinyin 依赖 |