Implement Event Management System and Native Geyser Extension System

[bundabrg]

Overview

This provides a Thread-safe Event Management System for Geyser. A native plugin system is also provided that can utilize the Event system through the use of 3rd party plugin jars.

Event System

Please refer to the live documentation for up to date information on how the system has been designed. This section is now outdated

An event extends GeyserEvent or GeyserCancellableEvent and can be triggered using the EventManager container on the Connector instance.

All event handlers will be run in order of priority and handlers can choose to not get cancelled events.

A handler can be defined using a lambda along with the expected event class.

Example 1:

// Load all this data into memory
myHugeData = readAllTheData();

// We want to save it all when Geyser Shuts down
eventManager.on(DisableEvent.class, (handler, event) -> {
    writeAllTheData(myHugeData);
}).build();

Example 2:

// We need to send this second packet only when we get a ResponsePacket
session.sendUpstreamPacket(somePacket);
eventManager.on(BedrockPacketReceiveEvent.class, (handler, event) -> {
    session.sendUpstreamPacket(otherPacket);
    handler.unregister(); // Unregister ourself
  
})
    .filter(ResponsePacket.class)
    .build();

Data for an event can be passed in the event object.

Events are triggered by creating a new object that inherits from GeyserEvent and calling the trigger method on the Event Manager.

Plugin System

Please refer to the live documentation for up to date information on how the system has been designed. This section is now outdated

A plugin system is also implemented to allow native Geyser Plugins to be written. This will reduce the amount of code that does not belong in the mainline by pulling it out into plugins that can optionally be used. It will also attract a community of developers who may not be interested in dealing with the low level aspects of Geyser but are happy to create useful optional features.

The plugin jar files are placed inside a plugins folder relative to the dataFolder of the appropriate bootstrap. This means relative to the jar for standalone and relative to its datafile folder for the other bootstraps. Each plugin can create its own datafolder under there as well.

We make use of a custom classloader that allows a plugin to also specify if it wishes to be part of the global namespace or not (default true). If it is global then other plugins may use its libraries and vice-versa, otherwise it is entirely independent and will not collide with other plugins.

An example plugin which runs on Geyser, Spigot and Bungeecord can be found here

Presently a class annotated with @Plugin and extending GeyserPlugin is looked for in the jar and is instantiated, becoming the plugin entrypoint. This annotation also defines all details about the plugin.

All event handlers are annotated by @Event and reflection is used to determine which event is hooked. Classes that event handers belong to must be registered with the plugin manager unless it is the main plugin class which is automatically registered.

Documentation

Online Documentation

Plugins

Please refer to Awesome Geyser Resources for a list of known plugins so far.

ToDo

