OverHeadMessage

OverHeadMessage is a lightweight Leaf/Paper plugin that mirrors a player's chat message right above their head using a modern TextDisplay entity — complete with smooth animations, hex/group colors, and a built-in AFK system.

When a player types in chat, their message smoothly appears over their head, rides along with them as they walk, gently bobs while it lingers, then flies up and fades away. No ArmorStands, no NMS hacks, no lag.

What it does

• Overhead chat — every chat message floats above the sender as a TextDisplay, attached as a passenger so it follows the player perfectly.
• Clean animations — a smooth scale-up on appear, gentle flicker-free idle bobbing, and a fly-up + shrink on disappear. Sending a new message instantly plays the old one's exit before showing the new one.
• Rich colors — supports both & legacy codes and inline #RRGGBB hex. Starting a message with ! switches it to a separate color (and the ! itself is hidden).
• Per-group colors — with LuckPerms installed, give each rank its own message colors through a simple priority list and overrides.
• AFK system — after a configurable idle time, a random phrase plus a live timer (30s → 1m → 1h 2m) appears over the head. Any movement, interaction, or chat clears it instantly.
• PlaceholderAPI support — expose an AFK tag anywhere you want (tab list, scoreboard, nametag plugin, and more).
• Featherweight — profiled at roughly 0.1% of a single server thread. No heavy loops, no entity leaks, everything cleaned up on quit, death, and shutdown.
• Version-tolerant — optional visual features are guarded, so the plugin degrades gracefully instead of crashing on different builds.

Colors and groups

Set a default color and a separate with_exclamation color (used when a message begins with !). If LuckPerms is present, group_priority decides which rank wins, and group_overrides lets each group define its own colors. Players outside those groups simply use the defaults.

AFK and PlaceholderAPI

When PlaceholderAPI is installed, OverHeadMessage registers these placeholders:

• %ohm_afk% — the colorized AFK tag while the player is AFK, empty otherwise
• %ohm_afk_time% — adaptive AFK time such as 1h 2m
• %ohm_afk_state% — true or false

The plugin never edits the tab list on its own — just place %ohm_afk% wherever you like.

Commands and permissions

• /ohm reload — reload the configuration
• /ohm status — show the current settings
• Permission: overheadmessage.admin (default: op)

Compatibility

Built for Leaf/Paper 1.21.x on Java 21, using the stable Bukkit/Paper API. LuckPerms and PlaceholderAPI are optional soft-dependencies — the plugin runs fine without them and prints a clear console notice (with download links) if they are missing.

Installation

1. Drop the jar into your plugins/ folder.
2. (Optional) Install LuckPerms for per-group colors.
3. (Optional) Install PlaceholderAPI for the AFK placeholders.
4. Restart, edit config.yml, and run /ohm reload.

Made by ZiTr_.