Scuffed Holograms

Install, staff-command, permission, editor and integration reference for server operators. For what players see and can click (text, images, leaderboards, triggers) see the Scuffed Holograms gameplay guide.

• Plugin version: 1.9.9 (plugin name ScuffedHolograms)

Holograms are drawn with packets and virtual entities rather than saved world objects. The plugin adds three kinds of real world objects when needed: invisible click-zone NPCs for holograms with click actions (removed on shutdown and swept every 30 seconds), carrier entities for particle-effect holograms, and light blocks for ambient light. Everything is created and edited in a built-in GUI. There is no global config file; each hologram carries its own settings.

Requirements

The plugin has no hard dependencies. PlaceholderAPI, TaleQuests and RPGLeveling are detected at runtime by class presence and are not listed in the manifest. The Endless Quests API shipped with Endless Leveling is used the same way.

Install notes

• Drop the jar in mods/. On first boot it creates mods/ScuffedHolograms/ and, next to it, the generated asset pack mods/ScuffedHologramsData/ (font glyph sheets and the world-map marker icons).
• To enable that pack the plugin writes Mods → Zbeve:ScuffedHologramsData → Enabled: true into the server config.json, unless DefaultModsEnabled is already true. It then tries to register the pack live. If that fails it logs a one-time notice and the map markers become active after the next planned restart. The plugin itself keeps loading either way.
• Do not start the server with --disable-file-watcher. Image holograms depend on the file watcher to reach clients, and /sch menu prints a red warning when the flag is present.
• A copy that was not obtained through its distributor refuses to start and logs an [SH-License] line.
• Each hologram stores the name of the world it was placed in and is shown only to players in that world.

Admin & Staff Commands

The base command is /scuffedholograms, alias /sch. Every subcommand is gated by the admin check described under Permissions. tptoholo, sendchat and cleanimages can also be run from the console.

There are no commands for reloading or resetting caps. Use the GUI Reload button and the cap-reset modes below.

Permissions

Holograms do not use one permission node per command. Instead one function decides whether someone is a hologram admin. It is used by every /sch subcommand, the Hologram Tool and the GUI. The console always passes. A player passes if any of these is true:

Any failure inside the check denies access.

Hologram actions can run commands as the console, so anyone who passes this check can build a hologram that runs any console command. Grant scuffedholograms.admin accordingly.

Player-side nodes (LuckPerms)

These need LuckPerms. They only change how triggers behave for a player or group.

Per-hologram access lists use any permission string you choose (see Triggers and permissions). They resolve through the server permission module, which routes through LuckPerms when it is installed.

Hologram Tool

Item id SH_HologramTool. It is a Legendary-quality item with an on-screen legend. Using it needs the admin check.

Rotating a Center or Horizontal hologram, or pitching a Center one, switches it to Fixed first (not for particle-effect holograms). Walk-in triggers are paused while a hologram is held. Scale up and down actions exist in code but are not bound to the tool.

The management GUI

/sch menu opens three tabs.

Holograms tab

• Lists all holograms eight to a page, sorted by name, with a search box and a Near Me filter (same world, within 32 blocks).
• Create buttons: New Text, New Image, New Model, New Particle and Leaderboard. A new hologram is placed at your position, about 2.5 blocks up (2 for particles), in your current world. Names are cleaned to letters, digits, _ and -; a clash gets a _1, _2 suffix.
• Per row: Edit, Copy (creates <name>_copy), Del (asks "Sure?" first) and a checkbox.
• Folders group holograms: New Folder, then tick holograms and use Move to Folder or Move Out. Folders do not nest.
• The Leaderboard button cycles through four built-in templates, one per click: leaderboard (Endless Leveling rank), leaderboard_kills, leaderboard_playtime, leaderboard_joins. Each creates a ten-line ranking hologram.

A new text hologram starts with three sample lines (gold title, two-colour line, gradient line) in the default font.

Combat Text tab

Replaces vanilla floating damage numbers server-wide. See Combat text below.

Settings tab

• Debug logging toggle. Not saved; it resets on restart.
• Give me one (the Hologram Tool) and Reload. Reload saves pending edits, re-reads all hologram files and delivers new image files in memory.
• Language dropdown, Import All (see Importing) and an About card.

Editing a hologram

Opening a hologram shows a Settings tab (display, effects, schedule, map marker and light) and a Triggers + Perms tab that opens a wider separate page. BACK saves and returns to the list. SAVE & CLOSE saves, refreshes particle assets and closes.

Content type

A hologram is one of these. Switching the content type replaces the lines.

Settings tab fields

Lines

Each line has its own editor: type, text, font, colours, animation, variants, offsets and (for images and models) scale. Lines can be reordered, duplicated and deleted. The line limit is 15 per hologram.

Per-line X offset and Z offset shift a line sideways without moving the hologram.

Colour and formatting syntax

&k, &l, &m, &n and &o are dropped without output: bold, italic and underline are not supported. The same syntax works in /sch sendchat.

