Universal Preview

# Universal Preview

**Inspect objects, discover their stories, and keep the clues that matter.**

Universal Preview, or **UP**, is a Minecraft Java Edition mod for inspecting objects, creating interactive descriptions with text and images, and keeping a personal clue notebook.

Hold an item and press **V** to rotate, zoom, and pan its model in a dedicated preview screen. For map and modpack creators, UP also provides visual editing tools: mark a spot on a model, add text or images, and give players something to discover as they examine it.

It can be a convenient model viewer or an item examination system for your map. An object’s history, a note on a nameplate, or a photograph of a clue can all become part of the experience, with the content written by you.

In **3.0.1**, players can also save information they have read to their own **clue notebook**, revisit it later, mark important entries, and arrange them in their preferred order. Creators place the clues; players decide what to keep.

## Inspect Items and Objects in the World

Press the preview key while holding an item in your main hand to open its preview. Only one model is rendered, regardless of the stack size, so stacked items never produce overlapping copies.

With Preview Mode enabled for a player, they can also aim at permitted objects in the world and inspect them. Supported targets include:

– Regular blocks.

– Dropped items.

– Item display entities.

– Block display entities.

– Text display entities.

Eligible targets highlight when aimed at, helping players recognize what they can inspect. Creators choose which objects receive permission instead of making the entire scene inspectable by default.

| Control | Action |

| — | — |

| V | Open the preview; rebindable in the controls menu |

| B | Open your personal notebook; rebindable in the controls menu |

| 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 saved by the creator |

| Esc | Close the preview, or cancel/exit an active temporary operation first |

The preview model is rendered temporarily on the client. Displaying it does not place a block or spawn a real entity in the world. A regular player’s viewing controls do not overwrite the creator’s saved view.

The interface uses a fixed UI size independent of Minecraft’s GUI Scale, while its layout adapts to the available screen space.

## Place Discoverable Anchors on Model Surfaces

The small rings in a preview are **anchors**, each representing a group of information. Objects without configured content do not receive rings automatically. Creators decide how many to add, where to put them, and what they reveal.

**Surface anchors** attach to a particular part of a model. As players rotate, pan, or zoom, the rings follow their attached positions. An anchor hides when the model obscures its location and reappears when that location becomes visible. Players do not need to match the exact angle used during editing, and creators can place information on the back of an object for players to discover.

For information about the whole object, creators can add a **screen overview** in empty space. These anchors remain at their screen positions when the model rotates.

Hover over a ring to see its group name, then click to smoothly expand its text and images along a connecting line. Only one group is expanded at a time. Content is arranged according to its actual width and the screen boundaries: short descriptions stay close to their rings, while longer content wraps and scrolls instead of being replaced with an ellipsis.

While details are expanded, model zoom is temporarily locked so the wheel can be used to read the content. Dragging the model closes the details without hiding all surface anchors or screen overviews.

Surface attachment supports static models whose geometry can be reliably captured. Objects that do not support surface detection, such as text displays, special renderers, animated textures, or dynamic billboards, can still use previews and screen overviews. Legacy two-dimensional anchors retain their previous visibility rules and can be manually converted into surface anchors.

## Keep the Clues You Discover

You do not have to remember every detail. After expanding an anchor, click the **bookmark beside its title** to save that group to your personal notebook. This records only the selected group, not every anchor on the object, and does not list hidden information you have not recorded.

Press **B** to open the notebook, or use the notebook button in the preview. Saving a clue does not interrupt your investigation. Returning from the notebook preserves the model’s view and the expanded group. Regular players can record clues without editor permission.

### Information from the Same Object Stays Together

The notebook groups entries into source cards. The source icon appears on the left with its name underneath; recorded anchor titles, text, and images are arranged on the right.

For example, a diamond might have three anchors: “Origin,” “Marks on the Back,” and “Appraisal.” Recording the first two gives you **one diamond card containing two clues**. It does not reveal the third anchor. Recording the same content again does not use another slot; changed content can be saved as a separate snapshot.

– Each page holds up to **5 source cards**, not 5 anchors. Additional cards go on later pages.

– Short records stay compact, while cards with more information expand to fit their content without repeating the source icon for every anchor.

– Long titles and text wrap and scroll rather than hiding the remainder behind an ellipsis.

– Images retain their proportions and occupy their own space in the layout. Click an image to view it at a larger size.

– The top controls and bottom page navigation remain accessible while the content area scrolls.

### Mark, Delete, and Arrange Individual Clues

Clues within the same source card can be managed separately:

– Click a star to mark one clue as important, or click again to unmark it. Other entries are unaffected, and starring does not automatically change the order.

– Switch to the important filter to see only the entries you have marked.

– Deletion requires confirmation and removes only your selected record, not the original object, anchor, or another player’s copy. Deleting the last clue on a card also removes the empty card.

– Drag a card’s left-hand icon/name area or grip to move the whole card. Drag an individual clue’s grip to reorder it within its source card.

