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.
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 startstraining.default-drill(gridshotby default), or the first drill inconfig.ymlwhen 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>. |
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.
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#
| 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-completeeffect plays ("TIME"). - The run is stored, if anything happened in it. Only a run that ran its course is ever stored.
- 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 thepersonal-besteffect, 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.
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.
| 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.
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#
| 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 | Leaving 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_FOUND | ExyliaPracticeCore 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.
| 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. 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 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 | Untouched 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 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. The ping taken off is capped, and what is left below a human floor is a false start. |
| 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. |
| On the way in and out | Between 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. |
| 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. 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 means | A 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 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. |
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#
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| 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.lock-rotation | true | Locks 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-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. A player who left the arena's world on their own — a portal, a warp — is restored where
they went instead. See Arenas.
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