Getting Started

##1. Installation

To get started with Aevum, install the plugin on your Minecraft server:

• Requirements: a Spigot or Paper server running Minecraft 1.20+. CraftBukkit is not supported.
• Optional integrations:
  • PlaceholderAPI — adds the %aevum_…% placeholders.
  • Stella — required only for team-scoped timers/stopwatches.

Drop the .jar into your server's plugins folder and restart. Aevum generates config.yml and messages.yml inside plugins/Aevum/, and persists your live instances to data.json.

---

##2. Timers vs Stopwatches

• A timer counts down from a duration to zero, then ends (firing its end event and any matching actions).
• A stopwatch counts up from zero and runs until you pause, reset or delete it.

/aevum timer create <name> <time> [scope] [target]
/aevum stopwatch create <name> [scope] [target]

Example: /aevum timer create event 5m creates a global 5-minute countdown named event. /aevum stopwatch create run creates a global stopwatch named run.

Names may use letters, numbers, _ and -.

---

##3. Time format

Anywhere a <time> is expected you can use:

Input	Meaning
90	90 seconds (a plain number = seconds)
90s	90 seconds
5m	5 minutes
1h30m	1 hour 30 minutes
2d	2 days

Units are d (days), h (hours), m (minutes), s (seconds) and can be combined in one token, e.g. 1h30m. Aevum displays time as MM:SS, or HH:MM:SS once it passes an hour.

---

##4. Scopes

Every instance has a scope that decides who owns it. The scope is the optional 3rd argument on create (defaults to global).

Scope	Ownership	Notes
global	One shared instance	The default. No target needed.
player	One instance per player	Pass a player name, or @all for everyone.
team	One instance per Stella team	Pass a team id, or @all for every team. Requires Stella.

Once created under a scope, a name is locked to that scope — trying to reuse it under a different scope is rejected with a scope-conflict error.

/aevum timer create lobby 60 global
/aevum timer create personal 10m player @all
/aevum timer create round 5m team red

---

##5. Targets ([target])

For player- and team-scoped instances, every management command takes an optional target so you can act on one owner or all of them:

Target	Meaning
(empty)	Yourself — only works when run by a player. From console you must specify a target.
<player> / <team>	A single player (must be online) or a single Stella team.
@all	Every instance under that name — all players, or all teams.

Example: /aevum timer add personal 30s @all adds 30 seconds to every player's personal timer, while /aevum timer add personal 30s Alex only touches Alex's. For a global instance the target is ignored.

---

##6. Controlling time

Both timers and stopwatches share the same control verbs:

/aevum <timer|stopwatch> add <name> <time> [target]
/aevum <timer|stopwatch> remove <name> <time> [target]
/aevum <timer|stopwatch> set <name> <time> [target]
/aevum <timer|stopwatch> pause <name> [target]
/aevum <timer|stopwatch> resume <name> [target]
/aevum <timer|stopwatch> status <name> [target]

Stopwatches additionally support reset (back to zero). Use status to see the current value and state (running, paused or stopped).

---

##7. Checkpoints (marks)

A mark records a named split — the remaining time (timer) or elapsed time (stopwatch) at the instant you mark it.

/aevum <timer|stopwatch> mark <name> <label> [target]
/aevum <timer|stopwatch> marks <name> [target]
/aevum <timer|stopwatch> unmark <name> <label|*> [target]

Labels may use letters, numbers and -. marks lists them in time order; unmark <label> removes one and unmark * clears them all. Marks are also readable via placeholders (timer / stopwatch) and the API.

---

##8. The Action Engine

config.yml lets a running timer/stopwatch fire actions (console commands, player messages, broadcasts) when conditions pass — for example, give every player a reward every 60 seconds, or broadcast a message when a timer ends. See the config.yml page for the full breakdown.

---

##9. More Resources

• Timer
  • Overview
  • Commands
  • Placeholders
• Stopwatch
  • Overview
  • Commands
  • Placeholders
• Plugin
  • Permissions
• Configuration Files
  • config.yml
  • messages.yml
• API
  • Aevum API

You're ready to start tracking time with Aevum.