• Proper Documentation
• Plugins should extend from an abstract class to provide helper methods
• Define a list of Events and where they can optimally be hooked into the code.
• Write a better example plugin perhaps one that provides custom filtering on the playerlist as it is easy to understand and by writing it help to know which events are useful.
• Will need Provide a platform independent method of retrieving the datafolder #769 merged but we implement the same functionality here anyway for the moment
• Remove edit URL's from the PDF documentation generation
• Remove need for Context in Method Event Handlers
• Individual Packet Events
• Command to show plugins loaded
• Handle cases where plugins may need to be run on specific platforms (spigot, standalone) by specifying requirements in the plugin annotation. I'm now not so sure this is needed. A plugin writer should test for this using whatever method they wish.
• Implement a delombok step so we can javadoc event fields
• Provide easy method to inject packets to Geyser
• Provide easy method to register commands not under the Geyser command (Ability to register new commands that are not under /geyser #1637)

Events Todo

• PluginMessageEvent + sending messages
• DownStreamPacketReceive
• DownStreamPacketSend
• UpstreamPacketReceive
• UpstreamPacketSend
• GeyserStartupEvent
• GeyserShutdownEvent
• PluginEnableEvent
• PluginDisableEvent
• Ping events

Optimization

• If no event handlers then we might be able to short circuit some stuff. However as events may be useful to internal geyser code in the future this may quickly become a useless optimization

[Heath123]

Well if Bungeecord has plugins, then why shouldn't Geyser? I can think of a few uses for this, at least

[andrew121410]

This is good because I wanted to make a Chest GUI to Custom Form Window. So it’s easier for bedrock users to interact. So instead of opening the Chest GUI it just opens the custom form window.

[Heath123]

This should have access to packets and be able to modify them before they get sent

[bundabrg]

I think it needs a pre and post event for both downstream and upstream. This way packets can be modified before and after geyser does it's thing.

[danielboos1]

So wait, with this am i able to run plugins for bedrock players only? Because that would be awesome

[bundabrg]

Correct, but keep in mind these are geyser plugins and not spigot plugins. So they would deal with Geyser related stuff. For now that would be modifying packets before they are received by Geyser or after its done its thing, and injecting packets towards the java server or up to the geyser client (ie the comment about chest gui would block creating the chest gui and send upstream the window creation packets).

You could also potentially communicate with spigot plugins in the downstream server but that's not yet planned as we would need some way to send messages and may require a hop through something like floodgate as a message bridge unless there is some way to send messages using the java packets (perhaps specially encoded packets that do not cause an effect on the java server like chat messages that your java plugin then suppress and captures the data from).

[Heath123]

You could also potentially communicate with spigot plugins in the downstream server but that's not yet planned as we would need some way to send messages and may require a hop through something like floodgate as a message bridge unless there is some way to send messages using the java packets (perhaps specially encoded packets that do not cause an effect on the java server like chat messages that your java plugin then suppress and captures the data from).

https://dinnerbone.com/blog/2012/01/13/minecraft-plugin-channels-messaging/

[bundabrg]

I was not aware of that. This solves a whole bunch of things and props to Dinnerbone for implementing it.

As another suggested feature for this branch I'd like to propose single shot events with lambdas which would be super useful for co-ordinating stuff that needs to be done in an ordered fashion without needing the whole event method setup.

For example something like:

session.sendDownstream(something);
pluginManager.when(DownstreamPacketReceivedEvent.class, (event) -> {
  if (event.getPacket().getId() == -1 ) { do something and cancel event }
});

I've not thought much more about it than that but it would temporarily add it to the list of events being triggered and can self cancel itself out when its fulfilled. Allows putting the code closer to where its relevant in the code.

[bundabrg]

I've expanded that thought further by moving the event system into its own system which will be useful for within Geyser as well. The Event system now becomes useful for Geyser itself to utilize and can possibly clean up things by placing code closer to where it is useful.

The plugin system now just uses the EventSystem by allowing 3rd party jars to be dropped into the Geyser plugins folder and provides some convenience through the use of annotations. Plugins also now extend from GeyserPlugin as a requirement.

This means that as well as the plugin system described in this topic one can also perform event hooking through the use of lambdas and through the magic of Generic and TypeVariables the runnable will have the correct event type.

Example 1:

// Load all this data into memory
myHugeData = readAllTheData();

// We want to save it all when Geyser Shuts down
eventManager.on(DisableEvent.class, (ctx, event) -> {
    writeAllTheData(myHugeData);
});

Example 2:

// We need to send this second packet only when we get a respose 
session.sendUpstreamPacket(somePacket);
eventManager.on(BedrockPacketReceiveEvent.class, (ctx, event) -> {
    if (event.getPacket() instance of ResponsePacket) {
        session.sendUpstreamPacket(otherPacket);
        ctx.unregister(); // Unregister ourself
    }
});

[bundabrg]

With regard to the plugin message channels this will simply need a sendMessage method on the session likely and a PluginMessageReceive event for receiving messages. It should just "work" then with communicating with server side plugins.

[bundabrg]

The EventManager will now allow classes to be registered and all methods of the class annotated with @event will be added as event handlers making them first class citizens of EventManager.

PluginManager provides a proxy to some of the registration functions in EventManager directly in GeyserPlugin to allow it to track EventHandlers that belong to a plugin but otherwise is now only responsible for purely plugin related things.

[bundabrg]

As this would require good documentation I've added both some initial documentation as well as a github action to automatically build + deploy both an online and offline documentation. For now it triggers when pushed to this branch and deploys to my pages repo and the 'edit' button in the docs will not work as it assumes it's editing master. The idea is the dev who is responsible for adding an event (or other feature) will also add to the documentation for it and the branch is not merged till that happens.

Online Documentation: https://bundabrg.github.io/Geyser/
Offline Documentation: https://bundabrg.github.io/Geyser/pdf/documentation.pdf

[bundabrg]

The last commit added support for sending PluginMessages downstream as well as an event that triggers when receiving a channel message.

However its important to note here:

• They are ClientPluginMessages. This is slightly different to ServerPluginMessages which are done from Bukkit servers for example to Bungeecord.
• Plugin writers of Bukkit plugins CANNOT trust the plugin channel as this can be sent from a java client as well. It may be worth providing a trusted channel that signs the messages similar to how floodgate works.
• In the same vein, accessing ServerPluginMessage channels from Geyser would need to bounce through a relay that takes trusted ClientPluginMessages, sends the appropriate ServerPluginMessage then responds back. This is all out of scope of this PR.

Note: If geyser is running as a bukkit plugin then it implicitly is able to send trusted messages. So perhaps a method on the bootstrap to send a trusted message, and those without the direct facility must then establish it through a relay plugin.

The relay plugin could also technically provide some missing things from non-bukkit Geyser instances. For example being able to query chunks etc, however I'd recommend that the relationship be optional and still work without else vanilla servers will not work.

[bundabrg]

I have put together a plugin that is a Geyser plugin, Spigot plugin and Bungeecord plugin all rolled into one. When added to any of these services it will merely send ping messages to a plugin message channel and report any that it see's. If you were to put one in all 3 then you should see ping messages from the other two participating servers in your logs.

This provides a simple example of how to create a plugin supporting all 3 servers and demonstrates the plugin message channel in use.

Source: https://github.com/bundabrg/GeyserLink
Release: https://github.com/bundabrg/GeyserLink/releases

[ghost]

Can you please implement plugins api as annotation processor like how velocity does? It's more easy for devs.

[Camotoy]

This should throw an exception instead of silently returning.

[funniray]

Just wondering, is there any reason why this hasn't been merged yet? Being able to handle custom packets for bedrock specific features is very important for what I need to do.

[Hellohi3654]

Just wondering, is there any reason why this hasn't been merged yet? Being able to handle custom packets for bedrock specific features is very important for what I need to do.

I doubt this will be merged anytime soon
One reason this hasn't been merged is because of all the conflicts since Bundabrg seems to have stopped merging the master branch into his plugins branch

Also this will need alot of fine tuning and testing before it's ready to be merged into master

[bundabrg]

Just wondering, is there any reason why this hasn't been merged yet? Being able to handle custom packets for bedrock specific features is very important for what I need to do.

I've updated it but I suspect Geyser itself may move a different direction with the API development but I don't believe its anywhere near ready to handle the Education Translator extension so I'll keep trying to keep this updated whilst I maintain that extension.

[Konicai]

Is LOW suppose to be 40?

[bundabrg]

Yes it is. Nice catch.

[Camotoy]

We're going to close this in favor of a new extension system actively in development. With that being said, we're incredibly grateful for the work that was done here; it was with the development here that the very idea of the extension name was created to differ from plugin systems of implementations. Thank you.