Event Documentation

[TomLewis]

I have found ~events lists events we can use, some are descriptive but others could mean anything or look like they are wanting extra paramters, can we please get some documentation on all events. These are the ones outputted for me;

#~Console
#~Error
#~FatalError
#~Hook
#~PlayerChat
#~PlayerDeath
#~PlayerEvent
#~PlayerJoin
#~PlayerQuit
#~ServerEvent
#~ServerInput
#~ServerOutput
#~ServerStart 
#~ServerStarted
#~ServerStarting
#~ServerStop
#~ServerStopped
#~ServerStopping
#~StatEvent
#~StatPlayerCount
#~StatPlayers
#~StatProcess
#~UserAttach
#~UserDetach
#~UserInput

[Column01]

The code for the events is here, some of it is cryptic, but you can get the gist if you take your time. I can run through quickly what I believe some of them do, but since I haven't taken a dive into mark2 in a while, I may be wrong on some of them.

All plugins that are referred to below are for mark2 plugins, not Minecraft plugins! On top of that, some of these events are not meant to be used by the user directly and are used internally by mark2 or plugins for mark2.

• Console
  • Issued by mark2 to print a line to the console window
• Error
  • Has no code under it, probably just a general event fired on error?
• FatalError
  • A Fatal error event probably used internally (has "Exception" and "Reason" in it)
• Hook
  • Probably used internally? Has some general info in the event.
• Player<something>
  • Fired when a player does some action in the list of somethings. Definitely used internally but could be cool to use for some other stuff if you are too lazy to write a plugin to handle the events from minecraft :P
• ServerEvent
  • Used internally to alert plugins that something is happening to the server
• ServerInput
  • Sends data to the server STDIN
• ServerOutput
  • Issued when the server prints something to STDOUT
• ServerStart
  • Issued to start the server
• ServerStarted
  • Issued when the server is done starting.
• ServerStarting
  • Issued to listening plugins when the server is starting
• ServerStop
  • Issued to stop the server
• ServerStopping
  • Issued to listening plugins when the server is stopping
• ServerStopped
  • Issued when the server has finally stopped
• StatEvent
  • General Stat event that is subclassed by other stat events
• StatPlayerCount
  • Probably Issued to update the player count ticker in the UI
• StatProcess
  • Issued to update the CPU and MEM usage in the UI
• UserAttach
  • A user attached to the mark2 console
• UserDetach
  • A user detached from the mark2 console
• UserInput
  • A user sent a command to the console.

[TomLewis]

some of these events are not meant to be used by the user directly and are used internally by mark2 or plugins for mark2

Aha! That's where my experimenting has been going wrong then! haha I had some @ServerStop events in my scripts.txt! Thanks for going through this list!

What im trying to do is listen to when the server shuts down and send all players to another server on my bungee first.

In my scripts.txt I had; @ServerStop * * * /sudo * server creative

But this wasn't working, I assumed it was listening for when the server stopped then forces all players to run /server creative to send them to another server instead of getting a kick message, but it didn't work, i'm wondering if I should try ServerStopping?

Any ideas if theres a user event for listening for when the servers shutting down and fully started up so I can trigger events then?

[Column01]

ServerStopping might work to listen to. ServerStarted is what you want if you want to handle when the server fully starts

[Column01]

I'm planning on writing a full guide on how mark2 works for the most part while it's fresh in my memory.

This will include documentation of a lot of the events

[Column01]

Added some basic documentation of how mark2 works, event documentation coming soon. See docs here

[edk0]

I think it's important to understand for some background to all this that mark2 is almost entirely its plugins and event system (services are just plugins that always get loaded). Events are how plugins communicate with each other and how almost everything that happens is orchestrated, and only some of those make any sense to use in scripts.txt. We used events there because it was convenient and mostly worked, but it wasn't particularly a polished feature.

As a bit of extra information for your docs, maybe worth noting that the manager doesn't really do very much at all; the work is nearly all in the services. The manager I think starts up and shuts down the reactor, and contains some event handlers that didn't really seem to fit anywhere else. It tracks the player list because a limitation of the plugin architecture is that they only really share events, not state.

An effect of this architecture is that a lot of code can be reloaded while mark2 is running, although since reloaded plugins don't keep state, reloading the process service would lose your minecraft server, and reloading user_server would detach your consoles. Rather than keep explaining that to people we just didn't support it, but it was sometimes useful in the real world, and there was a plugin I'd give to people individually to enable the functionality.

Hook is just a general-purpose event that in practice I think is only ever used to implement commands; the point being that events are a fixed set of things, baked into the code; dynamically addable events like commands therefore require some kind of catchall. If I were designing the thing again I'd just make a Command event and there'd probably be no need for it any more, whatever. In any case an interesting consequence of commands being events is that you can you can react to or even override their behaviour from other plugins.

FatalError tells the manager to exit with an error message. I don't think plain Error is used.

The ServerStop/Start* events work something like: ServerFoo is a command you use to Foo the server. It can be prevented by consuming the event. ServerFooing is issued mostly for internal use when the server has begun the irreversible process of Fooing and we need to attach/detach things to the process. And finally ServerFooed when the Fooing has finished, and it makes sense to inform humans (say, that the server is now playable). By contrast with ServerFoo, consuming ServerFooing or ServerFooed will almost certainly break things.

ServerEvent is for sending push notifications. Probably more things should be sending it; the idea is that the push config is used to select interesting ones.

The Stat* events are listened to by the user server, buffered and sent to the client on its request. See what I mean about not sharing state?

The point of the Player* events is interoperability; any plugin that understands them should work no matter what custom stuff is at play, as long as another plugin can be written that understands that custom stuff. But PlayerDeath in particular hasn't really kept pace with the game in that respect, I think.

[Column01]

Great insight, I will update the docs accordingly.

I have plans to get into the services more in depth. I did realize after submitting it that it was misleading to say the manager handles the IO since it just registers the services and plugins that do... my brain was clouded by tiredness lol

Keep in mind my rundown of the events was before I took a deep dive to update mark2

[Column01]

Also yes, PlayerDeath is essentially non functional since large variations of the death message exist

[Column01]

@edk0 would you say what's there now is more accurate to the function of mark2?

[Column01]

Rather than keep explaining that to people we just didn't support it, but it was sometimes useful in the real world, and there was a plugin I'd give to people individually to enable the functionality.

This also explains the UserServer plugin that stores the state, did that allow for the console scrollback to be cached across reloads so the only side effect was disconnecting the clients? I've put in the docs that it would lose states across reloads but will update it if that is incorrect

[edk0]

That's correct, but vanilla mark2 doesn't let you reload services at all, so the point is somewhat moot. If you wanted to add that feature I'd suggest giving plugins a way to remember their state.

I think the description is more accurate in general, yeah.

[Column01]

Awesome, if you have time I'd appreciate it if you could correct issues in the docs and just push em. I think its important for mark2's future to be documented lest new maintainers come around

[Column01]

Added some more info to the guide if you want to read it over 😄 Current contributing guidelines

From commit: https://github.com/gsand/mark2/commit/ebfb2f553984cd028e504d5c3d0eec66149d3960

[Column01]

Added which variables each event has, gonna call this done for now. If an event has no content under it, you likely shouldn't subscribe to it, or it has no content. Use common sense 😄