Skip to content

Lectern Holograms

Lectern holograms allow regular players to create their own holograms using Hologram Books placed in lecterns. This feature gives players a safe, limited way to customize their builds with floating text.

How It Works

  1. Player gets a Hologram Book via /mh getbook
  2. Player writes content in the book (with optional color codes)
  3. Player places the book on an empty lectern (signing it first is optional)
  4. A hologram appears above the lectern with the book's content
  5. Breaking the lectern (or taking the book out) removes the hologram

Step-by-Step Guide

Getting a Hologram Book

/mh getbook

This gives you a writable book with a special internal tag (MasuHologramBook). Only books obtained this way work with lecterns; regular books are ignored.

Permission: masuholograms.lectern.getbook (default: all players)

Writing Your Hologram

Open the book and write your hologram content:

  • Each line in the book becomes a hologram line. A new line only starts when you press Enter; text that wraps on its own still counts as one line.
  • Up to 6 lines per page (config maxLinesPerPage); lines after that are left out.
  • Color codes with & are supported if enabled in config (default: yes). See Book Text Rules.
  • Multiple book pages create a multi-page hologram (empty pages are skipped, at most 100 pages).

Example book content:

Page 1:
&6Steve's House
&7Welcome!
&eFeel free to look around

Page 2:
&6Rules
&71. No stealing
&72. Close the door

Signing the Book

Signing is optional: signed and unsigned Hologram Books both work. The Hologram Book tag is kept through signing. To change a signed book later, hold it and run /mh editbook, which turns it back into an editable book with the same pages.

Permission: masuholograms.lectern.editbook (default: all players)

Placing the Hologram

Right-click an empty lectern with the Hologram Book. The hologram appears above the lectern and the chat tells you how many of your holograms are in use, for example Hologram created above the lectern! (2/3).

Removing the Hologram

Break the lectern block; the hologram is removed at once.

Warning

A hologram is also removed when its lectern is destroyed in another way (explosion, piston, /setblock) or its book is taken out. These are found by a periodic check (every 5 seconds by default, config validationIntervalTicks), which only looks at lecterns in loaded chunks.

Multi-Page Lectern Holograms

If your book has multiple pages, the hologram automatically gets:

  • Right-click → Next page (except on the last page)
  • Left-click → Previous page (except on the first page)
  • A page indicator and a navigation hint under the book's lines

Each viewer can be on a different page. The indicator and hint texts come from lang.json.

Player Limits

Each player has a maximum number of lectern holograms they can have at once in a world.

Setting Default
Default limit (no limit permission) 3 (config defaultLimit)
Highest limit permission checked 20 (config maxLimit)

Without a permissions mod, operators have the bypass node and so no limit; see Permissions. Holograms brought in by the pre-1.3.0 import (or tracked again after a damaged tracker file) do not count towards the limit until the next lectern check has found their lectern.

Checking Your Limit

When you place a hologram, the chat message tells you your current count and limit:

Hologram created above the lectern! (2/3)

At the limit, placing another book is refused with You've reached your hologram limit! (3/3).

Adjusting Limits with LuckPerms

# Set a player's limit to 10
/lp user Steve permission set masuholograms.lectern.limit.10 true

# Give a group unlimited holograms
/lp group builder permission set masuholograms.lectern.bypass true

# Deny hologram creation entirely
/lp user Griefer permission set masuholograms.lectern.use false

Limit Resolution Order

  1. Check masuholograms.lectern.bypass → unlimited
  2. Scan masuholograms.lectern.limit.N from maxLimit down to 1 → first match = limit
  3. Fall back to defaultLimit from config

Security

Lectern holograms have several security measures to prevent abuse.

Book Text Rules

Book text is an allow-list: every line becomes plain text, and only these codes are kept (when allowColorCodes is true):

  • Colors and formats: &0-&9, &a-&f, &k-&o, &r
  • Hex colors: &#RRGGBB
  • Gradients and rainbow: <GRADIENT:RRGGBB>...</GRADIENT:RRGGBB>, <RAINBOW>...</RAINBOW>

