⏱ Animated Timer (Plugin)

An animated, extensively configurable in-game timer for Paper servers.

This is a plugin port of the popular Animated Timer datapack by Tapir0. Everything the datapack does, now as a lightweight Paper plugin with a single /timer command, tab completion, permissions and an API for other plugins.

Perfect for speedruns, challenges, events and "how long have we been playing" servers.

---

✨ Features

• Timer in the actionbar that counts up or down, tick-accurate
• 29 color-gradient animations (blue-pink, rainbow, gold-fade, …) with adjustable speed and direction
• Static style with two freely chosen colors (named colors or #hex), bold and italic
• 5 render types: 01:05:09, 1h 5m 9s, 1h 9s, 1ʜ 5ᴍ 9ꜱ, 1ʜ 9ꜱ
• Render pattern, prefix and suffix with variables: %t (timer), %c (coordinates), %f (facing direction)
• Extra fields globally or per player
• Automatic pause on: advancement, credits, player death, mob kill, players leaving, item obtained
• 12 ready-made profiles (galaxy, emerald, candy, maritime, forest, motley, crimson, …) and your own
• Short commands /start, /pause and /reset next to the full /timer command
• Paused screen: while paused the actionbar shows a configurable text instead of the time
• Custom chat prefix with hex gradient support (&#rrggbb)
• Hooks: run console commands when the timer reaches zero, a full minute/hour/day, is paused, continued or reset
• Developer API with Bukkit events
• State survives restarts (data.yml)

Chat messages are in German; the text shown while paused and the chat prefix can be changed in the config.

---

📦 Installation

1. Drop AnimatedTimer-x.y.z.jar into your server's plugins/ folder.
2. Restart the server.
3. Type /timer help.

Requires Paper 26.1+ and Java 25 (or a Paper fork such as Purpur). Spigot is not supported.

---

🎮 Commands

Main command: /timer (aliases /at, /animatedtimer). Short commands: /start, /pause, /reset.

Timer control

Command	Description
/timer continue or /start	Continue the timer (aliases: start, resume)
/timer pause or /pause	Pause the timer (alias: stop)
/timer reset or /reset	Reset & start. UP mode: from 0, DOWN mode: from the last set time
/timer reboot	Mode UP, paused, time 0
/timer set <seconds|minutes|hours|days> <value>	Set a single unit
/timer set <[[dd:]hh:]mm:ss>	Set the whole time, e.g. /timer set 10:00
/timer set time <d> <h> <m> <s>	Set the whole time with separate values
/timer mode [up|down]	Toggle / set the counting direction
/timer visibility [shown|hidden]	Show / hide the actionbar

Style

Command	Description
/timer style [static|animated]	Toggle the style type
/timer render [caz|saz|snz|taz|tnz]	Toggle / set the render type
/timer animation list	List all animations with a color preview (click to load)
/timer animation load <name>	Activate an animation
/timer speed <ticks>	Ticks per animation step
/timer direction [l2r|r2l]	Animation direction
/timer bold [1|2]	Toggle bold (1 = primary, 2 = secondary)
/timer italic [1|2]	Toggle italic
/timer color <1|2> <color>	Static colors: red, gold, #1ef9ca, …
/timer pattern <text>	Render pattern, e.g. ⌛ %t · %f ⚓
/timer prefix [text]	Gray text in front of the timer
/timer suffix [text]	Gray text after the timer
/timer extra [global|individual]	Extra fields for everyone or per player
/timer show	Print the current style configuration

Render types

Type	Example
caz	01:05:09
saz	1h 5m 9s
snz	1h 9s
taz	1ʜ 5ᴍ 9ꜱ
tnz	1ʜ 9ꜱ

Pattern variables

Variable	Meaning
%t	Position of the timer (pattern only; without it only the text is shown)
%c	Coordinates of the viewing player
%f	Direction the player is facing (N, NE, …)
%%	A literal %

Automatic pause

Command	Description
/timer autopause achieve [advancement]	Pause when a player gets the advancement, e.g. minecraft:end/kill_dragon
/timer autopause credits	Pause when a player sees the credits
/timer autopause death	Pause when a player dies
/timer autopause defeat [mob]	Pause when a player kills the mob, e.g. ender_dragon
/timer autopause leave [disabled|single|all]	Pause when one / all players leave (default: all)
/timer autopause obtain [item]	Pause when a player has the item, e.g. nether_star
/timer behavior	Print the current behavior configuration

Run a command without a value to disable that pause event.

Profiles

Command	Description
/timer profile list	List all profiles (click to load)
/timer profile load <name>	Load a profile
/timer profile save <name>	Save the current style as a profile
/timer profile view <name>	Show a profile's contents
/timer profile delete <name>	Delete a profile

Built-in: galaxy, emerald, candy, maritime, forest, secondary, explore, lavender, motley, crimson, aqua, labeled

Other

Command	Description
/timer help	Command overview
/timer info	Version, current time and links

---

🔐 Permissions

Permission	Default	Grants
animatedtimer.view	everyone	info, show, behavior, animation & profile lists
animatedtimer.control	OP	continue, pause, reset, reboot, set, /start, /pause, /reset
animatedtimer.configure	OP	style, behavior, auto-pause, profiles
animatedtimer.individual	everyone	own pattern/prefix/suffix in individual mode
animatedtimer.*	OP	everything

---

⚙️ Configuration (config.yml)

messages:
  # chat prefix, supports &-codes and &#rrggbb hex colors
  prefix: "&8[&#00D6FFL&#00DBDFe&#01E0BFg&#01E59Fi&#02EB80T&#02F060i&#02F540m&#03FA20e&#03FF00r&8] "
  # chat reply to /pause, also shown in the actionbar while paused
  paused: "Der Timer ist pausiert"
  # true = actionbar shows only the paused text while paused; false = time + " (paused)"
  paused-actionbar: true
hooks:
  reach_zero:
    - "say The countdown is over!"
    - "title @a title {\"text\":\"Time's up!\"}"
  reach_full_minute: []
  reach_full_hour: []
  reach_full_day: []
  timer_pause: []
  timer_continue: []
  timer_reset: []
autosave-seconds: 60

Hooks are console commands executed on timer events. Placeholders: %days%, %hours%, %minutes%, %seconds%, %ticks%, %state%.

---

🧩 Developer API

AnimatedTimerAPI api = Bukkit.getServicesManager().load(AnimatedTimerAPI.class);
api.setTotalSeconds(600);
api.setMode(TimerMode.DOWN);
api.resume();

Events: TimerPauseEvent, TimerContinueEvent, TimerResetEvent, TimerReachZeroEvent, TimerReachFullUnitEvent

---

❤️ Credits

Original datapack Animated Timer by Tapir0 (MIT). Documentation of the original: animated-timer.gitbook.io/docs

Licensed under MIT.