– Selection highlights, a cursor-following label, and an insertion line show where a dragged entry will go. Dragging near the edges scrolls the content, and whole cards can be moved between pages.

Sorting is disabled while the important filter hides other entries; switch back to all entries to reorder them. There is no undo or recycle bin for deletion, so check the confirmation before proceeding. You can investigate the original content again and record it anew.

### A Snapshot of What You Read

Notebook entries are **read-only snapshots**, preserving titles, font sizes, text colors and formatting, images, and element order. Removing the source object, revoking its preview permission, or editing its description later does not retroactively remove or overwrite existing records.

Images are archived by the server when a clue is recorded. Once saved, they remain available even if the original files are moved, deleted, or replaced. In multiplayer, clients automatically receive the images needed for their own records without copying files manually. Notebooks are saved separately for each player and world, not shared as a server-wide clue collection.

**Recording and rereading do not replay commands attached to anchors** or modify the original clues. The notebook is a personal investigation record, not an item container, a free-form text editor, or another 3D preview screen.

## Set the Capacity Your Map Needs

Players can save **20 clues** by default. Administrators can set the limit anywhere from **0 to 256**. Capacity counts anchors: recording three anchors from one object uses three slots, while still occupying just one source card for pagination.

“`mcfunction

/up notebook limit <count> <targets>

/up notebook limit query <targets>

/up notebook limit reset <targets>

/up notebook default_limit <count>

“`

For example:

“`mcfunction

/up notebook limit 30 @a

/up notebook limit query @s

/up notebook limit reset @s

/up notebook default_limit 20

“`

`limit` sets a personal limit for the selected online players. `query` checks usage and the effective limit. `reset` removes the personal override and restores the world default. `default_limit` changes the current world’s default for players without an override, including those who join later.

**A full notebook never automatically discards older clues.** Lowering a limit also preserves existing records. Setting it to zero prevents additions, but players can still read, mark, reorder, and delete what they have already saved.

Players who are **in Creative mode and have vanilla administrative permission** can also use the settings button at the top of the notebook to select an online player, adjust their limit, or restore the default. Creative mode alone, or UP editor permission alone, does not grant capacity management access.

## Visual Editing Without Entering Coordinates

With editor permission, right-click a supported model surface to create an anchor, or empty space to create a screen overview. The content editor opens immediately, without requiring coordinates, depth values, or visibility angles.

Right-click an existing anchor to edit, delete, or move it. During placement, a ring follows the cursor. In surface placement mode, white indicates a valid position and red indicates an invalid one. Click to confirm or press Esc to cancel. Screen overviews use a positioning grid with snapping instead.

Screen overviews and legacy anchors offer **Make surface anchor**, allowing them to be attached to a model without losing their content. Existing surface anchors simply use the move action to choose a new position.

An editor-only **anchor list** provides access to groups that are currently obscured or outside the view. Creators can edit, locate, move, and delete them without first finding their rings. Regular players do not receive this directory, so it does not reveal hidden information to them.

## Combine Text and Images

Each group can contain multiple text and image elements. An investigation note might include a description, a photograph, and an additional observation, all within the same group.

The editor supports:

– Group names and separate sliders for title size and each text element’s size.

– Bold, italic, underline, and strikethrough.

– Formatting or recoloring selected text without changing the rest of the element.

– A draggable color palette, hue bar, and HEX or RGB color input.

– Text and image insertion, individual element selection, and select-all batch deletion.

– A live preview of names, sizes, colors, and content beside the editor.

– Saving changes or canceling unsaved edits in the current panel.

Formatting is applied visually, without writing Markdown syntax. Long text wraps and scrolls, with separate scrolling for the content list and text inputs while settings and actions remain accessible.

Editors can also switch to **player-view preview** to try the anchor’s expanded presentation. This demonstration mode does not execute commands attached to anchors.

## Share Images with Other Players

Images are loaded from the `universal_preview` folder inside the current world directory. For single-player worlds, the path is usually:

“`text

saves/<world name>/universal_preview/

“`

Subfolders are supported, and the editor lists files hierarchically to help organize images by scene, item, or clue. Images scale proportionally to the available space and are arranged separately from surrounding text and image elements.

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

In multiplayer, the host or server provides the images. Other players automatically request the relevant resources when viewing them, so **they do not need to copy the files manually**. Dedicated servers use the `universal_preview` folder inside their actual world directory.

Original anchor groups store relative image paths. Include the image directory when distributing a map; moving or deleting an image can make the original anchor’s reference unavailable. Successfully archived notebook copies are unaffected, but their archive directory must also remain with the world.

## Save a Suitable Initial View for Each Object

Different models benefit from different viewing angles and sizes. Editors can rotate, zoom, and pan using the normal preview controls, then choose **Save as initial view** once the framing looks right.

Reopening the preview or pressing R restores that view. Simply rotating the model, editing text, or moving an anchor does not overwrite the default.

Surface anchors are not restricted to this default angle. Locating an anchor through the editor list also leaves the default view unchanged.

## Separate Viewing, Editing, and Target Permissions

UP separates three settings so creators can control what players can do:

