Universal Preview

Universal Preview

Overview

Universal Preview, or UP for short, is a Minecraft Java Edition mod for inspecting objects and creating interactive descriptions with text and images.

Players can open items, blocks, dropped items, and display entities in a dedicated preview screen, then rotate, zoom, and pan to see details that are easy to miss during normal gameplay. For map makers, UP also includes a visual anchor editor: place a small ring beside an object, add a description or an image, and let players click it to read more.

The history of an exhibit, an investigation note, or a photograph of a clue can all become part of the game this way. UP works as a simple model inspection tool, but it can also provide item examination and contextual information for puzzle, exploration, and story-driven maps.

Basic Preview

The default preview key is **V**. You can change it in the game's key bindings.

Normally, holding an item in your main hand and pressing the preview key opens the screen. Only one model is rendered, regardless of the stack size, so stacked items do not produce overlapping copies.

With Preview Mode enabled, you can also aim at a permitted object in the world and press the preview key. Supported targets include regular blocks, dropped items, item display entities, block display entities, and text display entities.

| Control | Action |

| --- | --- |

| Left-click and drag | Rotate the model |

| Mouse wheel | Zoom in or out |

| Ctrl + left-click and drag | Pan the model |

| R | Restore the initial view |

| Esc | Close the preview screen |

Previews use temporary client-side render objects. Opening a preview does not spawn actual dropped items or place blocks in the world. Viewing and editing are separate: a regular player's inspection controls do not overwrite the initial view configured by the creator.

Text and Image Anchors

Anchors are the small rings shown in the preview screen. Each anchor represents a group of information. Objects without configured content do not automatically receive anchors; creators choose how many to add, where to place them, and what each one displays.

Hovering over a ring shows the group name. Clicking it smoothly expands its text and images along a connecting line. A group named "Origin" might explain where an item came from, while "Investigation Notes" or "Scene Photos" can keep other information separate.

Only one group is expanded at a time. Opening another anchor collapses the previous group, keeping multiple descriptions from crowding around the model. Content is positioned to stay within the screen boundaries. Longer text wraps and can be scrolled, rather than having the rest replaced with an ellipsis.

Rotating, zooming, or panning the model temporarily hides the anchors. Press **R** to restore the initial view and show them again. While a detail group is expanded, mouse-wheel zooming of the model is locked so you can focus on reading.

Visual Editing

With editor permission, right-click an empty area of the preview screen to create an anchor. Right-click an existing anchor to edit its content, delete it, or change its position.

Moving an anchor does not require entering coordinates. In move mode, a grid appears and the ring follows your cursor. Move it into place and release the mouse button to save its position.

The editor lets you:

• Name each group and adjust its title size independently.

• Add text or images, combining both within the same group.

• Set a separate font size for each text element.

• Apply bold, italic, underline, and strikethrough formatting.

• Select part of the text and change only that selection's color or style.

• Choose colors using a color picker, a hue slider, or Hex and RGB values.

• Select individual elements, or select all and delete them together.

• See a live preview of the content on the right.

• Save your changes or cancel the panel's unsaved edits.

Formatting is applied visually, without writing Markdown. To emphasize a few words, select them first and then apply a style. To change an entire passage, select all of its text. Formatting is preserved separately for different text spans.

Custom Initial Views

Not every model looks its best from the same angle. For long, narrow items, unusual display entities, or text displays, creators can rotate, zoom, and pan in editor mode to set up a suitable starting view.

When the adjustment is finished, the new angle, scale, and position are saved as that object's initial view. Opening it again or pressing **R** returns to this setup. The saved view also becomes the reference state for displaying its anchors.

Preview Mode and Permissions

UP manages three things separately: whether a player can preview world objects, whether a player can edit, and whether an object is available for preview.

**Preview Mode** allows a player to inspect world objects through the crosshair. **Editor permission** allows a player to create and modify anchors and use the permission tool. **Object preview permission** determines which blocks or entities can be selected for inspection.

Regular players do not need editor permission to read existing content. Turning off Preview Mode does not disable held-item previews.

Administrators can configure player permissions with:

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

/up editor <true|false> <targets>

