Systems

Training

The solo session from start to rest, how a click is judged, and what the plugin protects while a player is inside.

A solo session is one player, one arena and one engine. The engine is the same object a duel uses, so everything on this page about clicks, the hotbar and protections applies to duels too; what a duel adds is on Duels. What the drills are and how a run becomes a number are on Drills and Scoring.

Starting a drill

Three ways in:

/aim train <drill>. Without a drill it starts training.default-drill (gridshot by default), or the first drill in config.yml when that one no longer exists.
/aim drills, or Drills in /aim, and a click on a drill.
Play again on the result screen or the hotbar, which replays the drill a player is already in.
Change drill on the result screen or the hotbar, which swaps the drill without leaving the arena. See Changing drill.

Before anything moves, the start is refused, with a message, when:

Situation	Message
The drill id is not in `config.yml`	Unknown drill `<drill>`.
PacketEvents is not available	Targets need PacketEvents, which this server does not have.
No arena is ready, or every ready arena is full	No arena is ready. Ask an administrator.
The player is already in a drill or a duel	Finish what you are doing first.
The player waits in an ExyliaPracticeCore queue and practice will not lend them	Practice cannot lend you right now.
Another plugin holds the player	You are busy in `<plugin>`.
Another plugin advises against taking the player	Not right now: `<reason>`.

No arena, no drill

A drill always runs in an arena. With none ready the player is refused before they are claimed, so a refusal never touches their inventory or position. See Arenas.

A player waiting in a practice queue is not refused for being held by practice: practice lends them, keeps their place in the queue and asks for them back when a match is found. That is on Compatibility.

A session, start to finish

Claim and snapshot

The player is claimed for TRAINING, their location is remembered and their inventory is saved. The chat confirms: "Drill started: <drill> · ×<difficulty> difficulty." The drill is remembered on their profile as their last choice.

Isolation

They join a group of their own: they see nobody, nobody sees them, and they cannot be touched from outside.

The arena

The ready arena hosting the fewest players is picked and the player is teleported to its spawn.

Dressed on arrival

Only once they stand in the arena is their inventory emptied and their game mode set to adventure. The order is deliberate: a per-world inventory plugin records whatever a player holds as they change world, so emptying them before the teleport would write an empty inventory into the world they came from.

The screen

Movement is frozen, the held slot is set to the first one, the drill's weapon goes into it (or it is left empty), the hotbar buttons, boss bar and sidebar appear, and the countdown starts. See HUD.

Countdown

training.countdown seconds (3.0 by default) with the countdown effect. Punching the air ends the countdown at once. 0 skips it.

The run

The go effect plays and the first targets appear. The run lasts the drill's duration, or until a reaction drill's attempts are answered.

The three phases

Phase	What is happening	A punch
`COUNTDOWN`	The number is counting down; no target is up.	Starts the run now.
`RUNNING`	The drill is live.	Is a shot, judged by the engine.
`RESTING`	The drill ran its course and the player stays in the arena.	Nothing.

%exyliaaimtrainer_phase% reads them in lowercase — countdown, running, resting — and none for a player who is not in a drill, a duellist included. See Placeholders.

When a drill ends

A drill that runs its course does not send anyone home. In order:

The session-complete effect plays ("TIME").
The run is stored, if anything happened in it.
The session summary screen opens: rating, score, difficulty, duration, ping, hits, misses, accuracy, precision, streaks, flick and reaction times, time on target, and the change against the player's best on that drill.
One line lands in chat: "★ New personal best · rating <rating> (+<delta>)" with the personal-best effect, or "Rating <rating> · your best is <best> (<delta>)".

The player then rests for training.rest-seconds (5 by default). In that window the Play again button on the summary or the hotbar replays the drill; Change drill starts another one. The time running out sends them home, but only if they are idle:

