# ⏱ Animated Timer (Plugin) **An animated, extensively configurable in-game timer for Paper servers.** This is a plugin port of the popular [Animated Timer datapack](https://modrinth.com/datapack/animated-timer) 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 ` | Set a single unit | | `/timer set <[[dd:]hh:]mm:ss>` | Set the whole time, e.g. `/timer set 10:00` | | `/timer set time ` | 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 ` | Activate an animation | | `/timer speed ` | 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> ` | Static colors: `red`, `gold`, `#1ef9ca`, … | | `/timer pattern ` | 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 ` | Load a profile | | `/timer profile save ` | Save the current style as a profile | | `/timer profile view ` | Show a profile's contents | | `/timer profile delete ` | 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`) ```yaml messages: # chat prefix, supports &-codes and &#rrggbb hex colors prefix: "&8[�D6FFL�DBDFeE0BFgE59FiEB80TF060iF540mFA20eFF00r&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 ```java 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](https://modrinth.com/datapack/animated-timer) (MIT). Documentation of the original: [animated-timer.gitbook.io/docs](https://animated-timer.gitbook.io/docs) Licensed under MIT.

Legicrafter