are Event Priorities a conventional matter?

Discussion in 'Spigot Plugin Development' started by HorrendousEntity, Jul 8, 2018.

  1. A question from a person who never defined a priority for his events: "Given a plugins list that all of them contain the same certain event with the same certain priority; In what order would those events be executed?"

    I literally can't visualize a situation when defining an event priority is criticial as it's getting treated.
    furthermore - how do a programmer decides which event priority is "the best" for a certain case? It must be conventional because it affects other plugins as well.

    beriefly: why do that option even exists?
    #1 HorrendousEntity, Jul 8, 2018
    Last edited: Jul 10, 2018
    • Agree Agree x 2
  2. Because sometimes you need to monitor the outcome of an event, so you need to make sure all other plugins that could change the outcome have passed.
  3. It makes sense in the context of multiple plugins working together with different devs, without the devs cooperating.

    For example if you're using a plugin which prepends player ranks in chat.
    You can make a quick plugin to add their guild before or after that player rank depending on priority.

    Sadly, often the cleanest examples are to do with cancellation and lots of devs omit adding ignoreCancelled when it would be relevant.
  4. Imagine worldguard and another plugin that handles the blockbreakevent.
    If one ignored the blockbreakevent if it was cancelled and worldguard did indeed cancel it then some weird stuff could happen.
    An example would be a quest plugin. Think that you have to break 10 stone blocks and somewhere there is a worldguard region that is protection some stone blocks. If the priorities are not set correctly then the player could break the same block 10 times without it actually breaking and the quest could progress normally.

    This is why it is essential that one knows how the event priorities work.
  5. how do you choose among the priorities? is the selection a matter of convention?
  6. Priorities are ordered as LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR (with LOWEST being the first to be called while HIGHEST should get the final say on what changes in the event). MONITOR is ran last but nothing should be modified by events with that priority (pretend everything is Read-Only).

    Using the previous example... There may be many plugins that prevent block breaking (ex: WorldGuard, Factions, GriefPrevention, Towny, etc). You may not know what priorities any of these use, but you do know that your quest plugin only cares if the player actually broke a block. Since you aren't changing the event and only want to know what broke, you will want to use the priority MONITOR. This will ensure that your event is ran after all of the previous priorities. Add it together with ignoreCancelled = true and you'll have a quest plugin that is compatible with all plugins that use priorities correctly.

    If a plugin decides to ignore the javadoc and uses MONITOR all the time while also changing items in the event or changing the cancelled state, that plugin will potentially lose compatibility with other plugins. The same can be said if you used anything but MONITOR for the quest plugin. As darklazerog said, unintended things will happen due to the order the events are called.

    Many times you may not know what priority is best for your event. In this case, you have to take an educated-guess or just leave it at NORMAL until you see a need to change it. You'll want to try to think about what could happen if other plugins modify the event in any way before or after your plugin did something. Some developers listen to their users and modify priorities after someone says there's an incompatibility with another plugin, some developers make their event priorities configurable, and some just don't know or care about setting priorities.

    Making configurable priorities lets knowledgeable users fix their incompatibilities themselves, but writing the code that makes that possible can be a pain and you'll still want to try to set a good default.

    Descriptions from the EventPrioritiy javadoc:
    Code (Text):
    LOWEST: Event call is of very low importance and should be ran first, to allow other plugins to further customise the outcome
    LOW: Event call is of low importance
    NORMAL: Event call is neither important nor unimportant, and may be ran normally
    HIGH: Event call is of high importance
    HIGHEST: Event call is critical and must have the final say in what happens to the event
    MONITOR: Event is listened to purely for monitoring the outcome of an event. No modifications to the event should be made under this priority
    • Winner Winner x 2
  7. Thanks in advance for your useful comment!
    During the reading I came to the conclusion that a conflict might occour if the priority choice is free; I can't straightforwardly imagine a situation where it occours but the main idea is that in order to be compatible with a certain plugin(s) I'd have to set the X priority - but that makes certain plugin(s) not compatible and vice versa.

    that's a really complex situation and as I imagine it - there's nothing to do but to manually either to change the code of any plugin or break your head.
  8. 90% of the time you'll probably only need ignoreCancelled and the default priority. Again, until there is an issue with the event priorities, such as if you are writing an overseer plugin such as a protection plugin for example (in which case you'd want a higher priority) then there is really no reason to need event priorities. Of course, some plugin authors are pretty stupid so you'll need event priorities when some other plugin does something dumb like a chat plugin that is on HIGHEST for example but does not provide an API.
  9. what do you mean does not provide an API?
  10. I'm saying theoretically. If a chat plugin is able to override everything else via their HIGHEST priority PlayerChatEvent listener, no other plugin that deals with chat can be used such as a plugin to replace certain words of chat or a chat filter if the plugin does not provide a means to access the chat event since their listener will override everything else
  11. I still don't get what you're saying by "if the plugin does not provide a means to access the chat",
    You're talking about the priority itself right?
  12. Yes, because when you put your listener on HIGHEST, no other plugin will be able to reliably modify the chat if they need. The HIGHEST priority listener gets the final say in the event and will just override the changes if it wants to, which breaks all the lower priority listeners.
  13. Given a plugins list that all of them contain the same certain event with the same certain priority; In what order would those events be executed?
  14. Order is not gauranteed. That's something that's implementation specific and the API holds no promises.
  15. The Spigot implementation of Bukkit's event priorities do not have a finer grain of control past event priorities