Statistics

Four tables hold what a player has done. Each answers a different question, and none is rebuilt from another, which is what makes the two history tables safe to prune.

The fifth table, aim_arenas, holds the arenas and is covered on Arenas.

The profile

The row is loaded when the player joins, written on every change and again when they quit. A player whose row is still loading plays with the default settings.

The profile row also carries a freeze column. It is always written as true and nothing reads it; it stays so an existing table needs no migration.

/aim profile, or /aim stats, opens the profile screen: rating, accuracy, sessions and duels on the head; hits, shots, fastest flick and reaction and time trained; duels played, wins, losses, win rate and rounds; the current and best duel streak; and buttons to Records, Sessions, Duel history and Leaderboards. /aim profile <player> opens someone else's, read from the database when they are offline. The name has to be one ExyliaLib's player cache knows; otherwise the command answers player-not-found.

Records

One row per player and drill, keyed uuid:drill. A run is merged into its row when it did anything: a hit, a miss, an expired target, a false start or a single tracked tick. A run that ended during the countdown stores nothing.

A run counts whether it ran its course or not. Leaving mid-run, quitting, being taken back by ExyliaPracticeCore or pressing Play again mid-run all store the run as far as it got.

When the rating beats the old best, the difference is added to the profile's overall rating, the result screen and chat call it a personal best, and the cached boards are dropped so the player sees themselves on the board they just climbed.

The Records screen, reached from the profile, lists every row the player holds in the order the drills appear in config.yml; a row for a drill no longer in the file goes last. Each row shows the best rating and the size and distance it was set at, the other bests, and the drill's lifetime sessions, accuracy and time.

Leaderboards

There is one board per drill, sorted by one of seven categories, and one overall board.

Names and icons live in messages.yml under menu.categories.

A player appears once per drill board, since the records are one row per player and drill. A zero never takes a place: an unset reaction, a combo in a drill that has none, an accuracy from runs below the shot floor. So the reaction board of a flick drill and the combo board of anything but a fight stay empty.

The overall board

Everybody by the sum of their best rating in every drill, read from aim_profiles. It sorts by rating or by accuracy (lifetime accuracy) and nothing else: the category row on that board offers those two, and asking for another category shows the rating board.

Opening a board

/aim leaderboard, or /aim top, opens the board picker: the overall board first, then every drill in config order. /aim leaderboard <drill> opens that drill's board sorted by rating, and /aim leaderboard <drill> <category> by that category; overall works as the drill. An unknown drill opens the picker instead of an empty board, and an unknown category falls back to rating. Inside, the category buttons re-sort the open board in place, and the top three rows wear medals.

The same boards are readable through PlaceholderAPI, as %exyliaaimtrainer_top_<drill>_<category>_<n>% and its _value. See Placeholders.

The cache

leaderboard:
  entries: 10
  cache-seconds: 300
  accuracy-min-shots: 20

Every board keeps two copies: a fresh one, which expires after cache-seconds, and the last one ever read. A menu waits for a fresh read; a placeholder shows the last copy while the fresh read runs in the background, so a hologram never blinks back to Loading… once it has shown a board.

The fresh copies are dropped when a run beats a rating, and when a player is reset. A run that improves only another best — accuracy, hits, a streak — does not drop them: that board catches up within cache-seconds.

History

Two lists, each reached from the other: Sessions (/aim sessions) and Duel history (/aim history). Both show the newest rows first.

A session row is one stored solo run: the drill and its kind, the score, rating and difficulty, hits, misses, accuracy, precision, best streak and combo, the average flick and reaction, time on target, the duration, the average ping and the date. A run that set a personal best is drawn with a star.

A duel writes two rows to aim_matches, one per participant, so "my duels" is a one-column query. Each carries the opponent, whether the player won, the drill, the best-of, the rounds for and against, the points for and against, the hits, the accuracy, the duration and when it ended. Only a duel that has a winner writes them; a cancelled duel writes nothing.

history:
  entries: 20
  retention-days: 30
  prune-interval-minutes: 60

A sweep looks at the oldest 500 rows of its table and deletes the ones past the cutoff, so a backlog drains over several sweeps rather than one long transaction.

Resetting a player

From /aimtraineradmin → Players, behind a confirmation. A reset:

• puts the profile back to zero — lifetime numbers, the duel record and the overall rating — while keeping the player's settings and last picks;
• deletes every record the player holds, so they leave every drill board;
• deletes their session history;
• drops the leaderboard cache.

Their rows in aim_matches are not deleted: the duel history screen still lists past duels until retention removes them, even though the confirmation reads "Every record, session and duel".