Universal Preview

# Feature Introduction

Universal Preview is a standalone Fabric mod for Minecraft Java Edition. It allows you to view items, blocks, drop entities and display entities in a dedicated interface, and provides visual detail anchor editing for items or targets in the world.

This mod is suitable for map creation, script production, resource inspection, scene presentation and item lookup. It does not depend on any content-specific mods, and will not modify the splash screen, loading animations, shaders or game logic of other mods.

## Supported Versions

Fabric builds are available for the following Minecraft versions:

- Minecraft 26.1

- Minecraft 26.1.2

- Minecraft 26.2

You must install the matching mod file for your Minecraft version. Do not place mod files for all three versions into one game instance at the same time.

## Normal Mode

Press **V** while holding an item in your main hand to open the preview interface for that item. Preview objects are temporarily generated client-side only for rendering and viewing. They will not spawn real item drops, place blocks, or modify the world.

## Preview Mode

Administrators can enable Preview Mode for players with the following command:

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

Once enabled, pressing **V** will prioritize detecting the target your crosshair points at. The mod supports item drops, item display entities, block display entities, text display entities, and regular blocks granted preview permission.

Preview Mode uses an allowlist mechanism. Only targets marked with the Preview Permission Tool will be highlighted and can be opened with the V key. This prevents every object on large maps from being highlighted simultaneously.

## Editor Mode

Editor permissions are controlled via this command:

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

Players with Editor Mode can use the Preview Permission Tool, create detail anchors, edit detail text, change text colors and move anchors. Players without editor permissions may still view saved preview details as observers, but cannot edit any data.

## Preview Permission Tool

Obtain the Preview Permission Tool:

`/give @s universal_preview:preview_permission_tool`

While in Editor Mode and Preview Mode:

- Left-click a regular block to grant preview permission to that block

- Left-click an item drop to grant preview permission to that drop entity

- Left-click an item display entity to grant preview permission to that entity

- Left-click a block display entity to grant preview permission to that entity

- Left-click a text display entity to grant preview permission to that entity

- Right-click a previously marked block or entity to revoke its preview permission

Display entities and item drops use separate entity raycasting. Blocks behind entities will not be incorrectly selected due to vanilla crosshair behavior.

## Preview Interface Controls

- **V**: Open preview for held item or crosshair target

- Left mouse drag: Rotate the preview model

- Mouse wheel: Zoom the preview model

- Ctrl + Left mouse drag: Pan the preview model

- **R**: Reset view angle, zoom and position

- **Esc**: Close the interface

The preview model starts centered on screen and fits within available viewport bounds to avoid overflow. The interface uses a fixed logical size and will not break entirely with GUI scaling changes. The preview background remains transparent so you can see the game world. Buttons, input boxes and panels are rendered using independent UI resources.

## Detail Anchors

The detail system follows an **Anchor – Group – Element** structure. Targets with no saved details will not show default circles or empty groups. Anchors only appear for groups that have actually been saved.

Editors can right-click empty space inside the preview interface to create a new anchor. New anchors immediately enter edit mode: enter the group title, then add text elements using the plus button. Existing anchors can be right-clicked to edit, delete or reposition. To reposition, simply drag the anchor without manually filling coordinate values.

Observers can hover to view group titles and click anchors to expand details. Only one group expands at a time; when opening a new group, the old one smoothly collapses. Text has no extra background panel and is overlaid directly onto the preview interface. Anchors will hide after rotating, zooming or panning the model, and reappear after pressing R to reset the view.

## Rich Text & Colors

The detail editor supports visual rich-text editing without handwriting Markdown:

- Bold

- Italic

- Underline

- Strikethrough

- Text color

- Auto line wrap and adaptive input box height

Colors can be selected via a 2D gradient color picker, or input as `#RRGGBB` or `R,G,B`. Hold down the left mouse button and drag on the color panel to pick colors.

# 功能介绍

通用预览（Universal Preview）是一款独立的 Minecraft Java Edition Fabric 模组，用于在专用界面中查看物品、方块、掉落物和展示实体，并为物品或世界中的目标提供可视化的详情锚点编辑功能。

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

## 支持版本

当前提供以下 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 缩放变化而整体失控。预览背景保持透明，可以看到游戏世界；按钮、输入框和面板使用独立界面资源绘制。

## 详情锚点

详情系统采用“锚点 - 群组 - 元素”结构。没有保存详情的目标不会显示默认圆圈或空白群组，只有实际保存过的群组才会出现锚点。

编辑者可以在预览界面空白处右键新建锚点。新建后会立即进入编辑状态，输入群组标题，再通过加号添加文本元素。已有锚点可以右键编辑、删除或修改位置。修改位置时直接拖动锚点即可，不需要手动填写坐标。

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

## 富文本和颜色

详情编辑器支持可视化富文本编辑，不需要手写 Markdown：

- 粗体；
- 斜体；
- 下划线；
- 删除线；
- 文字颜色；
- 自动换行和自适应输入框高度。

颜色可以通过二维渐变色盘选择，也可以填写 #RRGGBB 或 R,G,B。色盘支持按住鼠标左键拖动选择。