PMMO Event Trigger System

Event Triggers are an extension of PMMO and the Forge Event system. They allow you to register event logic just as you would for a Forge event, but within Project MMO. The primary goal of this system is to expose pmmo's events to addons and allow some control back to the event they came from.

Advantages of Event Triggers

Event triggers are different than forge events for two reasons. The first is that they execute only if any PMMO prerequisites have been met. for example if a damage event triggers and the player does not have the requirement for that weapon to do so, the event is cancelled and any registered event triggers are never called. The second benefit is the ability to apply special logic within a PMMO event that can affect the outcome of said event. Because this logic is running within the PMMO event, you do not have to worry about prioritization of mod call order to ensure your changes are reflected in PMMO's logic. You also have the ability to pass information back to the event which impacts subsequent logic such as perks, and awarded experience.

Registering a listener

The event system works by calling harmonised.pmmo.api.APIUtils.registerListener() after mod initialization. Server loading is the safest place to call, but there is no restriction on when a listener can be registered. This is no way to unregister though. At this time, all listeners are server-side. the method takes three parameters

ResourceLocation listenerID; // a custom ID used for debuggin
EventType eventType; // The specific PMMO event this is to be called within
BiFunction<? super Event, CompoundTag, CompoundTag> executeOnTrigger; // the actual logic being executed.

The executeOnTrigger Function

When an event trigger is called, this function is called. It is passed the event that pmmo was listening to and a CompoundTag containing information PMMO might give to event triggers for additional context. This is an ever evolving feature and suggestions and requests are highly encouraged. Lastly it must output a compound tag. This tag can be empty, but certain events look for outputs to modify their logic.

Events with Inputs

WIP

Events with Outputs

WIP

Cancellable Events

Any event which has the ability to be cancelled can be done so from an event Trigger. To notify PMMO that you would like to cancel the event, add an element that uses APIUtils.IS_CANCELLED as a key in your output CompoundTag. Note that PMMO is not looking for a value, only the existence of the key. do not pass "is_cancelled":false back to PMMO, it will be treated as true. there are also DENY_ITEM_USE and DENY_BLOCK_USE which are used in the player interact events and allow you to specifically cancel an aspect of the interaction, but not the entire event. These work the same as the event cancellation in that only the presence of the key matters.

Modifying XP Awards

Event Triggers have the ability to supply an award output to the event instance for which it was triggered.

To provide an award map, include a tag in your return tag using the key APIUtils.SERIALIZED_AWARD_MAP and the value using APIUtils.serializeAwardMap(yourMap) where "yourMap" is an instance of Map<String, Long> representing a map of skills and xp values.