Universal Preview

Universal Preview

Universal Preview is an independent Minecraft Java Edition Fabric mod for inspecting items, blocks, dropped items, and display entities in a dedicated interface. Its visual anchor editor can attach interactive text and image annotations to preview targets.

Current mod version: 2.0.0. This project has no dependency on a particular map or content mod, and does not contain or modify another mod's loading screen, character system, or gameplay.

中文文档：README.md

Supported versions

| Minecraft | Gradle project | Fabric Loader | Fabric API | Distribution file |

| --- | --- | --- | --- | --- |

| 26.1 | Root project | 0.19.2 | 0.145.1+26.1 | universal-preview-2.0.0-fabric_26.1.jar |

| 26.1.2 | :fabric-26.1.2 | 0.19.5 | 0.155.2+26.1.2 | universal-preview-2.0.0-fabric_26.1.2.jar |

| 26.2 | :fabric-26.2 | 0.19.5 | 0.159.0+26.2 | universal-preview-2.0.0-fabric_26.2.jar |

All variants share source code, assets, the universal_preview mod ID, and the data schema. Install only the JAR matching the instance's Minecraft version.

Basic preview

• The default preview key is V.

• In normal mode, press V while holding an item in the main hand.

• A stack always renders as one preview model, regardless of its count.

• Temporary preview entities are client-only and never spawn an item, place a block, or modify the world.

• Initial model scale is fitted from rendered bounds and the available screen area.

• Blocks and block displays use a readable three-dimensional initial angle.

Controls

| Input | Action |

| --- | --- |

| Left mouse drag | Rotate |

| Mouse wheel | Zoom |

| Ctrl + left mouse drag | Pan |

| R | Restore the target's saved initial view |

| Esc | Close |

Zoom is locked while a detail anchor is expanded. Rotating, panning, or zooming hides anchors; restoring the initial view makes them visible again.

Preview mode and permissions

/up preview\_mode <true|false> <targets>

/up editor <true|false> <targets>

Preview mode uses an allowlist so a scene is not flooded with highlights. The editor command replaces the old workflow that required manually adding a vanilla player tag.

Give the Preview Permission Tool:

/give @s universal\_preview:preview\_permission\_tool

The player must have both preview mode and editor mode enabled. With the tool held:

• left-click an ordinary block to grant permission;

• left-click a dropped item, item display, block display, or text display to grant entity permission;

• right-click one of those targets to revoke permission;

• an allowed target under the crosshair is highlighted and can be opened with V.

Entity selection uses a dedicated raycast and corrected display bounds. It prioritizes the actual display or dropped item under the crosshair even when vanilla reports the block behind it, while still respecting block occlusion.

Server-controlled preview UI

/up preview\_ui open <targets>

/up preview\_ui close <targets>

/up preview\_ui open <targets> <id>

/up preview\_ui progress\_bar <true|false> <targets>

• Without <id>, each target player's main-hand item is opened.

• <id> accepts item IDs with vanilla or modded data components.

• It also accepts entity IDs followed by optional vanilla SNBT entity data.

• Resolution uses the live registries, not a hard-coded vanilla list.

• Invalid IDs, component syntax, or SNBT return an error instead of crashing a client.

• close closes both the preview screen and its anchor editor.

Examples:

/up preview\_ui open @s

/up preview\_ui open @a minecraft:diamond

/up preview\_ui open @s minecraft:stone[minecraft:custom\_name='{"text":"Sample"}']

/up preview\_ui open @s minecraft:item\_display{item:{id:"minecraft:diamond",count:1}}

/up preview\_ui close @a

Hold-to-open progress ring

progress_bar defaults to false. When enabled:

• the preview key must be held for about 750ms;

• a clockwise ring is rendered below the crosshair;

• releasing early cancels and resets it;

• one hold can open only once, until the key is released;

• command-triggered previews play the same progress animation;

• other screens are unaffected.

The ring uses Minecraft/Fabric HUD extraction APIs and does not mutate raw OpenGL state.

Detail anchors

A target with no saved groups shows no built-in dot or placeholder. Rings exist only for actual detail groups.

Observer interaction

• Hovering a ring shows the group title tooltip.

• Clicking expands content smoothly toward the inside of the screen.

• Only one group can be open; opening another collapses the previous group.

• Text and images are drawn directly over the preview layer without an opaque detail card.

• A thin connector links the ring and content.

• Candidate placement respects screen edges and other fixed UI regions.

• Long text is never replaced by an ellipsis.

• Content taller than the safe screen area remains complete and gets an independent smooth scrollbar.

