Holograms
Floating animated text, rotation, bobbing, click-to-trade and placeholders.
Commands 1#
Examples#
Put a welcome hologram at spawn#
You need a sign above the platform with an online counter, without editing JSON by hand.
/hologram create spawn_welcome
/hologram addline spawn_welcome &6&lWelcome
/hologram addline spawn_welcome &7Online: &f{neoessentials_online_players}/{neoessentials_max_players}
/hologram setrefresh spawn_welcome 10
/hologram scale spawn_welcome 1.3
/hologram hover spawn_welcome on 0.1 1.2
/hologram info spawn_welcome
create without coordinates places an empty hologram at your feet at +1.5 height with a refreshInterval of 5 s. addline appends lines at the bottom (& colours and {…} placeholders). setrefresh 10 updates placeholders no more often than every 10 s (the global pollIntervalTicks still limits how often the scheduler looks at all). scale 1.3 and hover on are visible immediately: every edit triggers a respawn. info prints the world, coordinates, line count and visual fields.
Label a physical crate_<id> crate#
After /crate admin setblock a service hologram already hangs over the chest — you need to change the text and size without creating a second one.
/hologram list
/hologram setline crate_vote 1 &6Vote Crate
/hologram setline crate_vote 2 &eRight-click to open, left-click for odds
/hologram scale crate_vote 1.3
setblock creates a regular hologram with the id crate_<crate id> (a second block of the same crate gets crate_vote_2, crate_vote_3). It shows up in /hologram list and in id completion. setline replaces the line and resets that line's frame animation. The label survives /hologram moveto|movehere; /crate admin removeblock removes the hologram together with the binding. With modules.hologramEnabled: false the crate block works, but there is no label.
Clone a hologram and make it spin#
You need a copy of the same sign at another portal, rotating "like a record".
/hologram copy spawn_welcome portal_welcome
/hologram movehere portal_welcome
/hologram billboard portal_welcome fixed
/hologram spin portal_welcome on 3 Y
/hologram spintrack portal_welcome on
copy clones the lines and visuals to a new id at the same point (via Gson, with no shared entity UUIDs). movehere moves it to you at Y+1.5. spin on Y turns on player tracking by default: the text stays readable from all sides. spintrack off leaves raw rotation around the world axis — then billboard fixed makes sense.
Reload holograms from storage#
You edited a record in the DataStore by hand and want to see the result without a restart.
/hologram reload
All display entities are despawned, the in-memory map is cleared, the holograms collection is read again, and the entities are spawned back. The reply is reload_success with the number of holograms. /neoe reload does not replace this path: holograms have their own command. Shop holograms get the shop NBT tag again after reload (retagAllShopHolograms); otherwise clicking them would stop being a purchase.
Edge cases#
Crate auto-holograms: id crate_<id>#
On /crate admin setblock, CrateHologramManager creates a hologram with the crate_ prefix. The base id is crate_<crate id>; if the crate already has a block, a _2, _3 suffix is added. The block→hologram binding is stored separately (crate_block_holograms), so a repeated setblock on the same block reuses the existing hologram instead of creating a second one, and the binding survives /hologram moveto|movehere. Manual line edits stay until removeblock is called.
What to do: Find the id in /hologram list / completion. Do not create a hologram with the same id by hand — create replies already_exists. Remove the block with the crate command, not /hologram delete, unless you want to leave a "live" chest without a label or the other way round.
shop_ holograms are overwritten#
A shop above a sign creates an interactive hologram shop_<dimension>_<x>_<y>_<z>. Clicking it is the same buy/sell as clicking the sign (400 ms limit). Any /hologram setline|moveto on such an id is overwritten by the next transaction or shop reload. Admin-created holograms never get interactive: true.
What to do: For a shop, change the hologram offset with the shop's tools, not /hologram. Looking at /hologram info shop_… is fine.
Storage is the holograms collection, not holograms.json#
Data is written to the DataStore on every registerHologram. The legacy neoessentials/holograms.json is imported once if the collection is empty. /hologram reload calls initialize(): clear memory → migrate (only if empty) → load from the DataStore. Editing the old file after migration does nothing. The upstream wiki, where reload "reads holograms.json from disk", is outdated.
What to do: For a manual edit, change the record in the holograms collection, then run /hologram reload.
/holo and a disabled module#
The alias is registered as Commands.literal("holo").redirect(hologram) only with commands.hologram and commands.holo. holo: true alone with hologram disabled creates neither the root nor the alias. modules.hologramEnabled: false skips HologramCommand.register entirely — crates are then placed without a label.
What to do: Keep both command flags enabled. Change the module with a restart.
Lines, frames and refresh#
insertline accepts an index 1 … lineCount+1 (insert at the end). setline clears that line's frames. addframes needs ≥ 2 frames separated by |, intervalTicks 1–200. create sets refreshInterval: 5 even if there are no placeholders yet; setrefresh 0 means do not recompute placeholders. The global hologram.pollIntervalTicks / animationInterval in config.json limit the scheduler for all holograms; /hologram reload does not re-read them — you need /neoe reload.
What to do: Change poll/animation with /neoe reload. Frames and text with the /hologram commands.
create, the world and id case#
exists/getHologram key the id via toLowerCase. The world argument of create is a word; if it has no :, minecraft: is prepended. Completion offers only the dimension path (overworld), not the full key. create without coordinates requires a player; create with x y z is available to the console. copy does not carry over entity UUIDs (a fresh spawn). delete despawns and removes the record.
What to do: Write ids in lower-case Latin from the start so you do not have to guess. From the console, always give coordinates and the world.
Detailed guide#
The section below is the project's original documentation (docs/Wiki/HologramSystem.md). Links to other wiki pages are rewritten to this site; the guides themselves are not edited, so upstream syncs stay conflict-free.
NeoEssentials uses Minecraft's native Display.TextDisplay entities to render holographic floating text in the world.
Holograms are fully server-side — no client mod required.
Storage#
Hologram data lives in the active storage backend (holograms collection — JSON files by default, or SQLite/MySQL if configured), loaded automatically on server start / world load. The legacy neoessentials/holograms.json file is only read once, to migrate any existing data into the storage backend on first boot after upgrading — it's not written to afterward.
Shop-managed holograms (prefixed shop_) are created and destroyed automatically by the Shop system — see Shop Holograms below.
Permissions#
| Permission |
Description |
neoessentials.hologram.admin |
Full access to all /hologram commands (also granted by OP level 4 or neoessentials.admin.*) |
Command Reference#
All commands use /hologram (alias /holo).
Creation & Deletion#
| Command |
Description |
/hologram create <id> <x> <y> <z> [world] |
Create a new empty hologram at the given coordinates. world defaults to your current dimension (e.g. minecraft:overworld). |
/hologram delete <id> |
Permanently delete a hologram. |
/hologram rename <id> <newid> |
Rename a hologram in-place (keeps position, lines, and settings). |
/hologram copy <id> <newid> |
Clone an existing hologram (all lines, animations, and visual settings) under a new ID at the same position. |
/hologram reload |
Despawn all holograms, reload holograms.json from disk, and respawn everything. |
Line Management#
Line numbers are 1-based (1 = topmost) in every command below.
| Command |
Description |
/hologram addline <id> <text> |
Append a new text line to the bottom of the hologram. |
/hologram insertline <id> <index> <text> |
Insert a line before index (1 = topmost). Existing lines shift down. index may also equal lineCount + 1 to insert at the end. |
/hologram setline <id> <index> <text> |
Replace the text of an existing line (1-based index). Clears any frame animation on that line. |
/hologram removeline <id> <index> |
Delete a specific line (1-based index). |
/hologram moveline <id> <from> <to> |
Reorder a line within the hologram (1-based indices). |
/hologram clearlines <id> |
Remove all lines from the hologram. |
Frame Animation (per-line)#
Lines can cycle through multiple text frames automatically.
| Command |
Description |
/hologram addframes <id> <lineIndex> <intervalTicks> <frame1\|frame2\|...> |
Set animated frames for a line (1-based lineIndex). Requires at least 2 frames, separated by \|. intervalTicks controls how many ticks each frame is shown (1–200; 20 ticks = 1 second). |
/hologram removeframes <id> <lineIndex> |
Remove frame animation from a line, restoring static text. |
Example:
/hologram addframes welcome 1 10 &aWelcome!|&eHello!|&bHi there!
This cycles the top line (line 1) every 10 ticks (0.5 s) through three coloured greetings.
Positioning#
| Command |
Description |
/hologram moveto <id> <x> <y> <z> |
Teleport the hologram to exact coordinates. |
/hologram movehere <id> |
Move the hologram to your current standing position (Y offset +1.5). |
/hologram align <id> |
Snap the hologram's X/Z to the nearest block centre (floor(x)+0.5, floor(z)+0.5). |
/hologram tp <id> |
Teleport yourself to the hologram's position. |
/hologram near [radius] |
List all holograms within radius blocks (default 20, max 1000) sorted by distance. |
Visibility & Refresh#
| Command |
Description |
/hologram toggle <id> |
Show or hide the hologram without deleting it. |
/hologram setrefresh <id> <seconds> |
How often placeholders are re-evaluated. 0 = static (never refresh). |
/hologram list |
List all holograms with their world, position, and line count. |
/hologram info <id> |
Detailed info including all visual/animation settings and line contents. |
setrefresh's seconds value is a per-hologram minimum — how often that specific hologram
checks for updates is also capped by the global scheduler's own poll rate, set once for every
hologram via hologram.pollIntervalTicks/animationInterval in config.json (both in server
ticks; defaults 20/1, matching the previous fixed 1-second/50ms behavior). pollIntervalTicks
only controls how often the scheduler checks whether a hologram is due for a refresh — it is
not itself the refresh rate, and lowering it below your setrefresh seconds value does nothing
visible; animationInterval covers only {animation:NAME} frame advancement,
/hologram addframes cycling, and spin/hover motion — there's no benefit setting it below 1,
since an animation's own frame duration is already clamped to a 50ms (1-tick) minimum. Apply
changes with /neoe reload.
Billboard Mode#
Controls how the hologram faces the viewer.
| Command |
Description |
/hologram billboard <id> <mode> |
Set billboard: fixed, vertical, horizontal, or center (default). |
| Mode |
Behaviour |
center |
Always faces the player (default). |
vertical |
Rotates horizontally only; stays upright. |
horizontal |
Rotates to lie flat on the floor/ceiling. |
fixed |
No automatic rotation; use with /hologram spin for world-space effects. |
Text Alignment#
| Command |
Description |
/hologram textalign <id> <mode> |
Set per-line text alignment: center (default), left, or right. |
Animations#
Spin
| Command |
Description |
/hologram spin <id> on [speed] [axis] |
Enable rotation. speed = degrees/tick, 0.1–30.0 (default 3.0). axis = X, Y, or Z (default Y). |
/hologram spin <id> off |
Stop rotation. |
/hologram spintrack <id> on\|off |
Toggle player-tracking for Y-axis spin (see below). Enabled automatically when /hologram spin <id> on is used with the Y axis. |
Tip: Y-axis spin with fixed billboard = classic record-player spin.
Z-axis spin with center billboard = roll-spin visible to all players.
Player-tracking (Y-axis only, default on): instead of a raw world-space spin, the renderer
switches the billboard to FIXED and computes the yaw as yaw_to_nearest_player + currentSpinAngle,
so the "front" of the text sweeps past every player once per revolution rather than only being
readable from one fixed direction. Disable with /hologram spintrack <id> off to fall back to a
raw Y-axis rotation (only useful if you also set billboard to fixed manually).
Hover / Bob
| Command |
Description |
/hologram hover <id> on [amplitude] [speed] |
Smooth up-and-down bob. amplitude = peak displacement in blocks, 0.01–2.0 (default 0.08). speed = degrees/tick of the sine wave, 0.1–10.0 (default 1.5). |
/hologram hover <id> off |
Stop hover animation. |
Visual Appearance#
| Command |
Description |
/hologram scale <id> <scale> |
Uniform scale (0.1–10.0, default 1.0). Example: 2.0 = double size. |
/hologram linespacing <id> <spacing> |
Vertical gap between lines in blocks (0.05–3.0, default 0.3). |
/hologram shadow <id> on\|off |
Enable/disable the text drop-shadow. |
/hologram seethrough <id> on\|off |
Render the text through solid blocks (like a beacon beam). Default off. |
/hologram opacity <id> <0-255> |
Text opacity (255 = fully opaque, default; 0 = invisible). |
/hologram viewrange <id> <0.1-8.0> |
Display-entity view range multiplier (default 1.0, vanilla base ≈ 64 blocks, so e.g. 2.0 ≈ 128 blocks). |
/hologram linewidth <id> <1-4096> |
Maximum text width in pixels before wrapping (default 200). Set higher to prevent long lines wrapping. |
/hologram background <id> <color> |
Background panel colour. Accepts: transparent (default), #RRGGBB, or #AARRGGBB (where AA is alpha). |
Background examples:
/hologram background lobby transparent ← fully transparent (default)
/hologram background lobby #40000000 ← 25% black semi-transparent panel
/hologram background lobby #000000 ← opaque solid black
Placeholders#
Hologram line text supports the full NeoEssentials placeholder syntax {identifier}.
Common useful placeholders:
| Placeholder |
Value |
{neoessentials_online_players} |
Current online player count |
{neoessentials_max_players} |
Server max players |
{neoessentials_server_name} |
Server name from config |
{neoessentials_server_motd} |
Configured MOTD (/motd if set, otherwise server.properties) |
{neoessentials_time} |
Current server time (12h) |
{neoessentials_time_24} |
Current server time (24h) |
{neoessentials_date} |
Current date |
Set refreshInterval > 0 on the hologram to keep placeholder values up-to-date.
Leaderboard Boards#
Any registered leaderboard board's rank/name/value is also available:
{leaderboard_<board>:<rank>:name} / {leaderboard_<board>:<rank>:value}, e.g.
{leaderboard_money:1:name}. Rather than typing each /hologram addline by hand,
/leaderboard hologram create <board> <id> [lines] generates a full ranked hologram in one
command — see Leaderboard System → Holograms.
Colour Codes#
Use & colour codes in line text:
| Code |
Colour |
&a |
Green |
&b |
Aqua |
&c |
Red |
&e |
Yellow |
&f |
White |
&6 |
Gold |
&l |
Bold |
&o |
Italic |
&r |
Reset |
Hex colour via &#RRGGBB is also supported.
Example Hologram Setup#
# Step 1 — create at eye level above a spawn platform
/hologram create spawn-welcome 0 70 0 minecraft:overworld
# Step 2 — add lines (top to bottom)
/hologram addline spawn-welcome &6&lWelcome to &eMyServer!
/hologram addline spawn-welcome &7Online: &f{neoessentials_online_players}/{neoessentials_max_players}
/hologram addline spawn-welcome &7&oRight-click a sign to explore
# Step 3 — refresh every 10 s so player counts stay current
/hologram setrefresh spawn-welcome 10
# Step 4 — increase size slightly and enable gentle hover
/hologram scale spawn-welcome 1.3
/hologram hover spawn-welcome on 0.1 1.2
# Step 5 — inspect the result
/hologram info spawn-welcome
Fields stored per hologram:
{
"id": "spawn-welcome",
"world": "minecraft:overworld",
"x": 0.0, "y": 70.0, "z": 0.0,
"visible": true,
"refreshInterval": 10,
"interactive": false,
"scale": 1.3,
"lineSpacing": 0.3,
"textShadow": false,
"textOpacity": 255,
"backgroundColorArgb": 0,
"textAlign": 0,
"seeThrough": false,
"lineWidth": 200,
"viewRange": 1.0,
"billboardMode": 3,
"spinEnabled": false,
"spinSpeedDegrees": 3.0,
"spinAxis": "Y",
"spinTrackPlayer": true,
"hoverEnabled": true,
"hoverAmplitude": 0.1,
"hoverSpeedDegrees": 1.2,
"lines": [
{ "text": "&6&lWelcome to &eMyServer!", "frames": [], "animFrameIntervalTicks": 0 },
{ "text": "&7Online: &f{neoessentials_online_players}/{neoessentials_max_players}", "frames": [], "animFrameIntervalTicks": 0 }
]
}
billboardMode values: 0=FIXED, 1=VERTICAL, 2=HORIZONTAL, 3=CENTER.
textAlign values: 0=CENTER, 1=LEFT, 2=RIGHT.
backgroundColorArgb is an ARGB integer. 0 = fully transparent.
textOpacity: 0–255, 255 = fully opaque.
interactive: when true, right/left-clicking the hologram fires click events (used by shop holograms — see below). Regular admin-created holograms leave this false.
Shop Holograms#
When a sign shop enables its hologram (via the shop hologram toggle — see Economy System), NeoEssentials auto-creates an interactive hologram named shop_<dimension>_<x>_<y>_<z> above the sign showing the item, owner, and buy/sell prices. This hologram is refreshed automatically on every transaction and behaves as a second click-target for the shop:
| Interaction |
Effect |
| Right-click (non-owner) |
Buy from the shop (same as right-clicking the sign) — requires neoessentials.shop.use. |
| Left-click / attack (non-owner) |
Sell to the shop — requires neoessentials.shop.use. |
| Right-click (owner) |
Shows shop info instead of transacting. |
| Shift+right-click (owner), holding an item |
(Re)assigns the shop's traded item to the held item, capturing its data (enchantments, custom name, modded NBT) — same gesture as the sign, see Item Data / NBT in the Economy System page. |
Clicks are rate-limited to one processed interaction per player every 400 ms to prevent held-down attack-spam from firing repeated transactions.
Shop holograms can be repositioned relative to their sign (up to ±4.5 blocks per axis) via the shop's hologram-offset controls; admin /hologram commands can still be used to inspect them (/hologram info shop_...), but manual edits to their lines/position are overwritten the next time the shop transacts or reloads.
Web Dashboard API#
The dashboard exposes a REST API for hologram management:
| Method |
Path |
Description |
GET |
/api/holograms/list |
List all holograms |
GET |
/api/holograms/stats |
Summary counts (total, visible, animated, shop) |
GET |
/api/holograms/{id} |
Get a single hologram |
POST |
/api/holograms/create |
Create (body = hologram JSON) |
PUT |
/api/holograms/{id} |
Update (full hologram JSON body) |
DELETE |
/api/holograms/{id} |
Delete |
POST |
/api/holograms/{id}/spawn |
Force a re-spawn |
POST |
/api/holograms/{id}/despawn |
Despawn without deleting |
POST |
/api/holograms/{id}/visible |
Toggle visibility |
All responses include billboard, spin, hover, scale, lineSpacing, textShadow, textOpacity, and backgroundColorArgb fields.
