Content generated with AI — it may contain mistakes.

ExyliaAimTrainer/How it worksUpdated in v1.2.0

How a drill session works

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

Page 10 of 2515 min read

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#

Four 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:

SituationMessage
The drill id is not in config.ymlUnknown drill <drill>.
PacketEvents is not availableTargets need PacketEvents, which this server does not have.
No arena is ready, or every ready arena is fullNo arena is ready. Ask an administrator.
The player is already in a drill or a duelFinish what you are doing first.
The player waits in an ExyliaPracticeCore queue and practice will not lend themPractice cannot lend you right now.
Another plugin holds the playerYou are busy in <plugin>.
Another plugin advises against taking the playerNot right now: <reason>.

A second start, replay or drill change within two seconds of the last one is ignored without a message, so a start-and-leave loop cannot hammer the arena.

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. If that teleport is cancelled or fails, the drill never starts: the player is given back where they stood and reads "You could not be taken to the arena. The drill was cancelled."

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#

PhaseWhat is happeningA punch
COUNTDOWNThe number is counting down; no target is up.Starts the run now.
RUNNINGThe drill is live.Is a shot, judged by the engine.
RESTINGThe 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:

  1. The session-complete effect plays ("TIME").
  2. The run is stored, if anything happened in it. Only a run that ran its course is ever stored.
  3. 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.
  4. 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 dropped unstored, 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 dropped, unstored;
  • 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.

SlotButtonRight click
6th (slot 5)Change drillOpens the drill list; a pick changes the drill, as above.
7th (slot 6)SettingsOpens the settings screen. Changes apply from the next run.
8th (slot 7)Play againReplays the drill, as above. Does nothing in a duel.
9th (slot 8)LeaveLeaves 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.

The buttons live in menus/hotbar.yml under the plugin's lang/ folder. The file is yours, like the player screens: an edit survives a restart and a reload, and a button added in a release still arrives as a new key. See Menus.

How a session ends#

ReasonWhenWhat the player sees
COMPLETEDThe 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."
DISCONNECTEDThe player quit.Nothing.
CANCELLEDLeaving the arena's world, 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_FOUNDExyliaPracticeCore found the player a match while they trained."A practice match was found. Good luck!"

Only a run that ran its course is stored, and only when anything happened in it: a hit, a miss, an expired target, a false start or a tracked tick. A run cut short — by leaving, a replay, a drill change, a practice match, an administrator or anything else above — reaches neither the profile, nor the drill's records, nor the session history: a few hundred milliseconds with one lucky hit would extrapolate to a record no full run can reach. See Statistics.

The AimTrainingEndEvent carries the same reasons; see API.

How a click is judged#

Nothing about a target exists on the server. On Java 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. A Bedrock client draws neither, so a Bedrock player's target is one slime as wide as the target (see Compatibility). Nobody else sees them, the server ticks nothing for them, and nothing is saved.

WhatHow it is decided
A hitThe 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. An attack the client could not have made is ignored and its swing judged on its own: out of the fight's reach, or, on Java, with the crosshair nowhere near the target. The look checked is the one the click arrived with, not where the player turned a tick later.
A missA 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 targetJudged 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.
ReachUntouched on Java: a target farther than a sword swing is hit through a stand-in hitbox drawn a block and a half from the eye, covering the same piece of screen, so the click lands inside vanilla reach and an anticheat sees nothing out of range. A Bedrock player gets 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 fightA 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 reactionTimed from the moment the light was sent, minus the player's ping, so two players on different connections are graded on their hands. The ping taken off is capped, and what is left below a human floor is a false start.
TrackingChecked every tick along the rotation the client last sent, against where the client drew the target, forgiving half a tick either side.
PrecisionThe 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.

WhatRule
DamageEvery damage event on the player is cancelled, and so is any attack they make on anything.
On the way in and outBetween the claim and arriving in the arena, and between leaving and being home, the player still holds their real items, so damage, hunger, drops, pickups, placing and breaking blocks, using an item, and opening a chest or the ender chest are refused then too.
HungerFrozen.
ItemsDropping and picking up are cancelled.
BlocksBreaking and placing are cancelled.
Other playersInvisible both ways, not collidable, and right-clicking anyone outside the session is cancelled.
ChatWith 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.
CommandsOnly 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 modeAdventure, whatever the player arrived in. The original mode comes back with the snapshot.
MovementFrozen while the countdown and the drill run: the client's own movement packets are dropped. With training.lock-rotation: true (the default) the camera is locked too until the countdown ends, so nobody pre-aims; turning works again once the first target is live, and is what aims.
Leaving by other meansA teleport the plugin did not make ends the drill, or forfeits the duel. Leaving the arena's world does too, and the player stays in the world they went to rather than being sent home.
A death from elsewhereIf 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
yaml
training:
  countdown: 3.0
  lock-rotation: true
  rest-seconds: 5.0
  default-drill: gridshot
  allowed-commands: [aim, aimtrainer, at, msg, r, tell, w]
 
chat:
  isolation: true
KeyDefaultWhat it does
training.countdown3.0Seconds before the first target is live. Also the countdown of every duel round. 0 skips it.
training.lock-rotationtrueLocks the camera during the countdown of a drill and of every duel round, so nobody can pre-aim before the first target. false lets players turn during it.
training.rest-seconds5.0Seconds 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-drillgridshotThe drill /aim train starts without a name.
training.allowed-commandssee aboveCommand labels a player may still run in a drill or a duel.
chat.isolationtrueKeeps 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. A player who left the arena's world on their own — a portal, a warp — is restored where they went instead. 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