Visual editing

Editors can right-click empty space to create an anchor. Right-clicking an existing anchor offers edit, delete, and move operations. Move mode shows a grid and a ring following the cursor; coordinates are clamped to the safe screen area and saved on release.

The editor provides:

• group title;

• group-title size slider (0.5x to 2.0x);

• command code field;

• Run once / Repeatable mode;

• text and image elements;

• an independent size slider for every text element;

• bold, italic, underline, and strikethrough;

• selection-scoped text color;

• draggable saturation/value palette and hue strip;

• Hex #RRGGBB and RGB R,G,B input;

• per-entry checkboxes, Select all, and Delete selected;

• fixed Save and Cancel controls.

The header and actions are fixed while entries live in a clipped viewport. Long text scrolling and entry-list scrolling are independent. Scrolling no longer rebuilds the screen or causes unrelated widgets to disappear.

Rich-text selection

Mouse positions are measured from Unicode code points and actual wrapped lines, including the current internal text scroll. Mixed Chinese, Latin text, numbers, and newlines are supported. Toolbar actions modify only the current selection; without a selection, they apply to the active element. Styles are stored as independent text segments.

Image elements

World image root, shared by single-player, LAN hosts, and dedicated servers:

saves/<world>/universal\_preview/

• Any folder depth is supported.

• Only .png files are accepted.

• The picker uses an indented folder tree similar to a code editor.

• Real paths are checked to reject .. traversal and symbolic-link escapes.

• Maximum file size is 8 MiB, maximum width/height is 4096, and maximum area is 16777216 pixels.

• Valid images are aspect-fitted in both the element list and expanded details.

• Every image occupies its own layout element and cannot overlap adjacent elements.

• Read failures are logged and shown as an error state without crashing.

• Multiplayer uses the server world's image directory as the authority; the host or server stores one copy of each PNG.

• Remote clients request a saved relative path on demand and display it automatically, with no manual file copy.

• Transfers are bounded, chunked, and SHA-256 verified; the client also validates PNG type, dimensions, and pixel count.

• Remote images stay in the client's in-memory texture cache, are never written to player storage, and are released on disconnect.

• Image synchronization requires Universal Preview on the server/host and every joining client.

Anchor commands

An editor may store a command without the leading /. A blank command does nothing.

• Run once: executes on the first expansion in the current preview session.

• Repeatable: executes on every new expansion.

• An editor clicking an anchor opens the editor and does not accidentally execute it.

• Observer expansion is the execution trigger.

Security model: the client packet carries only target identity and group ID. The server reloads its own stored group, validates target existence and distance, and then executes the stored command. Arbitrary command text supplied in a click packet is never trusted.

Custom initial view

Editors can rotate, zoom, and pan exactly as in normal preview. At the end of the interaction, that state becomes the target's new initial view:

• future openings use the saved scale, rotations, and translation;

• R restores the saved state;

• anchor visibility uses that state as its baseline;

• wheel updates use a 250ms debounce to avoid a packet per wheel notch;

• saving promotes the current values immediately, preventing a sudden scale or position jump.

Data schema

The current SchemaVersion is 2. Missing new fields receive defaults, so legacy data remains readable.

Group fields include Id, Title, TitleKey, Color, AnchorX, AnchorY, Command, RepeatCommand, TextScale, and Entries.

Entry fields include Value, ImagePath, TextScale, Segments, and legacy style fields Bold, Italic, Underlined, Strikethrough, and Color.

Saved view fields under View are Configured, Scale, XRotation, YRotation, TranslateX, and TranslateY.

Item data is stored under minecraft:custom_data.UniversalPreview. Entities, block entities, and ordinary blocks use Fabric attachments; ordinary block data is keyed by block position on the owning chunk. Server sanitization limits group count, entry count, text length, scale, coordinates, and color before data reaches rendering.

Universal Preview（通用预览）

Universal Preview 是一个独立的 Minecraft Java Edition Fabric 模组，用于在专用界面中预览物品、方块、掉落物和展示实体，并通过可视化锚点编辑器为它们制作可交互的图文说明。

当前模组版本：2.0.0。本项目不依赖任何地图或其它内容模组，也不包含或修改其它模组的加载画面、角色系统和游戏逻辑。

English documentation: README_EN.md

支持版本

