RotatingHeadsPlus
Animate player heads, armor stands, and living entities with smooth rotations, body-part poses, floating holograms, particle effects, dynamic equipment, and rich click actions — all from simple YAML files.
Animate player heads, armor stands, and living entities with smooth rotations, body-part poses, floating holograms, particle effects, dynamic equipment, and rich click actions — all from simple YAML files.
Overview
RotatingHeadsPlus is a decoration and animation plugin built from scratch for the Spigot API. It was inspired by the original RotatingHeads 2 concept but is an entirely independent implementation — written from zero, with no shared code, no decompilation, and no license violations.
Compatibility
- Minecraft: 1.16 – 1.21.11 / 26.1.x
- Server software: Built for Spigot. Fully compatible with Paper, Purpur, and any Spigot-based fork.
- Java: 21+
- Architecture: Pure Bukkit/Spigot API — no NMS, no reflection. Works across all supported versions without version-specific adapters.
Features
Animation Types
- Circular — continuous rotation at configurable speed
- Ping-Pong — oscillates between two angles
- Static — locks at a fixed angle
- Stalking — follows the nearest player (per-player with ProtocolLib)
- Up-Down — smooth sinusoidal floating motion
- Composite — combine any of the above simultaneously (e.g. rotate + float)
Body-Part Animation (ArmorStands)
- Animate head, body, arms, and legs independently
- Per-part mode: static, ping-pong, or circular per body part
- Keyframe mode: define full-body poses at tick indices with interpolation (linear, smooth, step)
- Combine body-part animation with whole-body rotation in a single file
Dynamic Equipment (ArmorStands)
- Static equipment: set helmet, chestplate, leggings, boots, mainhand, offhand
- Animated equipment: cycle through gear changes by frame
- Supports custom model data, enchant glow, player skulls by name or Base64 texture
Holograms
- Floating text above any animated object
- Auto-detects DecentHolograms > FancyHolograms > Native (ArmorStand fallback)
- Supports PlaceholderAPI per-viewer and {lang:key} tokens
- Follows UpDown animation when configured
Particle Effects
- 4 patterns: circle, spiral, wave, aura
- Any Bukkit particle type, with color support for REDSTONE/DUST
- Automatically tracks entity position for UpDown
Click Actions
- 10 action types: message, title, command, console_cmd, broadcast, sound, actionbar, teleport, potion, connect (BungeeCord)
- Per-player cooldowns, permission conditions (including negation), world conditions
- Full PlaceholderAPI support in all values
- Triggers: LEFT, RIGHT, BOTH
Conditions
- World, min/max distance, time range (supports midnight crossing)
- Applied per-object — animations only run when conditions are met
Performance
- Distance culling — objects with no nearby players are skipped
- Chunk culling — objects in unloaded chunks are skipped
- Async data saving — state snapshot on main thread, file I/O off-thread
- Configurable object limit
- Tick profiling visible in /rhead debug
Commands
YAML:
/rhead create — animate the object you are looking at
/rhead remove — remove the nearest animated object
/rhead stop — stop animation of the nearest object
/rhead list — count active animated objects
/rhead info [uuid] — show details about an object
/rhead near [radius] — list animated objects within a radius
/rhead tp <uuid> — teleport to an animated object
/rhead copy — copy nearest object config to clipboard
/rhead paste — paste clipboard config onto a target
/rhead export [name] — export to exports/ folder
/rhead import <name> — import from exports/ folder
/rhead relink <uuid> — reassign a data file to a replacement entity
/rhead debug — print plugin diagnostics
/rhead reload — reload config and all data files
/rhead help — show command referencePermissions
YAML:
rotatingheadsplus.use (default: true) — create, remove, list, info, near, help
rotatingheadsplus.admin (default: op) — stop, reload, tp, copy, paste, export, import, relink, debugOptional Dependencies
- ProtocolLib — packet-based rotation (smoother, per-player stalking, no teleport jitter)
- DecentHolograms — high-performance holograms with per-player PAPI
- FancyHolograms — alternative hologram provider
- PlaceholderAPI — exposes %rotatingheadsplus_count% and %rotatingheadsplus_enabled%
None of these are required. The plugin works fully standalone.
Languages
Bundled: English, Spanish, Portuguese (BR), French, German, Chinese (Simplified).
Automatic fallback to English for missing keys. Community translations welcome — see lang/TRANSLATING.md.
Developer API
Full Java API for other plugins: register/remove objects, swap animations, listen to custom Bukkit events (AnimationStartEvent, AnimationChangeEvent, AnimationRemoveEvent, RotatableClickEvent), manage holograms, particles, and equipment programmatically. See the README on GitHub for full documentation.
Configuration
Everything is YAML-driven. Create objects with /rhead create or write data files by hand. All animation types, conditions, click actions, holograms, particles, and equipment are configured per-object in plugins/RotatingHeadsPlus/data/*.yml.
About
This plugin was inspired by the RotatingHeads 2 concept. It is not a fork, copy, or derivative — it was written entirely from scratch using only the public Spigot API. No code was taken from any other plugin. No licenses were violated.
Support
Found a bug or have a suggestion? Open an issue on GitHub or leave a message in the discussion tab.
Discord: https://discord.gg/FhTkwjMxzv
