✨ Holograms Module

The Holograms module is an embedded port of the FancyHolograms library, fully integrated into OreoEssentials. It uses Minecraft's native Display entities (text, item, block) introduced in 1.19.4, meaning holograms are real server-side entities — no client-side packet tricks required.

Quick Start

config.yml — Full Reference

Located at plugins/OreoEssentials/OHolograms/config.yml.

# ──────────────────────────────────────────────────────────
#  OHolograms Configuration (embedded in OreoEssentials)
#  File: plugins/OreoEssentials/OHolograms/config.yml
# ──────────────────────────────────────────────────────────

# Config version — DO NOT change this
config_version: 1

# ── Saving ───────────────────────────────────────────────
saving:
  autosave:
    # Whether to periodically save all holograms to disk automatically
    enabled: true
    # How often to autosave, in MINUTES (default: every 15 minutes)
    interval: 15

  # If true, holograms are also saved immediately every time they are edited.
  # Recommended: keep this true to avoid losing changes on crash.
  save_on_changed: true

# ── Logging ──────────────────────────────────────────────
logging:
  # Log verbosity: DEBUG, INFO, WARN, ERROR
  log_level: INFO

  # Log a message every time a world is loaded and its holograms spawn.
  # Disable if you dynamically load/unload worlds frequently.
  log_on_world_load: true

  # Show a console message when a newer plugin version is available
  version_notifications: true

# ── Visibility ───────────────────────────────────────────
# Default distance (in blocks) at which a hologram becomes visible.
# Players farther away than this will not see it.
# Can be overridden per hologram with /hologram edit <holo> visibilityDistance
visibility_distance: 20

# How often (in TICKS) to check and update which players can see each hologram.
# Lower = more responsive but slightly more CPU. Default 20 ticks = 1 second.
update_visibility_interval: 20

# ── Commands ─────────────────────────────────────────────
# Set to false to disable /hologram and /oholograms entirely
# (useful if using the API only)
register_commands: true

Performance Tips

Hologram Types

There are three hologram types. Choose the type when creating with /hologram create <type> <name>.

/hologram — Complete Command Reference

Also accessible as /holograms, /holo, /fholo, and /ohologram. All subcommands require the base permission oholograms.admin — subcommand permissions are additional fine-grained checks.

Informational Commands

Creating & Removing

Position & Transform

Visibility Controls

Text-Only Commands

These commands only work on text type holograms.

Item-Only Commands

Block-Only Commands

NPC Integration (requires FancyNPCs)

/oholograms — Management Commands

These commands manage the plugin itself rather than individual holograms.

Base permission: oholograms.admin

Permissions — Complete List

Parent Permission

Hologram Management

Edit Permissions

Viewer Permission

LuckPerms Setup Example

# Give all admins full hologram control
/lp group admin permission set oholograms.admin true

# Give a specific group permission to see a VIP-only hologram
/lp group vip permission set OHolograms.viewhologram.vip_rewards true

# Give all players permission to see a specific hologram
/lp group default permission set OHolograms.viewhologram.spawn_info true

Storage — How Holograms Are Saved

All holograms are stored in a single YAML file: plugins/OreoEssentials/OHolograms/holograms.yml. You can edit this file manually, but always run /oholograms reload after doing so.

File Format

version: 2  # DO NOT CHANGE

holograms:
  my_hologram:                      # Hologram name (lowercase)
    type: TEXT                       # TEXT / ITEM / BLOCK
    location:
      world: world
      x: 100.5
      y: 64.0
      z: 200.5
      yaw: 0.0
      pitch: 0.0
    visibility: ALL                 # ALL / PERMISSION_REQUIRED / MANUAL
    visibility_distance: -1          # -1 = use config default
    persistent: true
    text:                            # List of text lines (TEXT type only)
      - "<gold><b>Welcome!</b></gold>"
      - "<gray>Enjoy your stay!</gray>"
    text_shadow: false
    see_through: false
    text_alignment: center
    update_text_interval: -1          # -1 = no auto-refresh
    background: null                  # null = default, "transparent", "#RRGGBB", named color
    scale_x: 1.0
    scale_y: 1.0
    scale_z: 1.0
    shadow_radius: 0.0
    shadow_strength: 1.0
    billboard: null                   # null = CENTER, or fixed/vertical/horizontal

When Are Holograms Saved?

Visibility System

Each hologram has a visibility mode that controls who can see it, and a visibility distance that controls how far away it is visible.

Visibility Modes

Visibility Distance

The visibility distance determines how close a player must be to see the hologram. The server checks this every update_visibility_interval ticks (default: every second).

• Global default: set in config.yml as visibility_distance (default: 20 blocks)
• Per-hologram override: /hologram edit <name> visibilityDistance <blocks>
• Use -1 to reset a hologram back to the global default

Text Formatting

Text holograms support two formatting systems simultaneously.

MiniMessage (Recommended)

The modern Minecraft text format using XML-like tags. Examples:

# Bold gold title
/hologram edit myHolo setLine 1 <gold><b>Welcome to the Server!</b></gold>

# Gradient text
/hologram edit myHolo addLine <gradient:red:blue>Colorful Line</gradient>

# Rainbow text
/hologram edit myHolo addLine <rainbow>Rainbow Text!</rainbow>

# Hover tooltip (for players who see the hologram)
/hologram edit myHolo addLine <hover:show_text:'secret!'>Hover me!</hover>

# Clickable link
/hologram edit myHolo addLine <click:open_url:'https://example.com'>Visit us!</click>

Legacy Color Codes

The old &-style codes still work too:

/hologram edit myHolo setLine 1 &6&lGold Bold Title
/hologram edit myHolo addLine &aGreen text &r normal text

Empty Lines / Spacing

To add a blank line between text lines, use a single space as the text:

/hologram edit myHolo addLine  

FancyNPCs Integration

If you have the FancyNPCs plugin installed, holograms can be linked to NPCs. The hologram will float above the NPC, follow its position, and scale with the NPC's scale setting.

How to Link

Player Examples

Example 1 — Spawn Welcome Sign

Example 2 — Shop Price Display

Example 3 — VIP-Only Hologram

Example 4 — Floating Block Decoration

Example 5 — Move a Hologram Precisely

Example 6 — Import from DecentHolograms

FAQ