297
edits
Changes
Add sections for cancellable and result-having events
An '''event''' is a special object that is fired on an '''event bus''' to inform registered listeners about some type of action or state. This is the primary way by which Forge allows mods to hook into vanilla and game behavior; Forge has an array of different events which are fired when different actions happen within the game, and mods may act upon receiving these events.
An '''event''' is a special object that is fired on an '''event bus''' to inform registered listeners about some type of action or state. This is the primary way by which Forge allows mods to hook into vanilla and game behavior; Forge has an array of different events which are fired when different actions happen within the game, and mods may act upon receiving these events.
= Cancellable Events =
An event may be marked as '''cancellable''', which allows event listeners to cancel the event.
A cancellable event may be cancelled by using <code>Event#setCanceled(true)</code>. Attempting to call this method on a non-cancellable event will result in a <code>UnsupportedOperationException</code>. A cancelled event behaves similarly to a regular noncancelled event, with one main difference: an event listener will not receieve cancelled events unless they are explicitly registered to listen for cancelled events.
To mark an event as cancellable, the event class should be annotated with <code>@Cancelable</code>. This will automatically make <code>Event#isCancelable()</code> return <code>true</code>. Modders may check if an event has a result through the presence of the annotation or by calling the given method.
= Events with Results =
An event may '''have a result''', which is an enum of <code>Event.Result</code>.
The <code>Event.Result</code> enum has three values: <code>ALLOW</code>, <code>DEFAULT</code>, and <code>DENY</code>. The meaning of these result values is entirely dependent on the event itself.
An event's current result can be retrieved through <code>Event#getResult()</code>. The result on an event can be set through <code>Event#setResult(Event.Result)</code>. You can set the result for an event which is not marked as having a result, however this will cause nothing to happen if the event does not use the result value.
To mark an event as having a result, the event class should be annotated with <code>@Event.HasResult</code>. This will automatically make <code>Event#hasResult</code> return <code>true</code>. Modders may check if an event has a result through the presence of the annotation or by calling the given method.
<br>
Forge uses an event bus that allows mods to intercept events from various vanilla and mod behaviors.
Forge uses an event bus that allows mods to intercept events from various vanilla and mod behaviors.