From dfcb10cdaf4f3fe7b9365f2358560bb35ce55718 Mon Sep 17 00:00:00 2001 From: Mose Date: Mon, 24 Jul 2023 11:48:37 +0100 Subject: [PATCH] Events (#978) --- source/plugin/event/causes.rst | 8 ++++---- source/plugin/event/custom.rst | 21 +++++++++++---------- source/plugin/event/filters.rst | 8 ++------ source/plugin/event/listeners.rst | 27 ++++++++++++++++----------- 4 files changed, 33 insertions(+), 31 deletions(-) diff --git a/source/plugin/event/causes.rst b/source/plugin/event/causes.rst index 4d42ed163ca..90c812810df 100644 --- a/source/plugin/event/causes.rst +++ b/source/plugin/event/causes.rst @@ -9,8 +9,8 @@ Event Causes org.spongepowered.api.event.Event org.spongepowered.api.event.block.ChangeBlockEvent org.spongepowered.api.event.block.ChangeBlockEvent.All - org.spongepowered.api.event.cause.Cause - org.spongepowered.api.event.cause.Cause.Builder + org.spongepowered.api.event.Cause + org.spongepowered.api.event.Cause.Builder org.spongepowered.api.event.cause.EventContext org.spongepowered.api.event.cause.EventContext.Builder org.spongepowered.api.event.cause.EventContextKey @@ -46,7 +46,7 @@ The ``Cause`` object contains two distinct sets of information, the cause stack order, they are all equally important. As an example, if a sheep owned by a player eats some grass, the most direct cause of this is the sheep. The -player would be in the ``EventContext`` as the :javadoc:`EventContextKeys#OWNER`, giving event consumers +player would be in the ``EventContext`` as the :javadoc:`EventContextKeys#PLAYER`, giving event consumers that additional information about how the event has come about, but would not necessarily be within the direct cause itself. @@ -116,7 +116,7 @@ Unlike the cause stack, which makes no guarantees as to the objects contained wi @Listener public void onGrow(ChangeBlockEvent.All event) { - Optional notifier = event.getCause().getContext().get(EventContextKeys.NOTIFIER); + Optional notifier = event.cause().context().get(EventContextKeys.NOTIFIER); } This example makes use of :javadoc:`EventContext#get(EventContextKey)` which can be used to retrieve the expected object diff --git a/source/plugin/event/custom.rst b/source/plugin/event/custom.rst index a012f7f8e40..5b7ce3685d5 100644 --- a/source/plugin/event/custom.rst +++ b/source/plugin/event/custom.rst @@ -6,15 +6,17 @@ Custom Events org.spongepowered.api.entity.living.player.server.ServerPlayer org.spongepowered.api.event.Cancellable org.spongepowered.api.event.Event - org.spongepowered.api.event.cause.Cause + org.spongepowered.api.event.Cause org.spongepowered.api.event.entity.AffectEntityEvent org.spongepowered.api.event.impl.AbstractEvent You can write your own event classes and dispatch those events using the method described above. An event class must -extend the :javadoc:`AbstractEvent` class, thus implementing the :javadoc:`Event` interface. Depending on the exact -nature of the event, more interfaces should be implemented, like :javadoc:`Cancellable` for events that can be -cancelled by a listener or interfaces like :javadoc:`AffectEntityEvent` clarifying what sort of object is affected by -your event. +extend the :javadoc:`Event` class. Depending on the exact nature of the event, more interfaces should be implemented, +like :javadoc:`Cancellable` for events that can be cancelled by a listener or interfaces like +:javadoc:`AffectEntityEvent` clarifying what sort of object is affected by your event. + +.. tip:: + You can extend :javadoc:`AbstractEvent` for common methods to be implementated for you Example: Custom Event Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -31,7 +33,7 @@ would probably be mentioned that the root cause is generally an object of the fi import org.spongepowered.api.entity.living.player.server.ServerPlayer; import org.spongepowered.api.event.Cancellable; - import org.spongepowered.api.event.cause.Cause; + import org.spongepowered.api.event.Cause; import org.spongepowered.api.event.impl.AbstractEvent; public class PlayerMutationEvent extends AbstractEvent implements Cancellable { @@ -75,7 +77,6 @@ would probably be mentioned that the root cause is generally an object of the fi public Cause cause() { return this.cause; } - } Example: Fire Custom Event @@ -83,9 +84,9 @@ Example: Fire Custom Event .. code-block:: java - import org.spongepowered.api.event.cause.Cause; - import org.spongepowered.api.event.cause.EventContext; - import org.spongepowered.api.event.cause.EventContextKeys; + import org.spongepowered.api.event.Cause; + import org.spongepowered.api.event.EventContext; + import org.spongepowered.api.event.EventContextKeys; import org.spongepowered.api.Sponge; PluginContainer plugin = ...; diff --git a/source/plugin/event/filters.rst b/source/plugin/event/filters.rst index cda51cd6d34..52b4a0eeb95 100644 --- a/source/plugin/event/filters.rst +++ b/source/plugin/event/filters.rst @@ -2,15 +2,11 @@ Event Filters ============= -.. warning:: - These docs were written for SpongeAPI 7 and are likely out of date. - `If you feel like you can help update them, please submit a PR! `__ - .. javadoc-import:: org.spongepowered.api.event.Listener org.spongepowered.api.event.block.InteractBlockEvent.Primary org.spongepowered.api.event.block.InteractBlockEvent.Secondary - org.spongepowered.api.event.cause.Cause + org.spongepowered.api.event.Cause org.spongepowered.api.event.entity.AffectEntityEvent org.spongepowered.api.event.entity.DamageEntityEvent org.spongepowered.api.event.entity.DestructEntityEvent @@ -57,7 +53,7 @@ For example: This listener would normally be called for all events extending InteractBlockEvent. However, the :javadoc:`Exclude` annotationte will prevent your listener from being called for the :javadoc:`InteractBlockEvent.Primary` event (leaving -just the :javadoc:`InteractBlockEvent.Secondary` event). +just the :javadoc:`InteractBlockEvent.Secondary` extended events). An example with :javadoc:`Include` could be: diff --git a/source/plugin/event/listeners.rst b/source/plugin/event/listeners.rst index b198906a7a6..188762fa247 100644 --- a/source/plugin/event/listeners.rst +++ b/source/plugin/event/listeners.rst @@ -9,9 +9,9 @@ Event Listeners org.spongepowered.api.event.Order org.spongepowered.api.event.block.ChangeBlockEvent org.spongepowered.api.event.block.ChangeBlockEvent.All - org.spongepowered.api.event.cause.Cause - org.spongepowered.api.event.lifecycle.GameRefreshEvent - org.spongepowered.api.plugin.Plugin + org.spongepowered.api.event.lifecycle.RefreshGameEvent + org.spongepowered.plugin.PluginContainer + org.spongepowered.plugin.builtin.jvm.Plugin java.lang.Object In order to listen for an event, an event listener must be registered. This is done by making a method with any name, @@ -46,7 +46,7 @@ Registering and Unregistering Event Listeners ============================================= To register event listeners annotated by ``@Listener`` that are not in the main plugin class, you can use -:javadoc:`EventManager#registerListeners(Object, Object)`, which accepts a reference to the plugin and an instance of +:javadoc:`EventManager#registerListeners(PluginContainer, Object)`, which accepts a reference to the plugin and an instance of the class containing the event listeners. **Example: Registering Event Listeners in Other Classes** @@ -63,7 +63,7 @@ the class containing the event listeners. } } - Sponge.getEventManager().registerListeners(this, new ExampleListener()); + Sponge.eventManager().registerListeners(this, new ExampleListener()); @@ -98,7 +98,12 @@ before other server modifications. .. code-block:: java EventListener listener = new ExampleListener(); - Sponge.getEventManager().registerListener(this, ChangeBlockEvent.All.class, listener); + EventListenerRegistration registeration = EventListenerRegistration + .builder(ChangeBlockEvent.All.class) + .listener(listener) + .plugin(pluginContainer) + .build(); + Sponge.eventManager().registerListener(registeration); .. tip:: @@ -125,7 +130,7 @@ event listeners, including those registered with ``@Listener`` annotations. .. code-block:: java PluginContainer plugin = ...; - Sponge.getEventManager().unregisterPluginListeners(plugin); + Sponge.eventManager().unregisterListeners(plugin); .. _about_listener: @@ -144,17 +149,17 @@ cancellable and has been cancelled (such as by another plugin). .. _game-reload: -GameRefreshEvent +RefreshGameEvent ~~~~~~~~~~~~~~~~ To prevent all plugins providing their own reload commands, Sponge provides a built-in callback for plugins to listen to, and when executed, perform any refresh actions. What constitutes as a 'refresh action' is purely up to the -plugin to decide. The :javadoc:`GameRefreshEvent` will fire when a player executes the +plugin to decide. The :javadoc:`RefreshGameEvent` will fire when a player executes the ``/sponge plugins refresh`` command. The event is not necessarily limited to reloading configuration. .. code-block:: java - import org.spongepowered.api.event.lifecycle.GameRefreshEvent; + import org.spongepowered.api.event.lifecycle.RefreshGameEvent; @Listener public void refresh(GameRefreshEvent event) { @@ -173,6 +178,6 @@ You can fire events using the event bus (:javadoc:`EventManager`): .. code-block:: java - boolean cancelled = Sponge.getEventManager().post(theEventObject); + boolean cancelled = Sponge.eventManager().post(theEventObject); The method returns ``true`` if the event was cancelled, ``false`` if not.