For example, to enable Preview Mode and editor access for yourself:

/up preview\_mode true @s

/up editor true @s

Here, @s targets yourself and @a targets all players. You can also enter a player name. Administrative commands require the appropriate permissions; in singleplayer, cheats must be enabled.

Preview Permission Tool

The Preview Permission Tool lets you configure objects directly in the world, making it useful while building a scene and choosing what players can interact with.

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

With both Preview Mode and editor permission enabled, hold the tool and left-click a target to grant preview permission, or right-click to revoke it. The tool supports regular blocks, dropped items, and all three display entity types.

Permitted targets are highlighted when the player aims at them and the preview conditions are met. The player can then press the preview key to open them. Creators can therefore make only relevant objects available for inspection, rather than turning the entire scene into preview targets.

The tool provides its own selection feedback while held. To check whether permission was applied successfully, switch to another hotbar slot and aim at the target again.

Configuring Targets with Commands

For bulk changes or integration with map functions, you can also use entity selectors or block coordinates:

/up preview\_permissions set <entity\_selector> <true|false>

/up preview\_permissions set <x> <y> <z> <true|false>

For example, to allow item display entities to be previewed, or grant permission to the block beneath you:

/up preview\_permissions set @e[type=minecraft:item\_display] true

/up preview\_permissions set ~ ~-1 ~ true

Entity selectors apply to supported display entities and dropped items. Block coordinates must point to a loaded, non-air block.

Images and Multiplayer

Image elements load PNG files from the world's directory. For singleplayer worlds, the usual location is:

saves/<world\_name>/universal\_preview/

You can organize images into subfolders, for example:

universal\_preview/

|-- items/

| `-- lantern.png

`-- clues/

`-- room/

`-- photo.png

On a dedicated server, use the universal_preview folder inside the server's actual world directory. You do not need to reproduce the singleplayer saves path.

Choose "Add Image" in the editor to browse the folder hierarchy. Once loaded, the image appears in the element list and the live preview. It scales proportionally to fit the available space and occupies its own place in the layout, separate from the text and images before or after it.

PNG is supported, with a maximum file size of **8 MiB** and a maximum width and height of **4096 pixels** each.

In multiplayer, images are provided by the host or server. When another player opens the relevant anchor, their client requests and displays the image, so every player does not need to copy the files manually. The server and joining players must have matching mod versions and the required dependencies installed.

Anchors store relative image paths. When sharing a map, include its image directory as well. Moving or deleting the original files can make existing image paths stop working.

Commands Attached to Anchors

Alongside displaying information, anchors can run commands when a player expands their content. This can be used for messages, story progression, or integration with other map mechanics. Leave the command field empty when you do not need this feature.

Enter the command without the leading /, then choose one of two behaviors:

• **Run once**: executes only the first time the group is expanded during the current preview session. Closing and reopening the preview starts a new session; this does not mean once permanently across the entire world.

• **Repeatable**: can execute each time the group is expanded again.

Opening an anchor for editing does not trigger its command. Commands are triggered when regular viewers expand the content. Since editor access includes configuring content and commands, it should only be granted to trusted map makers or administrators.

Server-Controlled Preview Screens

Map makers can open or close preview screens for specific players using commands. This makes it possible to integrate previews into story sequences, interactions, and other events without always requiring the player to press a key.

/up preview\_ui open <targets>

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

/up preview\_ui close <targets>

Without an ID, the command previews each target player's main-hand item. With an ID, you can specify an item and its data components, or an entity and its SNBT data. Items and components are resolved through the registries of the running game, rather than a hardcoded list of vanilla entries.

close closes the preview screen and its anchor editor. Temporary previews created by commands are for display and have no actual world target to write changes back to. To edit a real item, block, or entity, open it through the normal preview controls.

Optional Hold-to-Open

By default, pressing the preview key opens the screen immediately. You can instead require players to hold it for about **750 milliseconds**, allowing a progress ring beneath the crosshair to complete before the preview opens:

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

Releasing the key early cancels and resets the progress. Each continuous hold can trigger only once. Command-opened previews also play the progress animation. Change true to false to restore immediate opening.

