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
- Player gets a Hologram Book via
/mh getbook - Player writes content in the book (with optional color codes)
- Player places the book on an empty lectern (signing it first is optional)
- A hologram appears above the lectern with the book's content
- Breaking the lectern (or taking the book out) removes the hologram
Step-by-Step Guide
Getting a Hologram Book
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:
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
- Check
masuholograms.lectern.bypass→ unlimited - Scan
masuholograms.lectern.limit.NfrommaxLimitdown to 1 → first match = limit - Fall back to
defaultLimitfrom 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&uanimation 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 resolveDISABLE_ANIMATIONS- animation tags are ignored
Color Code Control
Color codes can be globally enabled or disabled for lectern holograms:
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.usepermission 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 deleteto remove it
Colors don't work
- Check that
allowColorCodesistruein config - Use the
&prefix (e.g.,&6Gold), not§ - Only the codes listed under Book Text Rules are kept