The line editor works on plain text. Colour is applied through up to 8 segments per line: each segment is a character range with a Solid, Gradient or Rainbow colour. Line animations and segments cannot be combined; turning on an animation is refused while segments exist.

Animations and variants

Animated lines strip colour markup and force the Entity renderer.

Fonts

Built-in fonts are scuffed (default), minecraftunicode and press_start_2p. Drop a .ttf or .otf into mods/ScuffedHolograms/fonts/ and restart to add more; the file name, lowercased and cleaned, becomes the font name. The font sheet of a font that no hologram uses is removed at an empty-server boot (see Performance), and a font chosen later shows as the default font until the next such boot.

Placeholders

{name} or {name:argument} in text lines, variants and action commands. Names are case-insensitive. An unknown placeholder is left as typed.

The {el_*} placeholders exist only when EndlessLeveling is installed, and {rpg_*} only with RPGLeveling.

{top} returns --- for an empty rank (or 0 with :value, :prestige or :level), and ??? for malformed arguments.

PlaceholderAPI tokens use percent syntax, for example %player_name%. SH resolves its own {...} first, then runs the result through PlaceholderAPI. PAPI tokens always make the line per-viewer and also work inside action commands. Braces always belong to SH and percent signs to PAPI. See the PlaceholderAPI guide for the expansions the Endless mods provide.

Refresh timing

The renderer runs on a 200 ms tick. Update Int is counted in those ticks, not in server ticks, so the default of 600 refreshes about every 120 seconds, the minimum of 20 is 4 seconds and the maximum of 6000 is 20 minutes. On builds up to 1.9.9 the editor hint reads "20 ticks = 1s", which does not match this; later builds show the real timing. The interval governs placeholders and EL_PLACEMENT models; variants and animations update on their own cadence.

Leaderboards

Stats live in mods/ScuffedHolograms/leaderboards/<stat>.json as UUID → number maps, with display names cached in _names.json. Flushed every 60 seconds and on shutdown.

On a network where Endless Leveling shares a database, SH reads EL's own network leaderboard so every server shows the same ranking, including offline players. If EL has no such view, SH ranks only players seen on this server.

Models can show a ranked player: set a model line to EL_PLACEMENT:<n> (1 to 1000) and it renders whoever holds that place in el_rank, re-checked at the hologram's Update Int. The GUI offers a picker with the current top players. The player's look is cached in player_appearances.json when they log in and refreshed every 30 seconds while online, so someone who has never joined stays invisible until they do. Appearances are shared between servers when Endless Leveling's shared storage backend is active.

Images and GIFs

• Supported files: PNG, JPEG, BMP and GIF (up to 100 GIF frames). Use the image panel or line editor to Load from URL, or drop files into mods/ScuffedHolograms/images/ and click Refresh.
• URL loading: HTTP(S), up to 5 redirects, 8 second connect and 15 second read timeouts, 50 MiB maximum. The image is staged first; click Refresh to deliver it to clients. The name comes from the URL file name, cleaned to a-zA-Z0-9._-.
• Images can be renamed from the editor; every hologram that uses the image is updated.
• Sharp edges gives an image a hard-alpha texture. Turn it on if a soft-edged image pulses ("heartbeat"); edges look slightly rougher.
• Render mode per image: Particle (default, sharper, uses particle slots) or Entity (model based, no flicker, supports glow, tint and VFX).
• Images are scaled to a resolution cap before delivery: 1024 px on the long edge, dropping to 512 px once the library holds more than 11 images. The cap does not return to 1024 until the library shrinks to 8 images or fewer. The cap is stored in imagecap.txt. Hologram world size is not affected by the cap.
• The client has a hard texture budget. Too many large images can crash clients, which is why the library is capped and unused images are cleaned.
• Boot cleanup: on a boot with no players online, images that no saved hologram uses are deleted, source file included. It is skipped if no hologram is loaded, if no hologram uses any image, or while players are online. Images registered by other mods through the API are kept (see API).
• /sch cleanimages does the same cleanup on demand from the console. On builds up to 1.9.9 it also deletes images that other mods registered through the API (they return when the owner mod registers them again); later builds keep them, the same as the boot cleanup.

Models

A model line takes any model asset id (browse and search in the GUI, or type an id). Presets: Mannequin and My Model.

• My Model copies your current look, including a custom player skin and cosmetic attachments, as a snapshot stored in the hologram. It keeps working when you are offline.
• Gear: Held Item copies the item in your hand onto the model; My Armor copies your worn armour; Clear removes both.
• EL_PLACEMENT:n shows a leaderboard placement (above).
• Model scale is 0.01 to 30. Glow, tint and VFX apply only to model and image lines.

Effects

Triggers and permissions

Opened with Triggers + Perms. A hologram has one action list and one trigger mode.

Trigger mode

The interact prompt shows for creative-mode players only if "visible to NPCs" is enabled for them.

Actions

Each action is a command (leading / optional) with:

