通用预览

# 功能简介

通用预览（Universal Preview）是一款独立的 Minecraft Java 版 Fabric 模组。它允许你在专用界面中查看物品、方块、掉落物实体与展示实体，并提供针对世界中物品或目标的可视化细节锚点编辑功能。

 

本模组适用于地图制作、脚本创作、资源检查、场景展示和物品查找。它不依赖任何特定内容模组，也不会修改其它模组的启动画面、加载动画、着色器或游戏逻辑。

 

## 支持版本

以下 Minecraft 版本提供 Fabric 构建：

- Minecraft 26.1

- Minecraft 26.1.2

- Minecraft 26.2

 

你必须为你的 Minecraft 版本安装匹配的模组文件。请勿将三个版本的文件同时放入同一个游戏实例。

 

## 普通模式

在主手持有物品时按下 **V** 键，即可打开该物品的预览界面。预览对象仅在客户端临时生成，用于渲染和查看。它们不会生成真实的物品掉落物，不会放置方块，也不会修改世界。

 

## 预览模式

管理员可以使用以下命令为玩家启用预览模式：

`/up preview_mode <true|false> <targets>`

 

启用后，按下 **V** 键将优先检测准星所指向的目标。该模组支持物品掉落物、物品展示实体、方块展示实体、文本展示实体，以及获得预览许可的普通方块。

 

预览模式采用许可名单机制。只有使用预览许可笔标记过的目标才会被高亮显示，并可通过 V 键打开。这可防止大型地图上的每个对象同时被高亮。

 

## 编辑者模式

编辑权限通过以下命令控制：

`/up editor <true|false> <targets>`

 

拥有编辑者模式的玩家可以使用预览许可笔、创建细节锚点、编辑细节文本、更改文本颜色和移动锚点。没有编辑者权限的玩家仍可作为观察者查看已保存的预览细节，但无法编辑任何数据。

 

## 预览许可笔

获取预览许可笔：

`/give @s universal_preview:preview_permission_tool`

 

在编辑者模式和预览模式下：

- 左键点击普通方块，授予该方块预览许可

- 左键点击物品掉落物，授予该掉落物实体预览许可

- 左键点击物品展示实体，授予该实体预览许可

- 左键点击方块展示实体，授予该实体预览许可

- 左键点击文本展示实体，授予该实体预览许可

- 右键点击此前标记过的方块或实体，以撤销其预览许可

 

展示实体和物品掉落物使用独立的实体射线检测。位于实体后方的方块不会因原版准星行为而被错误选中。

 

## 预览界面控制

- **V**：打开手持物品或准星目标的预览

- 鼠标左键拖动：旋转预览模型

- 鼠标滚轮：缩放预览模型

- Ctrl + 鼠标左键拖动：平移预览模型

- **R**：重置视角、缩放和位置

- **Esc**：关闭界面

 

预览模型初始位于屏幕中央，并适配可用的视口边界以避免溢出。该界面使用固定的逻辑尺寸，不会因 GUI 缩放更改而完全损坏。预览背景保持透明，使你可以看到游戏世界。按钮、输入框和面板使用独立的 UI 资源渲染。

 

## 细节锚点

细节系统遵循 **锚点 – 群组 – 元素** 的结构。没有已保存细节的目标不会显示默认圆圈或空白群组。锚点仅在实际保存过的群组中显示。

 

编辑者可以在预览界面内部的空白区域右键点击以创建新锚点。新锚点会立即进入编辑模式：输入群组标题，然后使用加号按钮添加文本元素。可右键点击现有锚点进行编辑、删除或重新定位。要重新定位，只需拖动锚点，无需手动填写坐标值。

 

观察者可悬停以查看群组标题，并点击锚点展开细节。同一时间只有一个群组展开；打开新群组时，旧群组会平滑收起。文本没有额外的背景面板，直接叠加在预览界面上。旋转、缩放或平移模型后，锚点会隐藏，并在按 R 重置视角后重新出现。

 

## 富文本与颜色

细节编辑器支持可视化富文本编辑，无需手写 Markdown：

- 粗体

- 斜体

- 下划线

- 删除线

- 文本颜色

- 自动换行和自适应输入框高度

 

颜色可通过 2D 渐变拾色器选择，也可输入 `#RRGGBB` 或 `R,G,B`。在颜色面板上按住鼠标左键并拖动即可选取颜色。