Data Configuration for Map Makers

Anchor content and initial views can be configured through data as well as through the editor. This makes them easier to integrate with map functions, item rewards, and generated scenes.

Items can carry preview information in the universal_preview:preview_data data component. Entities store their corresponding preview data, while regular blocks use coordinate-based records in their chunks. Creators can therefore prepare items with predefined descriptions or configure spawned display entities without rebuilding the same content manually each time.

Not every regular block has block entity NBT, so this data cannot simply be included in a vanilla /setblock command. Place the block first, then write its preview data using the dedicated command:

/up preview\_data block <x> <y> <z> <document\_snbt>

Block items carrying preview data can pass their preview document to the block when placed normally. **Preview content and preview permission are separate**: having a description does not automatically make an object available through the crosshair. Its permission still needs to be configured separately.

Where It Fits

• **Exploration and puzzle maps**: let players examine clues, read notes, and compare photographs.

• **Story-driven and roleplay scenes**: add an item's history, purpose, personal messages, or event details.

• **Exhibitions and item displays**: present models together with descriptions that players can choose to explore.

• **Model and resource inspection**: rotate and enlarge items or display entities to check details and presentation.

UP does not automatically generate stories or descriptions. The content is written by the creator. If you only want a closer look at a model, use the basic preview. Add anchors, images, and commands when you need more interaction.

Usage Notes

Install the mod and its dependencies for your game environment. In multiplayer, both the client and server need the appropriate installation. Saving anchors writes preview configuration to the target, so keeping backups is recommended when working on important maps.

Resource packs, custom models, and shaders can also affect how previews look. After preparing content for a map, check it once more as a regular player to confirm that the view, text, images, and triggered actions work as intended.

Universal Preview（通用预览）

概述

Universal Preview，简称 UP，是一个用于 Minecraft Java 版的物品预览与图文信息编辑模组。

玩家可以在独立的预览界面中查看物品、方块、掉落物和展示实体，自由旋转、缩放和平移，观察平时不容易看清的模型细节。对于地图制作者，UP 还提供了可视化锚点编辑器：在目标旁边放置一个小圆环，写上说明、添加图片，玩家点开后就能阅读。

一件陈列品的来历、一处场景的调查记录、一张线索照片，都可以通过这种方式放进游戏。它既可以作为查看模型的小工具，也可以用于解谜、探索、剧情地图中的物品检索和信息展示。

基础预览

默认预览按键为 **V**，可以在游戏的按键设置中修改。

通常情况下，主手拿着物品，按下预览键即可打开界面。同一种物品无论堆叠了多少个，界面中都只显示一个预览模型，不会因为数量增加而重叠。

开启预览模式后，还可以看向世界中已获得预览许可的目标，再按预览键查看。支持的目标包括普通方块、掉落物，以及物品展示实体、方块展示实体和文本展示实体。

| 操作 | 作用 |

| --- | --- |

| 鼠标左键拖动 | 旋转模型 |

| 鼠标滚轮 | 放大或缩小 |

| Ctrl + 鼠标左键拖动 | 平移模型 |

| R | 恢复初始视角 |

| Esc | 关闭预览界面 |

预览使用客户端的临时渲染对象，不会因此在世界中生成真实掉落物或放置方块。查看模型与编辑配置是两回事，普通玩家的观察操作不会替制作者改写目标的初始视角。

图文锚点

锚点是预览界面中的小圆环，每个锚点对应一组信息。没有配置过内容的目标不会自动出现圆环，制作者可以根据需要决定放几个、放在哪里，以及分别展示什么。

鼠标悬停时会显示群组名称，点击后，文字和图片沿着连接线平滑展开。可以把一组命名为“来源”，介绍物品的来历；也可以创建“调查记录”“现场照片”等群组，把不同的信息分开。

界面同一时间只展开一组信息。点开另一个锚点时，上一组会收起，避免多段内容同时挤在模型旁边。图文展示会根据屏幕边界调整位置，较长的正文可以换行、滚动阅读，不会仅用省略号代替剩余内容。