| Setting | Controls |

| — | — |

| Player Preview Mode | Whether a player can inspect world targets by aiming at them |

| Player editor permission | Whether a player can create or edit content and use the permission tool |

| Target preview permission | Which blocks or supported entities can be selected for world previews |

Regular players do not need editor permission to read configured content. **Disabling Preview Mode does not disable held-item previews**, and an object having description data does not automatically give it world preview permission.

Administrators can use:

“`mcfunction

/up preview_mode <true|false> <targets>

/up editor <true|false> <targets>

/up preview_permissions set <entity selector> <true|false>

/up preview_permissions set <x> <y> <z> <true|false>

“`

`<targets>` accepts player names or player selectors such as `@s` and `@a`. Administrative commands require the appropriate permissions; single-player worlds need cheats enabled.

### Preview Permission Tool

UP includes a **Preview Permission Tool** with a dedicated three-dimensional pen model for configuring targets directly in the world:

– Left-click to grant preview permission.

– Right-click to revoke preview permission.

The player needs both Preview Mode and editor permission enabled. The tool supports regular blocks, dropped items, and all three display entity types. Dedicated ray targeting handles displays and dropped items instead of simply selecting the block behind them, while accounting for occlusion.

“`mcfunction

/give @s universal_preview:preview_permission_tool

“`

## Connect Anchors to Your Map’s Mechanics

Groups can do more than display information. Each can have a command that runs when a regular player actively expands it, allowing descriptions to connect to messages, story progression, or existing map mechanics. Enter the command without a leading `/`, or leave the field empty to run nothing.

Two execution modes are available:

– **Once per preview session:** runs only on the first expansion during that session. Closing and reopening the preview starts a new session; this is not a permanent once-per-world setting.

– **Repeatable:** runs whenever the group is expanded again.

Editing content, moving or locating anchors, and using player-view preview do not trigger attached commands. Since editor permission includes command configuration, it should only be granted to trusted creators or administrators.

## Open Previews with Commands or a Hold-to-Open Action

Creators can open and close previews for selected players, connecting them to story events, map functions, or other interactions:

“`mcfunction

/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, it can specify an item and its data components, or a supported display/dropped-item entity and its SNBT data. Items and components are parsed through the running environment’s registries rather than a hardcoded vanilla-only list. Invalid input produces an error message.

`close` also closes the anchor editor. Temporary previews created from a specified ID are for presentation: they do not spawn actual world targets and cannot write edits back to a nonexistent target.

By default, pressing V opens the preview immediately. An optional **hold-to-open** setting is available:

“`mcfunction

/up preview_ui progress_bar <true|false> <targets>

“`

When enabled, hold the preview key for about **750 milliseconds** while a clockwise progress ring fills below the crosshair. Releasing early cancels and resets progress, and each hold only triggers once. Command-opened previews also play the corresponding progress animation. Disabling the setting restores immediate opening without affecting other GUIs.

## Preset Content and Multiplayer Saving

Anchors and initial views are stored with their respective targets: items use the `universal_preview:preview_data` component, entities use a preview data attachment, and regular blocks use position records in their chunks. No separate database installation is required.

Alongside visual editing, creators can use item components, entity SNBT, and map functions to prepare objects with preset content. Regular blocks do not have a universal block-entity NBT field, so their documents can be assigned after placement using:

“`mcfunction

/up preview_data block <x> <y> <z> <document SNBT>

“`

Block items carrying preview data can pass their documents to normally placed blocks. Dropped items and item displays without independent configurations can inherit information from their contained items. If model spaces differ and surface positions no longer match, the anchors need repositioning rather than their text and images being discarded.

Edits are acknowledged by the server, with checks for changed targets and concurrent modifications. Conflicts and failed saves produce an error and retain the draft in the current preview instead of claiming it was saved. This is not an automatic draft backup that survives closing the game.

Personal notebooks are stored separately in the world’s `universal_preview_notebook` directory, including player records, capacity settings, and archived images. Keep the entire directory when backing up or moving a world, not just the text records or the original `universal_preview` image folder. Recording and organization actions are confirmed by the server; failures are reported rather than shown as successful client-only changes.

## What Can You Make with UP?

– **Exploration and puzzle maps:** inspect the back of an object, read clues, examine photographs, and keep important discoveries in the notebook for comparison.

– **Story and roleplay scenarios:** add item histories, personal messages, or event records.

– **Modpacks and item guides:** create illustrated descriptions and interaction points for selected items.

– **Exhibitions and displays:** let players choose which models and descriptions to explore.

– **Model and resource inspection:** view objects from different angles and check their presentation.

UP does not automatically generate stories or descriptions, or collect every clue for the player. Creators write the content, and players choose what to record. Use the basic preview when you only need to inspect a model, then add anchors, images, the notebook, and commands as your project needs them.

Choose the mod and dependencies matching your game environment, and install them correctly on both client and server for multiplayer. Back up important worlds before upgrading or editing. Resource packs, custom renderers, and shaders should also be checked in the environment where your map will actually run.