Minecraft	Gradle 项目	Fabric Loader	Fabric API	发布文件
26.1	根项目	0.19.2	0.145.1+26.1	universal-preview-2.0.0-fabric_26.1.jar
26.1.2	:fabric-26.1.2	0.19.5	0.155.2+26.1.2	universal-preview-2.0.0-fabric_26.1.2.jar
26.2	:fabric-26.2	0.19.5	0.159.0+26.2	universal-preview-2.0.0-fabric_26.2.jar

三个版本共享源码、资源、模组 ID universal_preview 和数据格式。每个实例只能安装与其 Minecraft 版本对应的一份 JAR。

基本预览

• 默认预览键为 V。
• 普通模式下，主手持有物品时按 V，预览该物品。
• 同种物品无论堆叠数量多少，预览界面都只渲染一个模型。
• 临时预览实体只存在于客户端，不会生成掉落物、放置方块或改写世界。
• 模型初始位于屏幕中心，并根据模型包围盒与可用屏幕区域限制初始尺寸。
• 方块和方块展示实体使用便于看清立体结构的初始角度。

预览界面操作

操作	功能
鼠标左键拖动	旋转
鼠标滚轮	缩放
Ctrl + 鼠标左键拖动	平移
R	恢复当前目标保存的初始视角
Esc	关闭

详情锚点展开时会锁定模型滚轮缩放。旋转、平移或缩放模型会隐藏锚点；恢复初始视角后锚点重新出现。

预览模式与许可

/up preview\_mode <true|false> <targets>  
/up editor <true|false> <targets>  

预览模式使用许可列表，避免场景中所有物体同时高亮。编辑者模式取代了手动添加原版玩家标签的旧流程。

获取预览许可笔：

/give @s universal\_preview:preview\_permission\_tool  

玩家需要同时开启预览模式和编辑者模式。手持许可笔时：

• 左键普通方块：给予预览许可；
• 左键掉落物、物品展示实体、方块展示实体或文本展示实体：给予实体预览许可；
• 右键上述目标：取消预览许可；
• 获得许可且位于准心下的目标会高亮，按 V 可打开预览。

实体选择使用独立射线检测和修正后的展示实体包围盒。即使原版命中结果落在实体后方的方块上，也会优先选择准心实际指向的掉落物或展示实体；被方块遮挡的实体不会越墙选中。

服务端控制预览界面

/up preview\_ui open <targets>  
/up preview\_ui close <targets>  
/up preview\_ui open <targets> <id>  
/up preview\_ui progress\_bar <true|false> <targets>  

• 不提供 <id> 时，打开每个目标玩家主手物品的预览。
• <id> 可以是物品 ID，也可以带原版或其它模组注册的数据组件。
• <id> 也可以是实体 ID，并可追加原版 SNBT 实体数据。
• ID 通过当前运行环境的实际注册表解析，没有写死原版物品列表。
• 无效 ID、组件或 SNBT 会返回明确错误，不会使客户端崩溃。
• close 会关闭预览界面及其锚点编辑界面。

示例：

/up preview\_ui open @s  
/up preview\_ui open @a minecraft:diamond  
/up preview\_ui open @s minecraft:stone[minecraft:custom\_name='{"text":"样品"}']  
/up preview\_ui open @s minecraft:item\_display{item:{id:"minecraft:diamond",count:1}}  
/up preview\_ui close @a  

按住 V 进度圈

progress_bar 默认是 false。设为 true 后：

• 按住预览键约 750ms 才打开界面；
• 准心下方按顺时针方向绘制进度圆；
• 中途松开按键会取消并归零；
• 一次按住只会触发一次，必须松开后才能再次触发；
• 指令打开预览界面时也会播放相同进度；
• 它只控制预览入口，不影响其它 GUI。

进度圆通过 Minecraft/Fabric 的 HUD 提取接口绘制，不直接改写 OpenGL 状态。

详情锚点

没有保存群组的目标不会出现固定圆点。只有确实存在详情群组时，预览界面才显示圆环锚点。

观察者交互

• 悬停圆环显示群组名 Tooltip；
• 点击后从锚点向屏幕内侧平滑展开；
• 同时只允许展开一个群组，打开另一个时原群组平滑收起；
• 文字和图片直接铺在预览层上，不增加遮挡模型的大块详情底板；
• 圆环与内容之间显示细连接线；
• 内容根据屏幕边界选择向左、向右、向上或向下的安全位置；
• 长文本不会替换为省略号，全部内容均被保留；
• 内容超过屏幕高度时使用独立平滑滚动条阅读。

可视化编辑

编辑者在空白处右键可新建锚点；右键已有锚点可编辑、删除或修改位置。修改位置时显示网格和跟随鼠标的圆环，位置被限制在屏幕安全范围，松开鼠标自动保存。