Placeholders ({player}, {uuid}, {x}, {y}, {z}, {online}, {time}, {date}, {world}, EL, PAPI) are resolved before the command runs. Template buttons fill the input with notify {player} …, sch sendchat {player} …, tp {player} 0 100 0, give {player} item_id, a UUID message, a teleport-to-hologram picker that writes sch tptoholo {player} <key>, and a quest picker.

Action mode

QUEST_CHAIN chain end: STOP (default, nothing), LOOP (first action again) or LAST (last action forever). Quest ids are routed to TaleQuests or the Endless Quests API. If a quest id is blank and the command is quest npc <player> <id>, the id is taken from the command.

Limits

Counts persist in triggercounts.json (also holds CHECKLIST positions), flushed every 60 seconds and on shutdown. Cooldowns are memory-only and persist across a player's reconnects but not a restart. There is no command to reset a player's count: stop the server and edit or delete the file, or change the reset mode. Deleting a hologram clears its counts. Interact triggers tell the player about cooldowns and caps; walk-in triggers stay silent about cooldowns.

Access control

Denied clicks on a hologram with an active list are silent so a click cannot reveal hidden holograms. A permission-module error denies a trigger but leaves a hologram visible.

Per-permission overrides

A list ordered by priority; the first entry whose permission the player holds applies. Each entry is independent:

When no override matches, the LuckPerms meta keys above apply.

Combat text

Off by default. The Combat Text tab has an enable toggle, three presets, font size (20 to 200), duration (0.2 to 3.0 seconds) and a colour picker. Click Save to apply; no restart is needed. Turning it off removes the override and restores vanilla numbers. Reset applies the Vanilla preset and keeps the feature on.

Settings are stored in combattext_settings.json; the generated asset is combattext_runtime/CombatText.json.

Importing

If either source is found the Settings tab shows how many holograms it detected and an Import button:

Imported holograms get the key imported_<name> and their images are copied with the same prefix. Colour codes are converted to the SH syntax and text uses the default font. Everything stays editable. Images are delivered in memory, so importing is safe with players online.

Language

The Settings tab has a language dropdown with 24 languages: en, de, fr, es, it, pt, nl, pl, ru, uk, cs, sk, hu, ro, lt, sv, da, tr, id, vi, zh, ja, ko, th. It translates the GUI labels; missing keys fall back to English. Files are in mods/ScuffedHolograms/lang/<code>.json; bundled translations are copied there only if missing, so your edits survive updates. The chosen language is stored in lang/active.txt.

Data & storage

Everything is under mods/ScuffedHolograms/ unless noted.

Transient API holograms are never written to disk. Any file marked transient is deleted at boot.

Server options

These are JVM system properties, set on the server start line with -D.

Performance notes

• Static text without placeholders or animation is baked once and sent as particles shared by all viewers. A text line with a placeholder, a per-viewer value, a PAPI token, an animation, or the Entity renderer uses entities that update in place. Images and models always have their own render path.
• Particle rendering is sharper at distance but uses client particle slots. Entity rendering is lighter on the server and the network. Prefer Entity for busy spawn areas with many holograms, or if clients hit the particle limit.
• Per-viewer placeholders are resolved for each nearby viewer. Raise Update Int and lower View Dist on crowded holograms.
• Collision holograms are checked every 50 ms for nearby players. Use them sparingly.
• Deleting image or font assets while players are connected forces every client to rebuild its asset atlases, which can black out a client. That is why the cleanups only run at boot with nobody online. New images added through the editor, Refresh or the API are delivered in memory without a rebuild. Custom fonts are generated at startup.
• Click-zone NPCs, particle carriers and light blocks are real world objects. Leave click actions and lights off holograms that do not need them.

Integrations

API for other mods

com.zbeve.scuffedholograms.api.ScuffedHologramsApi (API_VERSION 2) lets another mod ship PNG images in its own jar and display them as image holograms that exist only in memory. Every method is public static, uses JDK types only, is safe from any thread, never throws and returns false on failure (logged under [SH-API]).

Rules:

• Image names are lowercase, 1 to 64 characters from a-z 0-9 _ -, must not end in _sharp, _atlas or _frameN, and must not clash with another owner's image or a different user image. Prefix them with your mod id. Static images only, up to 16 MiB. The same resolution cap as uploads applies.
• Registered images are exempt from the boot cleanup while their owner registered them this boot or the last.
• Transient holograms are never saved, survive /sch reloads, are removed with their world, and cannot take the key of a saved hologram. A copy made in the GUI is a normal saved hologram.
• yawDegrees finite gives a Fixed hologram at that yaw; NaN gives a Center hologram. scale ≤ 0 means 1 and is capped at 100. viewDistance ≤ 0 means 80 and is capped at 1024. Keys are 1 to 128 characters.

To call it without a compile dependency, add "Zbeve:ScuffedHolograms": ">=1.9.1" to OptionalDependencies in your manifest so SH loads first, and bind the methods with MethodHandle after checking API_VERSION == 2. Register your images in setup, retry prepareTransientImage until it returns true, then call showTransientImage only once isTransientImageReady is true.

Troubleshooting