API: Event System

Relevant source files

The following files were used as context for generating this wiki page:

• API/src/main/java/xyz/xreatlabs/nexauth/api/event/EventProvider.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/AuthenticatedEvent.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/PasswordChangeEvent.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/event/CancellableEvent.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/event/Event.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/event/AuthenticEventProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/event/AuthenticPlayerBasedEvent.java

The NexAuth Event System provides a powerful mechanism for developers to hook into the authentication lifecycle. It allows other plugins to listen for specific actions, such as a player authenticating or changing their password, and to react accordingly. This system is designed to be extensible, enabling deep integration with other server plugins. The core of the system is a publish-subscribe model managed by the EventProvider.

The system is built around a few key interfaces: Event, which is the base for all events; PlayerBasedEvent, for events related to a specific player; and CancellableEvent, for actions that can be prevented by a listener. By subscribing to these events, developers can add custom logic, modify outcomes, or gather information about the authentication process.

Core Architecture

The event system is composed of several key interfaces and a central provider that manages event listeners and dispatches events.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/EventProvider.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/event/AuthenticEventProvider.java, API/src/main/java/xyz/xreatlabs/nexauth/api/event/Event.java

Event Hierarchy

All events in NexAuth inherit from the base Event<P, S> interface. This ensures that every event provides access to the NexAuthPlugin instance and the PlatformHandle. Many events also extend PlayerBasedEvent if they are related to a specific player, or implement CancellableEvent if the action they represent can be stopped.

The diagram below illustrates the inheritance structure of the core event interfaces and some concrete event classes.

EventProvider

The EventProvider is the central component for managing events. It is responsible for registering listeners (subscribers) and dispatching events to them. The concrete implementation, AuthenticEventProvider, uses a Map to store a Set of Consumer handlers for each EventType.

Key methods of EventProvider:

• subscribe(EventType<P, S, E> type, Consumer<E> handler): Registers a new listener for a specific event type.
• unsubscribe(Consumer<? extends Event<P, S>> handler): Removes a listener.
• fire(EventType<P, S, E> type, E event): Dispatches an event to all registered listeners for its type.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/EventProvider.java:17-38, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/event/AuthenticEventProvider.java:19-49

Event Handling Flow

Interacting with the event system follows a clear lifecycle: a developer subscribes to an event, NexAuth fires that event when a relevant action occurs, and the developer's handler code is executed.

Subscribing to and Firing an Event

The following sequence diagram shows how an external plugin would subscribe to an AuthenticatedEvent and how NexAuth would later fire it, triggering the subscriber's logic.

This diagram illustrates the decoupling between the core authentication logic and the custom actions performed by other plugins.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/EventProvider.java:26-38, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/event/AuthenticEventProvider.java:32-42

Cancellable Events

Certain events implement the CancellableEvent interface, allowing subscribers to prevent the associated action from completing. A common use case is validating a new password during a PasswordChangeEvent.

The flow for a cancellable event is as follows:

1. NexAuth fires a cancellable event (e.g., PasswordChangeEvent).
2. A subscriber receives the event.
3. The subscriber's logic evaluates a condition (e.g., password strength).
4. If the condition is not met, the subscriber calls event.setCancelled(true).
5. After all listeners have been called, NexAuth checks event.isCancelled().
6. If the event is cancelled, NexAuth aborts the action (e.g., does not save the new password).

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/CancellableEvent.java:11-23, API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/PasswordChangeEvent.java:13-14

Key Event Types

NexAuth provides a variety of events to hook into different parts of the authentication process. The following table summarizes some of the most important ones.

Event Class	Base Interfaces	Description	Key Data
AuthenticatedEvent	PlayerBasedEvent	Fired when a player successfully authenticates.	AuthenticationReason
PasswordChangeEvent	PlayerBasedEvent, CancellableEvent	Fired when a player attempts to change their password. Can be cancelled.	HashedPassword (the new password)

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/AuthenticatedEvent.java, API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/PasswordChangeEvent.java

AuthenticatedEvent

This event is triggered after a player has successfully logged in, registered, or been authenticated via a session. It provides the reason for the authentication through the getReason() method, which returns an AuthenticationReason enum.

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/AuthenticatedEvent.java:11-21, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/event/events/AuthenticAuthenticatedEvent.java:13-26

PasswordChangeEvent

This event is fired just before a player's password is changed in the database. It is cancellable, allowing plugins to enforce custom password policies (e.g., complexity, length). The event contains the new, hashed password, accessible via getNewPassword().

Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/event/events/PasswordChangeEvent.java:13-22

Summary

The NexAuth Event System is a fundamental feature for extending the plugin's functionality. It provides a robust, decoupled way for other plugins to interact with the authentication flow. By subscribing to events, developers can implement custom logic, integrate with other systems, and even modify or cancel core authentication actions, making NexAuth a highly adaptable solution.