编辑面板提供：

• 群组名称；
• 群组标题字号滑动条（0.5x～2.0x）；
• 执行指令代码输入框；
• “仅执行一次 / 可重复执行”切换；
• 文本与图片两类元素；
• 每个文本元素独立字号滑动条；
• 粗体、斜体、下划线、删除线；
• 选区文字颜色；
• 支持拖动的二维色盘与色相条；
• Hex #RRGGBB 或 RGB R,G,B 输入；
• 每个元素的勾选框、全选和批量删除；
• 固定于面板底部的保存与取消按钮。

编辑面板使用固定头部、固定操作区和独立的元素列表视口。长文本框内部滚动和元素列表滚动互不干扰，滚轮不会重建整个界面；所有内容都通过裁剪区域限制在底板内。

富文本选区

文本按 Unicode 码点和实际换行测量鼠标位置，支持中文、英文、数字与混合换行。滚动文本后，选区命中会计入首个可见行偏移。工具栏仅改动选区；未建立选区时作用于当前元素全文。样式按文本片段保存，不会因为修改一个片段而覆盖其它片段。

图片元素

世界图片目录（单人、局域网房主和专用服务器统一使用）：

saves/<存档>/universal\_preview/  

• 支持目录下任意层级子文件夹；
• 只读取 .png；
• 文件选择列表按文件夹层级缩进，类似代码编辑器的目录树；
• 选择前验证真实路径，阻止 .. 和符号链接逃逸存档目录；
• 单文件最大 8 MiB，宽高最大 4096，总像素最大 16777216；
• 读取成功后在元素列表和观察者详情中等比缩放；
• 图片占用独立布局项，不遮挡前后文本或图片；
• 读取失败只记录错误并显示失败状态，不导致崩溃；
• 多人游戏以服务端世界目录中的图片为准，房主或服务器只需保存一份 PNG；
• 远程玩家点开锚点时，客户端按已保存的相对路径向服务端请求图片并自动显示，无需手动复制；
• 传输使用受限分块和 SHA-256 完整性校验，客户端收到后再次验证 PNG 类型、尺寸和像素总量；
• 远程图片仅保存在客户端内存纹理缓存中，不写入玩家磁盘，退出服务器时立即释放；
• 图片同步要求服务端、房主和加入的玩家都安装 Universal Preview。

锚点执行指令

编辑者可在群组中填写不带 / 的指令。空输入不会执行任何内容。

• “仅执行一次”：同一次预览会话内首次展开时执行一次；
• “可重复执行”：每次重新展开都可以执行；
• 编辑者点击锚点进入编辑，不会误执行群组指令；
• 观察者展开锚点时才触发。

安全模型：客户端只发送目标类型、目标 ID/坐标和群组 ID。服务端会重新读取自己保存的群组数据、检查目标存在性与距离，再执行其中的指令。客户端不能把任意命令字符串塞进执行数据包。

自定义初始视角

编辑者打开目标后，可像普通预览一样旋转、缩放和平移。操作结束后，当前状态会保存为该目标新的初始状态：

• 后续打开直接使用保存后的角度、大小和位置；
• R 返回保存后的状态；
• 锚点以这个新状态为显示基准；
• 滚轮连续变化使用 250ms 防抖，避免每个滚轮刻度都发送网络更新；
• 保存后当前状态立即提升为新的基准，不会出现模型突然放大或偏移。

数据格式

当前 SchemaVersion 为 2。旧数据缺少新字段时使用默认值，仍可读取。

群组主要字段：

字段	说明
Id	群组唯一 ID
Title / TitleKey	标题或翻译键
Color	圆环 RGB 颜色
AnchorX, AnchorY	屏幕归一化坐标
Command	不带斜杠的指令
RepeatCommand	是否可重复执行
TextScale	群组标题字号
Entries	元素列表

元素主要字段：

字段	说明
Value	文本内容；图片元素可为空
ImagePath	相对 universal_preview 目录的 PNG 路径
TextScale	当前文本元素字号
Segments	富文本片段列表
Bold, Italic, Underlined, Strikethrough, Color	旧格式兼容字段

视角保存在 View 中，包含 Configured、Scale、XRotation、YRotation、TranslateX 和 TranslateY。

物品数据位于 minecraft:custom_data.UniversalPreview。实体、方块实体和普通方块使用 Fabric 数据附件；普通方块按坐标保存在所属区块中。服务端会限制群组数、元素数、文本长度、字号、坐标和颜色，坏数据不会直接进入渲染层。