With the summary still open, or no screen open at all, they are idle: the summary closes and they go home.
With a screen they opened themselves — the settings, the drill list, a value being typed — they are still deciding. The wait starts over, for another rest-seconds, and is checked again when it ends.

With rest-seconds: 0 they are sent home as soon as the drill ends.

Upgrading from a 20-second rest

Earlier builds shipped rest-seconds: 20.0. The config migrates a 20 it finds to 5; any other value the owner chose is kept.

Playing again

Play again is a full restart. Whatever the session is doing — resting, counting down, or halfway through a run — the current run is stopped and stored, the countdown is dropped, and a new countdown begins. The new run reads the player's current settings, so a change made in /aim settings while resting applies to it, and it draws a new random sequence.

Changing drill

Change drill, on the summary or the hotbar, opens the drill list. A click on a drill there, from inside a session, does not refuse the player as busy: it swaps the session to that drill in the same arena, whether they are resting, counting down or mid-run. It works like Play again with another drill:

the run in progress is stopped and stored under the drill it was;
the new drill becomes the player's last choice on their profile;
the chat confirms "Drill started: <drill> · ×<difficulty> difficulty.";
a new countdown begins, reading the player's current settings.

No new start event fires; it is still the same session. Picking a drill that no longer exists reads "Unknown drill <drill>." and changes nothing. In a duel the button still opens the list, but a pick is refused with "Finish what you are doing first."

The hotbar

While a drill or a duel runs, four buttons are drawn over the hotbar. They are packets: nothing is a real item, so nothing can be dropped, moved or walked out with.

Slot	Button	Right click
6th (slot 5)	Change drill	Opens the drill list; a pick changes the drill, as above.
7th (slot 6)	Settings	Opens the settings screen. Changes apply from the next run.
8th (slot 7)	Play again	Replays the drill, as above. Does nothing in a duel.
9th (slot 8)	Leave	Leaves the drill, or forfeits the duel.

Slots 0 to 4 are left to the real inventory, because slot 0 holds the drill's weapon when it has one. The whole overlay can be turned off with hud.hotbar: false.

menus/hotbar.yml is rewritten on every start and every reload

The file is copied over from the jar each time the plugin starts and each time it reloads, so a button added in a release reaches servers that already have it. An edit to it does not survive. Turn the overlay off with hud.hotbar instead.

How a session ends

Reason	When	What the player sees
`COMPLETED`	The drill ran its course. The session carries on resting.	The summary screen and the best line.
`LEFT`	`/aim leave`, a Leave button, or the rest ran out.	"Drill stopped." when a run was cut short; `/aim leave` also says "You left."
`DISCONNECTED`	The player quit.	Nothing.
`CANCELLED`	A world change, a teleport the plugin did not make (an ender pearl, a chorus fruit), a death from another plugin, another plugin taking the player back, an administrator stopping the session, the arena being disabled or deleted, the plugin disabling.	Nothing; they are sent home.
`MATCH_FOUND`	ExyliaPracticeCore found the player a match while they trained.	"A practice match was found. Good luck!"

A run is stored whenever anything happened in it: a hit, a miss, an expired target, a false start or a tracked tick. That holds for a run cut short as well: its numbers reach the profile, the drill's records and the session history exactly like a finished one, only without the summary. Leaving mid-run neither voids a good run nor hides a bad one. See Statistics.

The AimTrainingEndEvent carries the same reasons; see API.

How a click is judged

Nothing about a target exists on the server. Each one is two entities sent only to its player: a block display that is seen, and an interaction hitbox riding it that is hit. Nobody else sees them, the server ticks nothing for them, and nothing is saved.