旋转、缩放或平移模型时，锚点会暂时隐藏；按 **R** 恢复初始视角后重新显示。详情展开期间，模型的滚轮缩放会锁定，方便阅读内容。

可视化编辑

获得编辑权限后，在预览界面的空白处右键即可新建锚点。右键已有锚点，可以编辑内容、删除锚点或修改位置。

移动锚点不需要填写坐标。进入移动状态后，界面会显示网格，圆环跟随鼠标移动；放到合适的位置后，松开鼠标即可保存。

编辑器可以完成以下操作：

• 设置群组名称，单独调整群组标题字号。

• 添加文本或图片，同一群组内可以组合多种内容。

• 为每个文本元素分别设置字号。

• 使用粗体、斜体、下划线和删除线。

• 框选部分文字，只修改选中部分的颜色和样式。

• 通过色盘、色相条或 Hex、RGB 输入设置颜色。

• 勾选单个元素，或全选后批量删除。

• 在右侧实时查看当前图文的展示效果。

• 保存内容，或取消本次尚未保存的面板修改。

文字样式通过可视化工具设置，不需要手写 Markdown。需要强调一句话中的几个字时，先选中它们，再修改样式即可；需要修改整段文字时，可以先全选。不同文字片段的格式会分别保留。

自定义初始视角

不同模型适合的观察角度并不相同。对于细长的物品、特殊展示实体或文本展示内容，制作者可以在编辑状态下直接旋转、缩放和平移，调整出合适的初始画面。

操作结束后，新的角度、大小和位置会作为该目标的初始状态保存。以后再次打开，或按 **R** 复位，都会回到这个设定；锚点的显示也以新的初始状态为基准。

预览模式与权限

UP 将“玩家能否预览世界目标”“玩家能否编辑”和“目标是否允许被预览”分开管理。

**预览模式**决定玩家能否通过准心查看世界中的目标；**编辑权限**决定玩家能否制作、修改锚点并使用许可笔；**目标预览许可**则决定哪些方块或实体可以被选中查看。

普通玩家阅读已经制作好的图文，不需要编辑权限。关闭预览模式，也不等于禁止手持物品预览。

管理员可以通过以下指令设置玩家状态：

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

/up editor <true|false> <targets>

例如，为自己开启预览模式与编辑权限：

/up preview\_mode true @s

/up editor true @s

其中，@s 表示自己，@a 表示所有玩家，也可以填写玩家名称。管理指令需要相应权限，单人游戏需要允许作弊。

预览许可笔

预览许可笔用于直接在世界中配置目标，适合边布置场景、边设置可交互物体。

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

玩家同时开启预览模式和编辑权限后，手持许可笔，对目标左键可给予预览许可，右键可取消。它支持普通方块、掉落物和三类展示实体。

获得许可的目标在符合预览条件、被准心指向时会高亮，玩家可以按预览键打开。这意味着制作者可以只开放真正需要调查的物体，不必让整个场景都变成可预览目标。

持笔时有编辑选中反馈。验证许可是否生效时，建议切换到其他物品栏，再重新指向目标确认。

通过指令配置目标

需要批量配置，或与地图函数配合时，也可以使用实体选择器或方块坐标：

/up preview\_permissions set <实体选择器> <true|false>

/up preview\_permissions set <x> <y> <z> <true|false>

例如，允许物品展示实体被预览，或为脚下方块开启许可：

/up preview\_permissions set @e[type=minecraft:item\_display] true

/up preview\_permissions set ~ ~-1 ~ true

实体选择器作用于支持的展示实体和掉落物；方块坐标需要指向已经加载的非空气方块。

图片与多人展示

图片元素读取世界目录中的 PNG 文件。单人存档通常使用以下路径：

saves/<存档名称>/universal\_preview/

可以继续创建子文件夹，例如：

universal\_preview/

├─ items/

│ └─ lantern.png

└─ clues/

└─ room/

└─ photo.png

专用服务器使用服务器实际世界目录下的 universal_preview 文件夹，不必照搬单人游戏的 saves 路径。

在编辑器中选择“添加图片”后，可以按文件夹层级查找文件。图片加载成功后会出现在元素列表和效果预览中，并按可用空间等比缩放，与前后的文字、图片分开排列。