Everything else that could do more than show text is removed:

  • Placeholders and anything else in braces: {player}, {#ANIM:...}
  • Other <...> tags and the &u animation code
  • Section signs (§) and control characters
  • A line that starts with # is kept as text and never becomes another line type (#ICON:, #PLAYER: and the like show literally)
  • Lines longer than 256 characters are cut off

Custom replacements such as [x] and [p] from config.json still work.

Forced Flags

Lectern holograms get these flags when they are created (both on by default, see the configuration below):

  • DISABLE_PLACEHOLDERS - even if syntax somehow gets through, it won't resolve
  • DISABLE_ANIMATIONS - animation tags are ignored

Color Code Control

Color codes can be globally enabled or disabled for lectern holograms:

{
  "lecternHolograms": {
    "allowColorCodes": true
  }
}

Set to false to strip all color and formatting (legacy codes, hex, gradients and rainbow) from player holograms.

Configuration

All lectern hologram settings are in config.json under the lecternHolograms section:

{
  "lecternHolograms": {
    "enabled": true,
    "maxLinesPerPage": 6,
    "defaultLimit": 3,
    "maxLimit": 20,
    "heightOffset": 0.0,
    "displayRange": 48,
    "allowColorCodes": true,
    "disablePlaceholders": true,
    "disableAnimations": true,
    "validationIntervalTicks": 100
  }
}
Field Default Description
enabled true Enable/disable the feature entirely
maxLinesPerPage 6 Maximum lines per book page
defaultLimit 3 Default hologram limit per player
maxLimit 20 Highest masuholograms.lectern.limit.N permission that is checked
heightOffset 0.0 Vertical offset above the lectern
displayRange 48 Visibility range in blocks
allowColorCodes true Keep color codes in book text
disablePlaceholders true Give new lectern holograms DISABLE_PLACEHOLDERS
disableAnimations true Give new lectern holograms DISABLE_ANIMATIONS
validationIntervalTicks 100 How often to check that lecterns still hold their book (ticks)

Settings that shape the hologram (lines per page, offset, range, flags) apply to holograms placed after a change.

Storage

Lectern holograms belong to the world they were placed in and are stored in the world folder, separately from admin holograms (which stay global in config/masuholograms/holograms/):

<world>/masuholograms/players/<owner uuid>/<hologramName>.json
<world>/masuholograms/lectern-tracker.json

The hologram name follows the pattern lectern_<player>_<x>_<y>_<z>, with _<dimension> added outside the overworld (for example lectern_Steve_10_64_-5_the_nether). The lectern_ prefix is reserved: admins cannot create or rename holograms to such names. The tracker maps lectern positions to hologram names for the periodic check.

Each save keeps a .bak of the previous file. Lectern holograms from before 1.3.0 (stored under config/masuholograms/holograms/players/) are imported into each world once; see Storage & Backups.

Admins can list a world's lectern holograms with /mh plist and remove one with /mh hologram delete <name>.

Permissions Summary

Permission Default Description
masuholograms.lectern.use true Place hologram books in lecterns
masuholograms.lectern.getbook true Use /mh getbook
masuholograms.lectern.editbook true Use /mh editbook
masuholograms.lectern.guide true Use /mh guide
masuholograms.lectern.limit.N false Set hologram limit to N
masuholograms.lectern.bypass false Unlimited holograms

Troubleshooting

"You've reached your hologram limit!"

Your current hologram count in this world has reached your limit. Remove existing holograms by breaking their lecterns, or ask an admin to increase your limit.

Hologram doesn't appear

  • Make sure you used a Hologram Book from /mh getbook, not a regular book
  • The lectern must be empty when you place the book
  • The book needs at least one page with text ("The book has no content to display")
  • "This lectern cannot show a hologram" means an admin hologram already uses the name this lectern's hologram would get
  • Verify you have the masuholograms.lectern.use permission and that lectern holograms are enabled

Hologram disappeared

  • The lectern may have been destroyed (explosion, piston, manual break) or its book taken out
  • An admin may have used /mh hologram delete to remove it

Colors don't work

  • Check that allowColorCodes is true in config
  • Use the & prefix (e.g., &6Gold), not §
  • Only the codes listed under Book Text Rules are kept