What	How it is decided
A hit	The player's own client runs the same hitbox test it runs on a PvP opponent and reports an attack on the hitbox. The hit is judged where the player saw the target, at their own frame rate. The attack packet is then dropped, so the server never sees a click on an entity it does not have.
A miss	A swing that no attack came with. Before calling it a miss, the server casts its own ray from the eyes along the player's last rotation; if that ray crosses a target, it is a hit after all. Only then is it a miss.
A moving target	Judged where the client drew it: every position sent is kept, and the check looks back by the player's ping plus the two ticks the client smooths a move over.
Reach	64 blocks for every drill but a fight, given as a temporary attribute and removed on the way out. A `COMBO` fight is played at the game's three blocks.
A fight	A hit on a target still red from the last one (half a second) does nothing, as in the game. In a 1.9 fight every swing, hit or miss, and every change of held slot restart the attack cooldown, and a hit on a swing charged no more than 90% is rushed and counts as a miss.
A reaction	Timed from the moment the light was sent, minus the player's ping, so two players on different connections are graded on their hands.
Tracking	Checked every tick along the rotation the client last sent, against where the client drew the target, forgiving half a tick either side.
Precision	The server's ray through the target says how central a hit was. A ray that misses because the crosshair was moving leaves that hit unmeasured rather than scoring it as an edge.

Ping is sampled once a second. What each of these does to the score is on Scoring.

While inside

The same protections apply to drills and duels. They cover whoever is in a session; players outside one are left alone.

What	Rule
Damage	Every damage event on the player is cancelled, and so is any attack they make on anything.
Hunger	Frozen.
Items	Dropping and picking up are cancelled.
Blocks	Breaking and placing are cancelled.
Other players	Invisible both ways, not collidable, and right-clicking anyone outside the session is cancelled.
Chat	With `chat.isolation: true` (the default), a player in a session reads only their own session's chat and the rest of the server reads none of it. A session is one player, and each side of a duel is its own, so in practice nobody reads them.
Commands	Only the labels in `training.allowed-commands` run. Anything else reads "Leave with /aim leave before using that command." A `plugin:command` prefix is stripped before the check.
Game mode	Adventure, whatever the player arrived in. The original mode comes back with the snapshot.
Movement	Frozen while the countdown and the drill run: the client's own movement packets are dropped. Turning still works and is what aims.
Leaving by other means	A teleport the plugin did not make or a world change ends the drill, or forfeits the duel.
A death from elsewhere	If another plugin kills the player anyway, the inventory is kept, the drops are cleared, the console warns and the player is taken out.

Standing still is not a setting

Every drill freezes the player. There is no option to walk during one, for the player or in config.yml: a drill measures the hands.

Configuration

plugins/ExyliaAimTrainer/config.yml

training:
  countdown: 3.0
  rest-seconds: 5.0
  default-drill: gridshot
  allowed-commands: [aim, aimtrainer, at, msg, r, tell, w]
 
chat:
  isolation: true

Key	Default	What it does
`training.countdown`	`3.0`	Seconds before the first target is live. Also the countdown of every duel round. `0` skips it.
`training.rest-seconds`	`5.0`	Seconds a player may stay idle in the arena after a drill before being sent home. A screen they opened themselves extends the wait. `0` sends them home at once.
`training.default-drill`	`gridshot`	The drill `/aim train` starts without a name.
`training.allowed-commands`	see above	Command labels a player may still run in a drill or a duel.
`chat.isolation`	`true`	Keeps a session's chat inside it. `false` leaves chat as the server's chat plugin delivers it.

Leaving

Exit runs in a fixed order. The HUD comes down first: the boss bar, the extra reach, the weapon, the freeze, the hotbar buttons, and the experience bar is set back to what the server really holds. Then the player leaves the isolation group, the sidebar is hidden, they are teleported home, their inventory and game mode are restored there, and the claim is released last, so no other mode can dress them while their things are still on the way back.

Home is arena.return-location when it is set, otherwise the exact spot they started from, otherwise their world's spawn. See Arenas.

After a crash

A snapshot left behind by a restart is restored on the player's next join, and they are sent back to where they were before the session started. Nobody wakes up inside an arena.

Something missing on this page? Tell us on Discord