当前支持 PNG，单文件最大 **8 MiB**，宽、高均不能超过 **4096 像素**。

多人游戏中的图片由房主或服务器提供。其他玩家打开相关锚点时，会请求并显示对应图片，不需要每个人手动复制一份。使用这项功能时，服务端和加入的玩家都需要安装匹配的模组及前置。

锚点保存的是图片相对路径。分享地图时，需要把世界中的图片目录一起打包；删除或移动原文件后，原有路径可能无法继续读取。

锚点执行指令

除了展示信息，锚点还可以在玩家展开内容时触发指令，用于提示、剧情推进或与地图中的其他机制衔接。不需要这项功能时，将指令输入框留空即可。

填写指令时不需要开头的 /，并可选择：

• **仅执行一次**：在同一次预览会话中，仅首次展开时执行。关闭预览后重新打开，属于新的会话，并不是整个存档永久只能执行一次。

• **可重复执行**：每次重新展开这个群组时都可以执行。

编辑者进入锚点编辑时不会触发群组指令，普通玩家展开内容时才触发。编辑权限涉及内容及指令配置，建议只授予可信的地图制作者或管理员。

服务端控制预览界面

地图制作者可以通过指令打开或关闭指定玩家的预览界面，将预览接入剧情、交互或其他流程，而不必始终要求玩家自行按键。

/up preview\_ui open <targets>

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

/up preview\_ui close <targets>

未指定 ID 时，打开目标玩家主手物品的预览；指定 ID 时，可以传入物品及其数据组件，或实体及其 SNBT 数据。物品和组件通过当前运行环境的注册表解析，不局限于写死的原版列表。

close 会关闭预览及其锚点编辑界面。通过指令创建的临时预览用于展示，没有可写回的实际世界目标；要编辑真正的物品、方块或实体，应通过正常预览入口打开。

可选的长按入口

默认情况下，按一下预览键就会打开界面。也可以改成先按住约 **750 毫秒**，让准心下方的进度圈走完后再进入：

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

中途松开会取消并清空进度；同一次按住只触发一次。指令打开预览时也会播放对应进度，将 true 改为 false 即可恢复直接打开。

数据配置与地图制作

锚点内容和初始视角不仅可以在界面里编辑，也可以通过数据方式配置，便于与地图函数、物品发放及场景生成结合。

物品可以通过 universal_preview:preview_data 数据组件携带预览信息；实体保存对应的预览数据；普通方块则通过区块中的坐标记录保存配置。这样，制作者可以制作带有预设说明的物品，或为生成的展示实体配置已有信息，不必每次重新手动编辑。

普通方块并不都有方块实体 NBT，不能简单地把这类数据塞进原版 /setblock。可以先放置方块，再通过专用指令写入：

/up preview\_data block <x> <y> <z> <文档SNBT>

携带预览数据的方块物品，在正常放置时可以继承相应的预览文档。**预览内容和预览许可是两回事**：有说明数据，不代表已经允许玩家通过准心打开，许可仍需单独设置。

适合用在哪里

• **探索与解谜地图**：让玩家查看线索物品、阅读记录、对照现场照片。

• **剧情与角色扮演场景**：为道具补充来历、用途、人物留言或事件信息。

• **展览与物品陈列**：让模型和说明放在一起，玩家可以主动选择感兴趣的内容。

• **模型与资源检查**：旋转、放大查看物品与展示实体，观察细节和呈现效果。

UP 不会自动替目标生成故事或介绍，展示内容由制作者自行编写。只想看看模型，可以直接使用基础预览；需要更完整的信息交互，再逐步加入锚点、图片和指令即可。

使用提醒

安装时请选择与游戏环境对应的模组及前置文件；多人使用时，客户端和服务端都需要正确安装。保存锚点会写入目标的预览配置，制作重要地图前建议保留备份。

使用资源包、自定义模型或光影时，实际呈现效果也会受到相关资源与渲染环境影响。为地图制作预览内容后，建议再以普通玩家身份检查一次，确认视角、文字、图片和触发行为符合预期。