[1.17+] ATHENA - A robust, user-friendly and detailed in-game event debugger

ATHENA is a small side project which I use to help find why an event results in a particular manner whilst ensuring that it is user-friendly and robust.

At this time, ATHENA is still in BETA and isn’t perfect. This milestone documents what remains before the plugin has its first full release.

Installation is the same as most common plugins’, just drop it into the plugins folder and restart the server. Use /reload and I’ll need to have a word with you privately.

Releases: https://github.com/Errored-Innovations/ATHENA/releases
Source: https://github.com/Errored-Innovations/ATHENA
Discord: https://discord.gg/Jrr6veTNGF
Donations but honestly I don’t care don’t worry I have a well-paying job: https://ko-fi.com/thatsmusic99

Features

  • See what plugins are listening to each event.
  • See the changes an individual plugin makes to an event.
  • See the amount of milliseconds it takes for a plugin to finish running their listener.
  • See the listener class that is making changes to a given event.

Requirements:

  • Java 16
  • Minecraft 1.17 or newer
  • Paper*

*This plugin has not been tested on other server types/forks. Please use this plugin on other server types at your own risk. Any problem that appears on different server types can be considered a bug, but only if said server type being used is Purpur or Airplane. Other server types are considered unsupported (including CraftBukkit and Spigot).

Commands

  • /athena listen <Event Name|Class> - listens to an event of a given name, like PlayerTeleportEvent. All events being listened to actively are cached and will display in the tab complete menu, but in the event that an event does not appear, the full class needs to be inserted (e.g. io.github.thatsmusic99.athena.ListenEvent).
  • /athena listener <Event|Plugin> - lists the listeners for a plugin or event.
  • /athena stop [Event] - stops listening to a named event, or all if none is specified.

Permissions

  • at.command.listen - provides access to /athena listen
  • at.command.listeners - provides access to /athena listeners
  • at.command.stop - provides access to /athena stop

Disclaimer

ATHENA is made with usability, stability and detail in mind. However, performance is not necessarily a priority with the plugin. Whilst I have applied the majority of my knowledge to make the plugin as optimised as possible, it is not recommended to run ATHENA when you don’t need it. The plugin uses a considerable amount of reflection to function and collect data from events, which in itself can take a hit on performance. In addition, whilst ATHENA does not (or at least tries to not) interfere with individual plugin listeners, it may have an impact on how optimised they may appear in Paper’s Timings. If you are measuring event performance using Timings and ATHENA, it is recommended to take separate measurements (e.g. /timings paste first, then use ATHENA to see completion times on one occasion).

If you are a server owner measuring listener durations, you should only be concerned about performance if a single listener exceeds 40ms of completion time. A single tick in Minecraft takes 50ms, hence why 20 TPS is an important number to aim for in servers. Please do not nag plugin developers if their listeners’ time simply takes the longest; some plugins need to carry out more tasks than others. In addition, a spark/profiling report, as well as timings, may be more helpful than a single snippet from ATHENA.

If ATHENA is unable to listen to a specific event or crashes when you attempt to do so, please open an issue with the event. If it is an event from a plugin, please send the class of the event where possible.

If ATHENA experiences an error, it should still let the listeners it has control over run so it should not have an impact on other plugins’ functionality.

PRs and suggestions on how to improve the plugin - including its performance - are more than welcome.

1 Like