Exclude CODEOWNERS from language statistics

Co-authored-by: Wolfdv1 <Wolfdv1@github.com>

.gitattributes

@@ -0,0 +1,6 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# These are explicitly windows files and should use crlf
+*.bat           text eol=crlf
+.gitea/CODEOWNERS linguist-detectable=false

.gitea/CODEOWNERS

@@ -0,0 +1,3 @@
+# Pull requests request review from the eligible staff team(s).
+# One approval from either an Admin or Developer satisfies branch protection.
+*   @trueog/Admins @trueog/Developers

.github/FUNDING.yml

@@ -1,2 +0,0 @@
-github: lucko
-patreon: luckdev

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,40 +0,0 @@
----
-name: 🐛 ​ Bug report
-about: Report an issue or problem with the way LuckPerms is functioning.
-title: ''
-labels: 'type: issue'
-assignees: ''
-
----
-
-<!-- Before going any further, please check to see if your problem is fixed by updating to a newer version. The latest development builds can be obtained from https://luckperms.net/download -->
-
-### Description
-<!-- Please provide a short description of the issue in the space below. -->
-
-
-### Reproduction steps
-<!-- Please provide a clear list of steps we should follow in order to reproduce your issue in the space below. -->
-
-1. Open the config.yml file and set example to true.
-2. Restart the server
-3. Run /lp user example permission set x from the console
-4. See error
-
-
-### Expected behaviour
-<!-- Please provide a description of what you expected to happen. -->
-
-
-### Environment details
-<!-- Please provide details of your server environment in the space below. -->
-
-* Server type/version: `ExampleSpigot` running version `1.12.2` build `???`
-* LuckPerms version: `v???`
-
-<!-- If you think it would be helpful, please also include a "pastebin" of any relevant config files or log output. You should use https://gist.github.com/ to upload, then include the link below. -->
-
-
-### Any other relevant details
-<!-- Please include any other relevant details in the space below. -->
-

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: 💬 ​ Ask a question
-    url: https://discord.gg/luckperms
-    about: We use Discord to provide support for the project. If you have a question, need help, or aren't sure if you've found a bug or not, please come and talk to us there!

.github/ISSUE_TEMPLATE/suggestion.md

@@ -1,16 +0,0 @@
----
-name: 💡 ​ Suggestion
-about: Suggest an idea for an improvement or change to LuckPerms.
-title: ''
-labels: 'type: suggestion'
-assignees: ''
-
----
-
-### Description
-<!-- Please provide a short description of the suggestion in the space below. -->
-
-
-### Proposed behaviour
-<!-- Please provide a short explanation of how the feature should work / be changed, and how this will effect the project. -->
-

.gitignore

@@ -1,3 +1,6 @@
+### LuckPerms Standalone ###
+standalone/loader/data/
+
 ### Gradle & IntelliJ ###
 .gradle/
 /.idea/

CONTRIBUTING.md

@@ -1,26 +0,0 @@
-### :speech_balloon: Looking for support?
-
-Details about support for the project can be found [here, on the Wiki Homepage](https://github.com/lucko/LuckPerms/wiki#support).
-
-### :bug: Reporting bugs?
-
-Before reporting a bug or issue, please make sure that the issue is actually being caused by or related to LuckPerms. We get a lot of reports which are caused by other software - please double check!
-
-If you're unsure, feel free to ask using the above resources BEFORE making a report.
-
-Bugs or issues should be reported using the [GitHub Issues tab](https://github.com/lucko/LuckPerms/issues).
-
-### :pencil: Want to contribute code?
-#### Pull Requests
-If you make any changes or improvements to the plugin which you think would be beneficial to others, please consider making a pull request to merge your changes back into the upstream project. (especially if your changes are bug fixes!)
-
-LuckPerms loosely follows the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Generally, try to copy the style of code found in the class you're editing. 
-
-If you're considering submitting a substantial pull request, please open an issue so we can discuss the change before starting work on the contribution. Most pull requests are happily accepted, but larger changes may have an inpact on the maintainability of the project, and require more consideration. 
-
-#### Project Layout
-The project is split up into a few seperate modules.
-
-* **API** - The public, semantically versioned API used by other plugins wishing to integrate with and retrieve data from LuckPerms. This module (for the most part) does not contain any implementation itself, and is provided by the plugin.
-* **Common** - The common module contains most of the code which implements the respective LuckPerms plugins. This abstract module reduces duplicated code throughout the project.
-* **Bukkit, BungeeCord, Sponge, Nukkit & Velocity** - Each use the common module to implement plugins on the respective server platforms.

README.md

@@ -1,12 +1,14 @@
-![alt text](https://i.imgur.com/ToguFkQ.png "Banner")
+![](https://raw.githubusercontent.com/LuckPerms/branding/master/banner/banner.png "Banner")
 # LuckPerms
 [![Build Status](https://ci.lucko.me/job/LuckPerms/badge/icon)](https://ci.lucko.me/job/LuckPerms/)
 [![javadoc](https://javadoc.io/badge2/net.luckperms/api/javadoc.svg)](https://javadoc.io/doc/net.luckperms/api)
 [![Maven Central](https://img.shields.io/maven-metadata/v/https/repo1.maven.org/maven2/net/luckperms/api/maven-metadata.xml.svg?label=maven%20central&colorB=brightgreen)](https://search.maven.org/artifact/net.luckperms/api)
-[![Discord](https://img.shields.io/discord/241667244927483904.svg?logo=discord&label=)](https://discord.gg/luckperms)
+[![Discord](https://img.shields.io/discord/241667244927483904.svg?label=discord&logo=discord)](https://discord.gg/luckperms)
 
 LuckPerms is a permissions plugin for Minecraft servers. It allows server admins to control what features players can use by creating groups and assigning permissions.
 
+The latest downloads, wiki & other useful links can be found on the project homepage at [luckperms.net](https://luckperms.net/).
+
 It is:
 
 * **fast** - written with performance and scalability in mind.
@@ -16,26 +18,29 @@ It is:
 * **extensive** - a plethora of customization options and settings which can be changed to suit your server.
 * **free** - available for download and usage at no cost, and permissively licensed so it can remain free forever.
 
-For more information, see the wiki article on [Why LuckPerms?](https://github.com/lucko/LuckPerms/wiki/Why-LuckPerms)
-
-## Useful Links
-The latest downloads & other useful links can be found on the project homepage at [luckperms.net](https://luckperms.net/).
+For more information, see the wiki article on [Why LuckPerms?](https://luckperms.net/wiki/Why-LuckPerms)
 
 ## Building
 LuckPerms uses Gradle to handle dependencies & building.
 
 #### Requirements
-* Java 8 JDK or newer
+* Java 21 JDK or newer
 * Git
 
 #### Compiling from source
 ```sh
-git clone https://github.com/lucko/LuckPerms.git
+git clone https://github.com/LuckPerms/LuckPerms.git
 cd LuckPerms/
 ./gradlew build
 ```
 
-You can find the output jars in the `build/libs` directories.
+You can find the output jars in the `loader/build/libs` or `build/libs` directories.
+
+## Tests
+There are some automated tests which run during each build.
+
+* Unit tests are defined in [`common/src/test`](https://github.com/LuckPerms/LuckPerms/tree/master/common/src/test)
+* Integration tests are defined in [`standalone/src/test`](https://github.com/LuckPerms/LuckPerms/tree/master/standalone/src/test).
 
 ## Contributing
 #### Pull Requests
@@ -48,7 +53,7 @@ The project is split up into a few separate modules.
 
 * **API** - The public, semantically versioned API used by other plugins wishing to integrate with and retrieve data from LuckPerms. This module (for the most part) does not contain any implementation itself, and is provided by the plugin.
 * **Common** - The common module contains most of the code which implements the respective LuckPerms plugins. This abstract module reduces duplicated code throughout the project.
-* **Bukkit, BungeeCord, Sponge, Nukkit & Velocity** - Each use the common module to implement plugins on the respective server platforms.
+* **Bukkit, BungeeCord, Fabric, Forge, Nukkit, Sponge & Velocity** - Each use the common module to implement plugins on the respective server platforms.
 
 ## License
-LuckPerms is licensed under the permissive MIT license. Please see [`LICENSE.txt`](https://github.com/lucko/LuckPerms/blob/master/LICENSE.txt) for more info.
+LuckPerms is licensed under the permissive MIT license. Please see [`LICENSE.txt`](https://github.com/LuckPerms/LuckPerms/blob/master/LICENSE.txt) for more info.

api/build.gradle

@@ -1,99 +0,0 @@
-group = 'net.luckperms'
-project.version = '5.2'
-
-dependencies {
-    compileOnly 'org.checkerframework:checker-qual:2.5.5'
-}
-
-// Only used occasionally for deployment - not needed for normal builds.
-/*
-if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePassword')) {
-    apply plugin: 'signing'
-
-    javadoc {
-        title = 'LuckPerms API (v' + project.ext.apiVersion + ')'
-        options.encoding = 'UTF-8'
-        options.charSet = 'UTF-8'
-        options.links(
-                'https://docs.oracle.com/javase/8/docs/api/'
-        )
-        options.addStringOption('Xdoclint:none', '-quiet')
-    }
-
-    task javadocJar(type: Jar, dependsOn: javadoc) {
-        classifier 'javadoc'
-        from javadoc.destinationDir
-    }
-
-    task sourcesJar(type: Jar) {
-        classifier 'sources'
-        from sourceSets.main.allSource
-    }
-
-    artifacts {
-        archives javadocJar
-        archives sourcesJar
-    }
-
-    signing {
-        useGpgCmd()
-        sign configurations.archives
-    }
-
-    uploadArchives {
-        repositories {
-            mavenDeployer {
-                beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) }
-
-                repository(url: 'https://oss.sonatype.org/service/local/staging/deploy/maven2/') {
-                    authentication(userName: sonatypeUsername, password: sonatypePassword)
-                }
-
-                snapshotRepository(url: 'https://oss.sonatype.org/content/repositories/snapshots/') {
-                    authentication(userName: sonatypeUsername, password: sonatypePassword)
-                }
-
-                pom {
-                    project {
-                        name 'LuckPerms API'
-                        description 'A permissions plugin for Minecraft servers.'
-                        url 'https://luckperms.net'
-
-                        licenses {
-                            license {
-                                name 'MIT'
-                                url 'https://opensource.org/licenses/MIT'
-                            }
-                        }
-
-                        developers {
-                            developer {
-                                id 'lucko'
-                                name 'Luck'
-                                url 'https://lucko.me'
-                                email 'git@lucko.me'
-                            }
-                        }
-
-                        scm {
-                            connection 'scm:git:https://github.com/lucko/LuckPerms.git'
-                            developerConnection 'scm:git:git@github.com:lucko/LuckPerms.git'
-                            url 'https://github.com/lucko/LuckPerms'
-                        }
-
-                        ciManagement {
-                            system 'Jenkins'
-                            url 'https://ci.lucko.me/job/LuckPerms'
-                        }
-
-                        issueManagement {
-                            system 'GitHub'
-                            url 'https://github.com/lucko/LuckPerms/issues'
-                        }
-                    }
-                }
-            }
-        }
-    }
-}
-*/

api/javadoc/overview.html

@@ -0,0 +1,20 @@
+<body>
+<p>
+    LuckPerms is a permissions manager for Minecraft servers. It allows server admins to control what
+    features players can use by creating groups and assigning permissions.
+</p>
+<h4>Useful Links</h4>
+<ul>
+    <li><a target="_top" href="https://luckperms.net">Project Website</a></li>
+    <li><a target="_top" href="https://luckperms.net/wiki/Developer-API">Wiki - API Introduction</a></li>
+    <li><a target="_top" href="https://luckperms.net/wiki/Developer-API-Usage">Wiki - API Usage</a></li>
+    <li><a target="_top" href="https://github.com/LuckPerms/LuckPerms">Source Code</a></li>
+</ul>
+<h4>Maven</h4>
+<p>
+    The API artifact is deployed to Maven Central with
+    <a target="_top" href="https://search.maven.org/artifact/net.luckperms/api">
+        group id: <b><code>net.luckperms</code></b>, artifact id: <b><code>api</code></b>.
+    </a>
+</p>
+</body>

api/src/main/java/net/luckperms/api/LuckPerms.java

@@ -26,6 +26,7 @@
 package net.luckperms.api;
 
 import net.luckperms.api.actionlog.ActionLogger;
+import net.luckperms.api.actionlog.filter.ActionFilterFactory;
 import net.luckperms.api.context.ContextCalculator;
 import net.luckperms.api.context.ContextManager;
 import net.luckperms.api.event.EventBus;
@@ -40,14 +41,15 @@ import net.luckperms.api.model.user.User;
 import net.luckperms.api.model.user.UserManager;
 import net.luckperms.api.node.NodeBuilderRegistry;
 import net.luckperms.api.node.matcher.NodeMatcherFactory;
+import net.luckperms.api.platform.Health;
 import net.luckperms.api.platform.Platform;
 import net.luckperms.api.platform.PlayerAdapter;
 import net.luckperms.api.platform.PluginMetadata;
 import net.luckperms.api.query.QueryOptionsRegistry;
 import net.luckperms.api.track.Track;
 import net.luckperms.api.track.TrackManager;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
@@ -131,6 +133,7 @@ public interface LuckPerms {
      * <li>{@code org.bukkit.entity.Player}</li>
      * <li>{@code net.md_5.bungee.api.connection.ProxiedPlayer}</li>
      * <li>{@code org.spongepowered.api/entity.living.player.Player}</li>
+     * <li>{@code net.minecraft.server.network.ServerPlayerEntity} (Fabric)</li>
      * <li>{@code cn.nukkit.Player}</li>
      * <li>{@code com.velocitypowered.api.proxy.Player}</li>
      * </ul>
@@ -194,21 +197,6 @@ public interface LuckPerms {
      */
     @NonNull ContextManager getContextManager();
 
-    /**
-     * Gets the {@link NodeBuilderRegistry}.
-     *
-     * @return the node builder registry
-     */
-    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
-
-    /**
-     * Gets the {@link QueryOptionsRegistry}.
-     *
-     * @return the query options registry
-     * @since 5.1
-     */
-    @NonNull QueryOptionsRegistry getQueryOptionsRegistry();
-
     /**
      * Gets the {@link MetaStackFactory}.
      *
@@ -220,14 +208,6 @@ public interface LuckPerms {
      */
     @NonNull MetaStackFactory getMetaStackFactory();
 
-    /**
-     * Gets the {@link NodeMatcherFactory}.
-     *
-     * @return the node matcher factory
-     * @since 5.1
-     */
-    @NonNull NodeMatcherFactory getNodeMatcherFactory();
-
     /**
      * Schedules the execution of an update task, and returns an encapsulation
      * of the task as a {@link CompletableFuture}.
@@ -241,6 +221,17 @@ public interface LuckPerms {
      */
     @NonNull CompletableFuture<Void> runUpdateTask();
 
+    /**
+     * Executes a health check.
+     *
+     * <p>This task checks if the LuckPerms implementation is running and
+     * whether it has a connection to the database (if applicable).</p>
+     *
+     * @return the health status
+     * @since 5.5
+     */
+    @NonNull Health runHealthCheck();
+
     /**
      * Registers a {@link MessengerProvider} for use by the platform.
      *
@@ -251,4 +242,40 @@ public interface LuckPerms {
      */
     void registerMessengerProvider(@NonNull MessengerProvider messengerProvider);
 
+    /**
+     * Gets the {@link NodeBuilderRegistry}.
+     *
+     * @return the node builder registry
+     */
+    @Internal
+    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
+
+    /**
+     * Gets the {@link QueryOptionsRegistry}.
+     *
+     * @return the query options registry
+     * @since 5.1
+     */
+    @Internal
+    @NonNull QueryOptionsRegistry getQueryOptionsRegistry();
+
+    /**
+     * Gets the {@link NodeMatcherFactory}.
+     *
+     * @return the node matcher factory
+     * @since 5.1
+     */
+    @Internal
+    @NonNull NodeMatcherFactory getNodeMatcherFactory();
+
+    /**
+     * Gets the {@link ActionFilterFactory}.
+     *
+     * @return the action filter factory
+     * @since 5.5
+     */
+    @Internal
+    @NonNull
+    ActionFilterFactory getActionFilterFactory();
+
 }

api/src/main/java/net/luckperms/api/LuckPermsProvider.java

@@ -27,41 +27,64 @@ package net.luckperms.api;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+import static org.jetbrains.annotations.ApiStatus.Internal;
+
 /**
- * Provides static access to the {@link LuckPerms} service.
+ * Provides static access to the {@link LuckPerms} API.
  *
  * <p>Ideally, the ServiceManager for the platform should be used to obtain an
- * instance, however, this provider can be used if you need static access.</p>
+ * instance, however, this provider can be used if this is not viable.</p>
  */
 public final class LuckPermsProvider {
     private static LuckPerms instance = null;
 
     /**
-     * Gets an instance of the {@link LuckPerms} service,
-     * throwing {@link IllegalStateException} if an instance is not yet loaded.
+     * Gets an instance of the {@link LuckPerms} API,
+     * throwing {@link IllegalStateException} if the API is not loaded yet.
      *
-     * <p>Will never return null.</p>
+     * <p>This method will never return null.</p>
      *
-     * @return an api instance
-     * @throws IllegalStateException if the api is not loaded
+     * @return an instance of the LuckPerms API
+     * @throws IllegalStateException if the API is not loaded yet
      */
     public static @NonNull LuckPerms get() {
+        LuckPerms instance = LuckPermsProvider.instance;
         if (instance == null) {
-            throw new IllegalStateException("The LuckPerms API is not loaded.");
+            throw new NotLoadedException();
         }
         return instance;
     }
 
+    @Internal
     static void register(LuckPerms instance) {
         LuckPermsProvider.instance = instance;
     }
 
+    @Internal
     static void unregister() {
         LuckPermsProvider.instance = null;
     }
 
+    @Internal
     private LuckPermsProvider() {
         throw new UnsupportedOperationException("This class cannot be instantiated.");
     }
 
+    /**
+     * Exception thrown when the API is requested before it has been loaded.
+     */
+    private static final class NotLoadedException extends IllegalStateException {
+        private static final String MESSAGE = "The LuckPerms API isn't loaded yet!\n" +
+                "This could be because:\n" +
+                "  a) the LuckPerms plugin is not installed or it failed to enable\n" +
+                "  b) the plugin in the stacktrace does not declare a dependency on LuckPerms\n" +
+                "  c) the plugin in the stacktrace is retrieving the API before the plugin 'enable' phase\n" +
+                "     (call the #get method in onEnable, not the constructor!)\n" +
+                "  d) the plugin in the stacktrace is incorrectly 'shading' the LuckPerms API into its jar\n";
+
+        NotLoadedException() {
+            super(MESSAGE);
+        }
+    }
+
 }

api/src/main/java/net/luckperms/api/actionlog/Action.java

@@ -26,9 +26,9 @@
 package net.luckperms.api.actionlog;
 
 import net.luckperms.api.LuckPermsProvider;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.time.Instant;
 import java.util.Optional;
@@ -36,7 +36,10 @@ import java.util.UUID;
 
 /**
  * Represents a logged action.
+ *
+ * <p>API users should not implement this interface directly.</p>
  */
+@NonExtendable
 public interface Action extends Comparable<Action> {
 
     /**
@@ -82,6 +85,7 @@ public interface Action extends Comparable<Action> {
     /**
      * Represents the source of an action.
      */
+    @NonExtendable
     interface Source {
 
         /**
@@ -103,6 +107,7 @@ public interface Action extends Comparable<Action> {
     /**
      * Represents the target of an action.
      */
+    @NonExtendable
     interface Target {
 
         /**
@@ -127,7 +132,7 @@ public interface Action extends Comparable<Action> {
         @NonNull Type getType();
 
         /**
-         * Represents the type of a {@link Target}.
+         * Represents the type of {@link Target}.
          */
         enum Type {
             USER, GROUP, TRACK
@@ -170,7 +175,7 @@ public interface Action extends Comparable<Action> {
          * @param type the type
          * @return the builder
          */
-        @NonNull Builder targetType(Action.Target.Type type);
+        @NonNull Builder targetType(Target.@NonNull Type type);
 
         /**
          * Sets the acted object for the entry.

api/src/main/java/net/luckperms/api/actionlog/ActionLog.java

@@ -25,7 +25,9 @@
 
 package net.luckperms.api.actionlog;
 
+import net.luckperms.api.actionlog.filter.ActionFilter;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.SortedSet;
 import java.util.UUID;
@@ -39,7 +41,11 @@ import java.util.UUID;
  * You can add to the log using the {@link ActionLogger}, and then request an updated copy.</p>
  *
  * <p>All methods are thread safe, and return immutable and thread safe collections.</p>
+ *
+ * @deprecated Use {@link ActionLogger#queryActions(ActionFilter)} or
+ * {@link ActionLogger#queryActions(ActionFilter, int, int)} instead.
  */
+@Deprecated
 public interface ActionLog {
 
     /**
@@ -47,7 +53,7 @@ public interface ActionLog {
      *
      * @return the content
      */
-    @NonNull SortedSet<Action> getContent();
+    @NonNull @Unmodifiable SortedSet<Action> getContent();
 
     /**
      * Gets the entries in the log performed by the given actor.
@@ -55,7 +61,7 @@ public interface ActionLog {
      * @param actor the uuid of the actor to filter by
      * @return the content for the given actor
      */
-    @NonNull SortedSet<Action> getContent(@NonNull UUID actor);
+    @NonNull @Unmodifiable SortedSet<Action> getContent(@NonNull UUID actor);
 
     /**
      * Gets the log content for a given user
@@ -63,7 +69,7 @@ public interface ActionLog {
      * @param uniqueId the uuid to filter by
      * @return all content in this log where the user = uuid
      */
-    @NonNull SortedSet<Action> getUserHistory(@NonNull UUID uniqueId);
+    @NonNull @Unmodifiable SortedSet<Action> getUserHistory(@NonNull UUID uniqueId);
 
     /**
      * Gets the log content for a given group
@@ -71,7 +77,7 @@ public interface ActionLog {
      * @param name the name to filter by
      * @return all content in this log where the group = name
      */
-    @NonNull SortedSet<Action> getGroupHistory(@NonNull String name);
+    @NonNull @Unmodifiable SortedSet<Action> getGroupHistory(@NonNull String name);
 
     /**
      * Gets the log content for a given track
@@ -79,6 +85,6 @@ public interface ActionLog {
      * @param name the name to filter by
      * @return all content in this log where the track = name
      */
-    @NonNull SortedSet<Action> getTrackHistory(@NonNull String name);
+    @NonNull @Unmodifiable SortedSet<Action> getTrackHistory(@NonNull String name);
 
 }

api/src/main/java/net/luckperms/api/actionlog/ActionLogger.java

@@ -25,10 +25,11 @@
 
 package net.luckperms.api.actionlog;
 
-import net.luckperms.api.messaging.MessagingService;
-
+import net.luckperms.api.actionlog.filter.ActionFilter;
+import net.luckperms.api.util.Page;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
 /**
@@ -47,43 +48,78 @@ public interface ActionLogger {
      * Gets a {@link ActionLog} instance from the plugin storage.
      *
      * @return a log instance
+     * @deprecated Use {@link #queryActions(ActionFilter)} or {@link #queryActions(ActionFilter, int, int)} instead. These methods
+     * are more efficient (they don't load the full action log into memory) and allow for pagination.
      */
+    @Deprecated
     @NonNull CompletableFuture<ActionLog> getLog();
 
     /**
-     * Submits a log entry to the plugin to be handled.
+     * Gets all actions from the action log matching the given {@code filter}.
      *
-     * <p>This method submits the log to the storage provider and broadcasts
-     * it.</p>
+     * <p>If the filter is {@code null}, all actions will be returned.</p>
      *
-     * <p>It is therefore roughly equivalent to calling
-     * {@link #submitToStorage(Action)} and {@link #broadcastAction(Action)},
-     * however, using this method is preferred to making the calls individually.</p>
+     * <p>Unlike {@link #queryActions(ActionFilter, int, int)}, this method does not implement any pagination and will return
+     * all entries at once.</p>
      *
-     * <p>If you want to submit a log entry but don't know which method to pick,
+     * @param filter the filter, optional
+     * @return the actions
+     * @since 5.5
+     */
+    @NonNull CompletableFuture<List<Action>> queryActions(@NonNull ActionFilter filter);
+
+    /**
+     * Gets a page of actions from the action log matching the given {@code filter}.
+     *
+     * <p>If the filter is {@code null}, all actions will be returned.</p>
+     *
+     * @param filter the filter, optional
+     * @param pageSize the size of the page
+     * @param pageNumber the page number
+     * @return the page of actions
+     * @since 5.5
+     */
+    @NonNull CompletableFuture<Page<Action>> queryActions(@NonNull ActionFilter filter, int pageSize, int pageNumber);
+
+    /**
+     * Submits a logged action to LuckPerms.
+     *
+     * <p>This method submits the action to the storage provider to be persisted in the action log.
+     * It also broadcasts it to administrator players on the current instance and to admins on other
+     * connected servers if a messaging service is configured.</p>
+     *
+     * <p>It is roughly equivalent to calling
+     * {@link #submitToStorage(Action)} followed by {@link #broadcastAction(Action)},
+     * however using this method is preferred to making the calls individually.</p>
+     *
+     * <p>If you want to submit an action log entry but don't know which method to pick,
      * use this one.</p>
      *
      * @param entry the entry to submit
-     * @return a future which will complete when the action is done
+     * @return a future which will complete when the action is submitted
      */
     @NonNull CompletableFuture<Void> submit(@NonNull Action entry);
 
     /**
-     * Submits a log entry to the plugins storage handler.
+     * Submits a logged action to LuckPerms and persists it in the storage backend.
+     *
+     * <p>This method does not broadcast the action or send it through the messaging service.</p>
      *
      * @param entry the entry to submit
-     * @return a future which will complete when the action is done
+     * @return a future which will complete when the action is submitted
      */
     @NonNull CompletableFuture<Void> submitToStorage(@NonNull Action entry);
 
     /**
-     * Submits a log entry to the plugins log broadcasting handler.
+     * Submits a logged action to LuckPerms and broadcasts it to administrators.
      *
-     * <p>If enabled, this method will also dispatch the log entry via the
-     * plugins {@link MessagingService}.</p>
+     * <p>The broadcast is made to administrator players on the current instance
+     * and to admins on other connected servers if a messaging service is configured.</p>
+     *
+     * <p>This method does not save the action to the plugin storage backend.</p>
      *
      * @param entry the entry to submit
-     * @return a future which will complete when the action is done
+     * @return a future which will complete when the action is broadcasted
      */
     @NonNull CompletableFuture<Void> broadcastAction(@NonNull Action entry);
 

api/src/main/java/net/luckperms/api/actionlog/filter/ActionFilter.java

@@ -0,0 +1,114 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.actionlog.filter;
+
+import net.luckperms.api.LuckPermsProvider;
+import net.luckperms.api.actionlog.Action;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
+
+import java.util.UUID;
+import java.util.function.Predicate;
+
+/**
+ * A predicate filter which matches certain {@link Action}s.
+ *
+ * <p>API users should not implement this interface directly.</p>
+ *
+ * @since 5.5
+ */
+@NonExtendable
+public interface ActionFilter extends Predicate<Action> {
+
+    /**
+     * Gets an {@link ActionFilter} which matches any action.
+     *
+     * @return the matcher
+     */
+    static ActionFilter any() {
+        return LuckPermsProvider.get().getActionFilterFactory().any();
+    }
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions with a specific source user.
+     *
+     * @param uniqueId the source user unique id
+     * @return the matcher
+     */
+    static ActionFilter source(UUID uniqueId) {
+        return LuckPermsProvider.get().getActionFilterFactory().source(uniqueId);
+    }
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which target a specific user.
+     *
+     * @param uniqueId the target user unique id
+     * @return the matcher
+     */
+    static ActionFilter user(UUID uniqueId) {
+        return LuckPermsProvider.get().getActionFilterFactory().user(uniqueId);
+    }
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which target a specific group.
+     *
+     * @param name the target group name
+     * @return the matcher
+     */
+    static ActionFilter group(String name) {
+        return LuckPermsProvider.get().getActionFilterFactory().group(name);
+    }
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which target a specific track.
+     *
+     * @param name the target track name
+     * @return the matcher
+     */
+    static ActionFilter track(String name) {
+        return LuckPermsProvider.get().getActionFilterFactory().track(name);
+    }
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which contain a specific search query in the source name,
+     * target name or description.
+     *
+     * @param query the search query
+     * @return the matcher
+     */
+    static ActionFilter search(String query) {
+        return LuckPermsProvider.get().getActionFilterFactory().search(query);
+    }
+
+    /**
+     * Tests to see if the given {@link Action} matches the filter.
+     *
+     * @param action the action to test
+     * @return true if the action matched
+     */
+    @Override
+    boolean test(Action action);
+
+}

api/src/main/java/net/luckperms/api/actionlog/filter/ActionFilterFactory.java

@@ -0,0 +1,88 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.actionlog.filter;
+
+import org.jetbrains.annotations.ApiStatus.Internal;
+
+import java.util.UUID;
+
+/**
+ * A factory which creates {@link ActionFilter}s.
+ *
+ * @since 5.5
+ */
+@Internal
+public interface ActionFilterFactory {
+
+    /**
+     * Gets an {@link ActionFilter} which matches any action.
+     *
+     * @return the matcher
+     */
+    ActionFilter any();
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions with a specific source user.
+     *
+     * @param uniqueId the source user unique id
+     * @return the matcher
+     */
+    ActionFilter source(UUID uniqueId);
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which target a specific user.
+     *
+     * @param uniqueId the target user unique id
+     * @return the matcher
+     */
+    ActionFilter user(UUID uniqueId);
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which target a specific group.
+     *
+     * @param name the target group name
+     * @return the matcher
+     */
+    ActionFilter group(String name);
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which target a specific track.
+     *
+     * @param name the target track name
+     * @return the matcher
+     */
+    ActionFilter track(String name);
+
+    /**
+     * Gets an {@link ActionFilter} which matches actions which contain a specific search query in the source name,
+     * target name or description.
+     *
+     * @param query the search query
+     * @return the matcher
+     */
+    ActionFilter search(String query);
+
+}

api/src/main/java/net/luckperms/api/actionlog/filter/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * {@link net.luckperms.api.actionlog.Action} filters.
+ */
+package net.luckperms.api.actionlog.filter;

api/src/main/java/net/luckperms/api/actionlog/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * {@link net.luckperms.api.actionlog.ActionLog} related functionality.
+ */
+package net.luckperms.api.actionlog;

api/src/main/java/net/luckperms/api/cacheddata/CachedData.java

@@ -26,11 +26,14 @@
 package net.luckperms.api.cacheddata;
 
 import net.luckperms.api.query.QueryOptions;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Holds cached lookup data for a given set of query options.
+ *
+ * <p>All calls will account for inheritance, as well as any default data
+ * provided by the platform. These calls are heavily cached and are therefore
+ * fast.</p>
  */
 public interface CachedData {
 

api/src/main/java/net/luckperms/api/cacheddata/CachedDataManager.java

@@ -30,7 +30,6 @@ import net.luckperms.api.model.PermissionHolder;
 import net.luckperms.api.model.group.Group;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.query.QueryOptions;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.concurrent.CompletableFuture;
@@ -39,7 +38,7 @@ import java.util.concurrent.CompletableFuture;
  * Holds cached permission and meta lookup data for a {@link PermissionHolder}.
  *
  * <p>All calls will account for inheritance, as well as any default data
- * provided by the platform. This calls are heavily cached and are therefore
+ * provided by the platform. These calls are heavily cached and are therefore
  * fast.</p>
  */
 public interface CachedDataManager {
@@ -81,11 +80,10 @@ public interface CachedDataManager {
      * <p>For {@link User}s, the most appropriate query options will be their
      * {@link ContextManager#getQueryOptions(User) current active query options} if the
      * corresponding player is online, and otherwise, will fallback to
-     * {@link ContextManager#getStaticQueryOptions() the current static query options}
-     * if they are offline.</p>
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}.</p>
      *
      * <p>For {@link Group}s, the most appropriate query options will always be
-     * {@link ContextManager#getStaticQueryOptions()} the current static query options.</p>
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}.</p>
      *
      * @return a permission data instance
      * @since 5.1
@@ -99,11 +97,10 @@ public interface CachedDataManager {
      * <p>For {@link User}s, the most appropriate query options will be their
      * {@link ContextManager#getQueryOptions(User) current active query options} if the
      * corresponding player is online, and otherwise, will fallback to
-     * {@link ContextManager#getStaticQueryOptions() the current static query options}
-     * if they are offline.</p>
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}.</p>
      *
      * <p>For {@link Group}s, the most appropriate query options will always be
-     * {@link ContextManager#getStaticQueryOptions()} the current static query options.</p>
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}.</p>
      *
      * @return a meta data instance
      * @since 5.1
@@ -118,7 +115,7 @@ public interface CachedDataManager {
     void invalidate();
 
     /**
-     * Invalidates all of the underlying Permission calculators.
+     * Invalidates all underlying permission calculators.
      *
      * <p>Can be called to allow for an update in defaults.</p>
      */

api/src/main/java/net/luckperms/api/cacheddata/CachedMetaData.java

@@ -26,63 +26,207 @@
 package net.luckperms.api.cacheddata;
 
 import net.luckperms.api.metastacking.MetaStackDefinition;
-
+import net.luckperms.api.node.types.MetaNode;
+import net.luckperms.api.node.types.PrefixNode;
+import net.luckperms.api.node.types.SuffixNode;
+import net.luckperms.api.node.types.WeightNode;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.SortedMap;
+import java.util.function.Function;
 
 /**
  * Holds cached meta lookup data for a specific set of contexts.
+ * 
+ * <p>Meta data refers to {@link PrefixNode prefixes}, {@link SuffixNode suffixes} and
+ * {@link MetaNode meta (options)} held by a permission holder.</p>
+ *
+ * <p>All calls will account for inheritance, as well as any default data
+ * provided by the platform. These calls are heavily cached and are therefore
+ * fast.</p>
  */
 public interface CachedMetaData extends CachedData {
 
+    /**
+     * Query a meta value for the given {@code key}.
+     * 
+     * <p>This method will always return a {@link Result}, but the
+     * {@link Result#result() inner result} {@link String} will be null if a value
+     * for the given key was not found.</p>
+     *
+     * @param key the key
+     * @return a result containing the value
+     * @since 5.4
+     */
+    @NonNull Result<String, MetaNode> queryMetaValue(@NonNull String key);
+
     /**
      * Gets a value for the given meta key.
+     * 
+     * <p>If no such meta value exists for the given key, {@code null} is returned.</p>
      *
      * @param key the key
      * @return the value
      */
-    @Nullable String getMetaValue(String key);
+    default @Nullable String getMetaValue(@NonNull String key) {
+        return queryMetaValue(key).result();
+    }
 
     /**
-     * Gets the holder's highest priority prefix, or null if the holder has no prefixes
+     * Gets a value for the given meta key, and runs it through the given {@code transformer}.
+     *
+     * <p>If no such meta value exists, an {@link Optional#empty() empty optional} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in an {@link Optional#empty() empty optional} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     getMetaValue("my-int-val", Integer::parseInt).orElse(0);
+     * </pre></blockquote>
+     *
+     * @param key the key
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the meta value
+     * @since 5.3
+     */
+    default <T> @NonNull Optional<T> getMetaValue(@NonNull String key, @NonNull Function<String, ? extends T> valueTransformer) {
+        return Optional.ofNullable(getMetaValue(key)).map(value -> {
+            try {
+                return valueTransformer.apply(value);
+            } catch (IllegalArgumentException e) {
+                return null;
+            }
+        });
+    }
+
+    /**
+     * Query for a prefix.
+     * 
+     * <p>This method uses the rules defined by the {@link #getPrefixStackDefinition() prefix stack}
+     * to produce a {@link String} output.</p>
+     * 
+     * <p>Assuming the default configuration is used, this will usually be the value of the
+     * holder's highest priority prefix node.</p>
+     * 
+     * <p>This method will always return a {@link Result}, but the
+     * {@link Result#result() inner result} {@link String} will be null if
+     * a the resultant prefix stack contained no elements.</p>
+     *
+     * @return a result containing the prefix
+     * @since 5.4
+     */
+    @NonNull Result<String, PrefixNode> queryPrefix();
+
+    /**
+     * Gets the prefix.
+     * 
+     * <p>This method uses the rules defined by the {@link #getPrefixStackDefinition() prefix stack}
+     * to produce a {@link String} output.</p>
+     * 
+     * <p>Assuming the default configuration is used, this will usually be the value of the
+     * holder's highest priority prefix node.</p>
+     * 
+     * <p>If the resultant prefix stack contained no elements, {@code null} is returned.</p>
      *
      * @return a prefix string, or null
      */
-    @Nullable String getPrefix();
+    default @Nullable String getPrefix() {
+        return queryPrefix().result();
+    }
 
     /**
-     * Gets the holder's highest priority suffix, or null if the holder has no suffixes
+     * Query for a suffix.
+     *
+     * <p>This method uses the rules defined by the {@link #getSuffixStackDefinition() suffix stack}
+     * to produce a {@link String} output.</p>
+     *
+     * <p>Assuming the default configuration is used, this will usually be the value of the
+     * holder's highest priority suffix node.</p>
+     *
+     * <p>This method will always return a {@link Result}, but the
+     * {@link Result#result() inner result} {@link String} will be null if
+     * a the resultant suffix stack contained no elements.</p>
+     *
+     * @return a result containing the suffix
+     * @since 5.4
+     */
+    @NonNull Result<String, SuffixNode> querySuffix();
+
+    /**
+     * Gets the suffix.
+     *
+     * <p>This method uses the rules defined by the {@link #getSuffixStackDefinition() suffix stack}
+     * to produce a {@link String} output.</p>
+     *
+     * <p>Assuming the default configuration is used, this will usually be the value of the
+     * holder's highest priority suffix node.</p>
+     *
+     * <p>If the resultant suffix stack contained no elements, {@code null} is returned.</p>
      *
      * @return a suffix string, or null
      */
-    @Nullable String getSuffix();
+    default @Nullable String getSuffix() {
+        return querySuffix().result();
+    }
 
     /**
-     * Gets an immutable copy of the meta this holder has.
+     * Query for a weight.
      *
-     * @return an immutable map of meta
+     * <p>This method will always return a {@link Result}, and the
+     * {@link Result#result() inner result} {@link Integer} will never be null.
+     * A value of {@code 0} is equivalent to null.</p>
+     *
+     * @return a result containing the weight
+     * @since 5.5
      */
-    @NonNull Map<String, List<String>> getMeta();
+    @NonNull Result<Integer, WeightNode> queryWeight();
 
     /**
-     * Gets an immutable sorted map of all of the prefixes the holder has, whereby the first
-     * value is the highest priority prefix.
+     * Gets the weight.
+     *
+     * <p>If the there is no defined weight, {@code 0} is returned.</p>
+     *
+     * @return the weight
+     * @since 5.5
+     */
+    default int getWeight() {
+        return queryWeight().result();
+    }
+
+    /**
+     * Gets a map of all accumulated {@link MetaNode meta}.
+     *
+     * <p>Prefer using the {@link #getMetaValue(String)} method for querying values.</p>
+     *
+     * @return a map of meta
+     */
+    @NonNull @Unmodifiable Map<String, List<String>> getMeta();
+
+    /**
+     * Gets a sorted map of all accumulated {@link PrefixNode prefixes}.
+     *
+     * <p>Prefer using the {@link #getPrefix()} method for querying.</p>
      *
      * @return a sorted map of prefixes
      */
-    @NonNull SortedMap<Integer, String> getPrefixes();
+    @NonNull @Unmodifiable SortedMap<Integer, String> getPrefixes();
 
     /**
-     * Gets an immutable sorted map of all of the suffixes the holder has, whereby the first
-     * value is the highest priority suffix.
+     * Gets a sorted map of all accumulated {@link SuffixNode suffixes}.
+     *
+     * <p>Prefer using the {@link #getSuffix()} method for querying.</p>
      *
      * @return a sorted map of suffixes
      */
-    @NonNull SortedMap<Integer, String> getSuffixes();
+    @NonNull @Unmodifiable SortedMap<Integer, String> getSuffixes();
 
     /**
      * Gets the name of the holders primary group.
@@ -95,14 +239,14 @@ public interface CachedMetaData extends CachedData {
     @Nullable String getPrimaryGroup();
 
     /**
-     * Gets the definition used for the prefix stack
+     * Gets the definition used for the prefix stack.
      *
      * @return the definition used for the prefix stack
      */
     @NonNull MetaStackDefinition getPrefixStackDefinition();
 
     /**
-     * Gets the definition used for the suffix stack
+     * Gets the definition used for the suffix stack.
      *
      * @return the definition used for the suffix stack
      */

api/src/main/java/net/luckperms/api/cacheddata/CachedPermissionData.java

@@ -25,25 +25,48 @@
 
 package net.luckperms.api.cacheddata;
 
+import net.luckperms.api.node.Node;
 import net.luckperms.api.util.Tristate;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Map;
 
 /**
  * Holds cached permission lookup data for a specific set of contexts.
+ *
+ * <p>All calls will account for inheritance, as well as any default data
+ * provided by the platform. These calls are heavily cached and are therefore
+ * fast.</p>
  */
 public interface CachedPermissionData extends CachedData {
 
     /**
-     * Gets a permission check result for the given permission node.
+     * Performs a permission check for the given {@code permission} node.
+     *
+     * <p>This check is equivalent to the "hasPermission" method call on most platforms.
+     * You can use {@link Tristate#asBoolean()} if you need a truthy result.</p>
+     *
+     * @param permission the permission node
+     * @return a result containing the tristate
+     * @throws NullPointerException if permission is null
+     * @since 5.4
+     */
+    @NonNull Result<Tristate, Node> queryPermission(@NonNull String permission);
+
+    /**
+     * Performs a permission check for the given {@code permission} node.
+     *
+     * <p>This check is equivalent to the "hasPermission" method call on most platforms.
+     * You can use {@link Tristate#asBoolean()} if you need a truthy result.</p>
      *
      * @param permission the permission node
      * @return a tristate result
      * @throws NullPointerException if permission is null
      */
-    @NonNull Tristate checkPermission(@NonNull String permission);
+    default @NonNull Tristate checkPermission(@NonNull String permission) {
+        return queryPermission(permission).result();
+    }
 
     /**
      * Invalidates the underlying permission calculator cache.
@@ -57,6 +80,6 @@ public interface CachedPermissionData extends CachedData {
      *
      * @return an immutable set of permissions
      */
-    @NonNull Map<String, Boolean> getPermissionMap();
+    @NonNull @Unmodifiable Map<String, Boolean> getPermissionMap();
 
 }

api/src/main/java/net/luckperms/api/cacheddata/Result.java

@@ -0,0 +1,81 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.cacheddata;
+
+import net.luckperms.api.node.Node;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * Represents the result of a cached data lookup.
+ *
+ * <p>You can find "the holder that has the node that caused this result"
+ * using the following code:</p>
+ * <p></p>
+ * <blockquote>
+ * <pre>
+ * public static {@link net.luckperms.api.model.PermissionHolder.Identifier} holderThatHasTheNodeThatCausedTheResult(Result&lt;?, ?&gt; result) {
+ *     {@link Node} node = result.node();
+ *     if (node == null) {
+ *         return null;
+ *     }
+ *     {@link net.luckperms.api.node.metadata.types.InheritanceOriginMetadata} origin = node.getMetadata(InheritanceOriginMetadata.KEY).orElse(null);
+ *     if (origin == null) {
+ *         return null;
+ *     }
+ *     return origin.getOrigin();
+ * }
+ * </pre>
+ *
+ * <p>Combined with the node itself, this is all the information needed to determine
+ * the root cause of the result.</p>
+ * </blockquote>
+ *
+ * <p>The nullability of {@link #result()} is purposely undefined to allow the
+ * flexibility for methods using {@link Result} to declare it. In general, if the {@code T} type
+ * has a nullable/undefined value, then the return of {@link #result()} will be non-null,
+ * and if not, it will be nullable.</p>
+ *
+ * @param <T> the result type
+ * @param <N> the node type
+ * @since 5.4
+ */
+public interface Result<T, N extends Node> {
+
+    /**
+     * Gets the underlying result.
+     *
+     * @return the underlying result
+     */
+    T result();
+
+    /**
+     * Gets the node that caused the result.
+     *
+     * @return the causing node
+     */
+    @Nullable N node();
+
+}

api/src/main/java/net/luckperms/api/cacheddata/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Caches permission checks and meta lookups for {@link net.luckperms.api.model.user.User}s and
+ * {@link net.luckperms.api.model.group.Group}s.
+ */
+package net.luckperms.api.cacheddata;

api/src/main/java/net/luckperms/api/context/ContextCalculator.java

@@ -103,7 +103,7 @@ public interface ContextCalculator<T> {
      *
      * @return a set of potential contexts
      */
-    default ContextSet estimatePotentialContexts() {
+    default @NonNull ContextSet estimatePotentialContexts() {
         return ImmutableContextSet.empty();
     }
 

api/src/main/java/net/luckperms/api/context/ContextManager.java

@@ -28,8 +28,8 @@ package net.luckperms.api.context;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.query.QueryMode;
 import net.luckperms.api.query.QueryOptions;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 import java.util.Optional;
 
@@ -48,6 +48,7 @@ import java.util.Optional;
  * <li>{@code org.bukkit.entity.Player}</li>
  * <li>{@code net.md_5.bungee.api.connection.ProxiedPlayer}</li>
  * <li>{@code org.spongepowered.api.service.permission.Subject}</li>
+ * <li>{@code net.minecraft.server.network.ServerPlayerEntity} (Fabric)</li>
  * <li>{@code cn.nukkit.Player}</li>
  * <li>{@code com.velocitypowered.api.proxy.Player}</li>
  * </ul>
@@ -156,13 +157,14 @@ public interface ContextManager {
      *
      * @return the context set factory
      */
+    @Internal
     @NonNull ContextSetFactory getContextSetFactory();
 
     /**
      * Invalidates the lookup cache for a given subject
      *
      * @param subject the subject
-     * @deprecated use {@link #signalContextUpdate(Object)}
+     * @deprecated Use {@link #signalContextUpdate(Object)} instead
      */
     @Deprecated
     default void invalidateCache(@NonNull Object subject) {

api/src/main/java/net/luckperms/api/context/ContextSet.java

@@ -26,6 +26,7 @@
 package net.luckperms.api.context;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Iterator;
 import java.util.Map;
@@ -111,7 +112,7 @@ public interface ContextSet extends Iterable<Context> {
      *
      * @return an immutable set
      */
-    @NonNull Set<Context> toSet();
+    @NonNull @Unmodifiable Set<Context> toSet();
 
     /**
      * Returns a {@link Map} representing the current state of this
@@ -122,7 +123,7 @@ public interface ContextSet extends Iterable<Context> {
      *
      * @return a map
      */
-    @NonNull Map<String, Set<String>> toMap();
+    @NonNull @Unmodifiable Map<String, Set<String>> toMap();
 
     /**
      * Returns a {@link Map} <b>loosely</b> representing the current state of
@@ -135,10 +136,10 @@ public interface ContextSet extends Iterable<Context> {
      * may not be a true representation of the set.</p>
      *
      * @return an immutable map
-     * @deprecated because the resultant map may not contain all data in the ContextSet
+     * @deprecated Deprecated because the returned map may not contain all data in the ContextSet
      */
     @Deprecated
-    @NonNull Map<String, String> toFlattenedMap();
+    @NonNull @Unmodifiable Map<String, String> toFlattenedMap();
 
     /**
      * Returns an {@link Iterator} over each of the context pairs in this set.
@@ -151,7 +152,7 @@ public interface ContextSet extends Iterable<Context> {
      * @return an iterator
      */
     @Override
-    @NonNull Iterator<Context> iterator();
+    @NonNull @Unmodifiable Iterator<Context> iterator();
 
     /**
      * Returns if the {@link ContextSet} contains at least one value for the
@@ -173,7 +174,7 @@ public interface ContextSet extends Iterable<Context> {
      * @return a set of values
      * @throws NullPointerException if the key is null
      */
-    @NonNull Set<String> getValues(@NonNull String key);
+    @NonNull @Unmodifiable Set<String> getValues(@NonNull String key);
 
     /**
      * Returns any value from this {@link ContextSet} matching the key, if present.

api/src/main/java/net/luckperms/api/context/ContextSetFactory.java

@@ -26,18 +26,49 @@
 package net.luckperms.api.context;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 /**
  * A factory for creating {@link ContextSet}s.
+ *
+ * <p>Prefer using the static methods on {@link ImmutableContextSet} or {@link MutableContextSet}
+ * instead of this interface.</p>
  */
+@Internal
 public interface ContextSetFactory {
 
+    /**
+     * Prefer using {@link ImmutableContextSet#builder()}.
+     *
+     * @return a immutable context set builder
+     * @see ImmutableContextSet#builder()
+     */
     ImmutableContextSet.@NonNull Builder immutableBuilder();
 
+    /**
+     * Prefer using {@link ImmutableContextSet#of(String, String)}.
+     *
+     * @param key the key
+     * @param value the value
+     * @return an immutable context set
+     * @see ImmutableContextSet#of(String, String)
+     */
     @NonNull ImmutableContextSet immutableOf(@NonNull String key, @NonNull String value);
 
+    /**
+     * Prefer using {@link ImmutableContextSet#empty()}.
+     *
+     * @return an empty immutable context set
+     * @see ImmutableContextSet#empty()
+     */
     @NonNull ImmutableContextSet immutableEmpty();
 
+    /**
+     * Prefer using {@link MutableContextSet#create()}.
+     *
+     * @return a new mutable context set
+     * @see MutableContextSet#create()
+     */
     @NonNull MutableContextSet mutable();
 
 }

api/src/main/java/net/luckperms/api/context/DefaultContextKeys.java

@@ -34,13 +34,31 @@ public final class DefaultContextKeys {
     }
 
     /**
-     * The context key used to denote the subjects server.
+     * The context key used to denote the name of the subjects server.
      */
     public static final String SERVER_KEY = "server";
 
     /**
-     * The context key used to denote the subjects world.
+     * The context key used to denote the name of the subjects world.
      */
     public static final String WORLD_KEY = "world";
 
+    /**
+     * The context key used to denote the dimension type of the subjects world.
+     *
+     * <p>Possible values: overworld, the_nether, the_end</p>
+     *
+     * @since 5.3
+     */
+    public static final String DIMENSION_TYPE_KEY = "dimension-type";
+
+    /**
+     * The context key used to denote the subjects gamemode.
+     *
+     * <p>Possible values: survival, creative, adventure, spectator</p>
+     *
+     * @since 5.3
+     */
+    public static final String GAMEMODE_KEY = "gamemode";
+
 }

api/src/main/java/net/luckperms/api/context/ImmutableContextSet.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.context;
 
 import net.luckperms.api.LuckPermsProvider;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Objects;
@@ -67,7 +66,7 @@ public interface ImmutableContextSet extends ContextSet {
     }
 
     /**
-     * @deprecated Already immutable!
+     * @deprecated This context set is already immutable!
      */
     @Override
     @Deprecated
@@ -119,7 +118,7 @@ public interface ImmutableContextSet extends ContextSet {
         }
 
         /**
-         * Adds of of the contexts in another {@link ContextSet} to the set.
+         * Adds all the contexts in another {@link ContextSet} to the set.
          *
          * @param contextSet the set to add from
          * @return the builder

api/src/main/java/net/luckperms/api/context/MutableContextSet.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.context;
 
 import net.luckperms.api.LuckPermsProvider;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Objects;
@@ -94,7 +93,7 @@ public interface MutableContextSet extends ContextSet {
     }
 
     /**
-     * Adds of of the contexts in another {@link ContextSet} to this set.
+     * Adds all the contexts in another {@link ContextSet} to this set.
      *
      * @param contextSet the set to add from
      * @throws NullPointerException if the contextSet is null

api/src/main/java/net/luckperms/api/context/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Context functionality, including {@link net.luckperms.api.context.ContextSet}s and
+ * {@link net.luckperms.api.context.ContextCalculator}s.
+ */
+package net.luckperms.api.context;

api/src/main/java/net/luckperms/api/event/EventBus.java

@@ -26,6 +26,7 @@
 package net.luckperms.api.event;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Set;
 import java.util.function.Consumer;
@@ -49,7 +50,7 @@ public interface EventBus {
      * @param <T>        the event class
      * @return an event handler instance representing this subscription
      */
-    @NonNull <T extends LuckPermsEvent> EventSubscription<T> subscribe(@NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
+    <T extends LuckPermsEvent> @NonNull EventSubscription<T> subscribe(@NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
 
     /**
      * Registers a new subscription to the given event.
@@ -69,7 +70,7 @@ public interface EventBus {
      * @param handler    the event handler
      * @return an event handler instance representing this subscription
      */
-    @NonNull <T extends LuckPermsEvent> EventSubscription<T> subscribe(Object plugin, @NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
+    <T extends LuckPermsEvent> @NonNull EventSubscription<T> subscribe(Object plugin, @NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
 
     /**
      * Gets a set of all registered handlers for a given event.
@@ -78,6 +79,6 @@ public interface EventBus {
      * @param <T>        the event class
      * @return an immutable set of event handlers
      */
-    @NonNull <T extends LuckPermsEvent> Set<EventSubscription<T>> getSubscriptions(@NonNull Class<T> eventClass);
+    <T extends LuckPermsEvent> @NonNull @Unmodifiable Set<EventSubscription<T>> getSubscriptions(@NonNull Class<T> eventClass);
 
 }

api/src/main/java/net/luckperms/api/event/LuckPermsEvent.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.event;
 
 import net.luckperms.api.LuckPerms;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/cause/DeletionCause.java

@@ -35,6 +35,12 @@ public enum DeletionCause {
      */
     COMMAND,
 
+    /**
+     * The deletion was caused by the web editor
+     * @since 5.3
+     */
+    WEB_EDITOR,
+
     /**
      * The deletion was caused by an API call
      */

api/src/main/java/net/luckperms/api/event/cause/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Event causes.
+ */
+package net.luckperms.api.event.cause;

api/src/main/java/net/luckperms/api/event/context/ContextUpdateEvent.java

@@ -28,7 +28,6 @@ package net.luckperms.api.event.context;
 import net.luckperms.api.context.ContextManager;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Optional;

api/src/main/java/net/luckperms/api/event/context/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to {@link net.luckperms.api.context.Context}s.
+ */
+package net.luckperms.api.event.context;

api/src/main/java/net/luckperms/api/event/extension/ExtensionLoadEvent.java

@@ -28,7 +28,6 @@ package net.luckperms.api.event.extension;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.extension.Extension;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/extension/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to {@link net.luckperms.api.extension.Extension}s.
+ */
+package net.luckperms.api.event.extension;

api/src/main/java/net/luckperms/api/event/group/GroupCacheLoadEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.cacheddata.CachedDataManager;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.group.Group;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/group/GroupCreateEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.cause.CreationCause;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.group.Group;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/group/GroupDataRecalculateEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.cacheddata.CachedDataManager;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.group.Group;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/group/GroupDeleteEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.cause.DeletionCause;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.node.Node;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Set;

api/src/main/java/net/luckperms/api/event/group/GroupLoadEvent.java

@@ -28,7 +28,6 @@ package net.luckperms.api.event.group;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.group.Group;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/group/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to {@link net.luckperms.api.model.group.Group}s.
+ */
+package net.luckperms.api.event.group;

api/src/main/java/net/luckperms/api/event/log/LogBroadcastEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.actionlog.Action;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/log/LogNetworkPublishEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.actionlog.Action;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;

api/src/main/java/net/luckperms/api/event/log/LogNotifyEvent.java

@@ -30,7 +30,6 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.platform.PlatformEntity;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/log/LogPublishEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.actionlog.Action;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/log/LogReceiveEvent.java

@@ -28,13 +28,16 @@ package net.luckperms.api.event.log;
 import net.luckperms.api.actionlog.Action;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;
 
 /**
- * Called when a log entry is received via the MessagingService
+ * Called when a log entry is received via the MessagingService.
+ *
+ * <p>Note: listening to this event is the same as listening to the {@link LogBroadcastEvent}
+ * and filtering for {@link LogBroadcastEvent#getOrigin() origin} =
+ * {@link net.luckperms.api.event.log.LogBroadcastEvent.Origin#REMOTE REMOTE}.</p>
  */
 public interface LogReceiveEvent extends LuckPermsEvent {
 

api/src/main/java/net/luckperms/api/event/log/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to the {@link net.luckperms.api.actionlog.ActionLog}.
+ */
+package net.luckperms.api.event.log;

api/src/main/java/net/luckperms/api/event/messaging/CustomMessageReceiveEvent.java

@@ -0,0 +1,59 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.messaging;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.messaging.MessagingService;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a custom payload message is received via the {@link MessagingService}.
+ *
+ * <p>This event is effectively the 'other end' of
+ * {@link MessagingService#sendCustomMessage(String, String)}.</p>
+ *
+ * @since 5.5
+ */
+public interface CustomMessageReceiveEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the channel id.
+     *
+     * @return the channel id
+     */
+    @Param(0)
+    @NonNull String getChannelId();
+
+    /**
+     * Gets the custom payload that was sent.
+     *
+     * @return the custom payload
+     */
+    @Param(1)
+    @NonNull String getPayload();
+
+}

api/src/main/java/net/luckperms/api/event/messaging/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to the {@link net.luckperms.api.messaging.MessagingService}.
+ */
+package net.luckperms.api.event.messaging;

api/src/main/java/net/luckperms/api/event/node/NodeAddEvent.java

@@ -27,8 +27,12 @@ package net.luckperms.api.event.node;
 
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.node.Node;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 
 /**
  * Called when a node is added to a holder
@@ -40,7 +44,14 @@ public interface NodeAddEvent extends NodeMutateEvent {
      *
      * @return the node that was added
      */
-    @Param(4)
+    @Param(3)
     @NonNull Node getNode();
 
+    @Override
+    default @NonNull @Unmodifiable Set<Node> getDataBefore() {
+        // Get data after, then reverse the action
+        Set<Node> nodes = new HashSet<>(this.getDataAfter());
+        nodes.remove(this.getNode());
+        return Collections.unmodifiableSet(nodes);
+    }
 }

api/src/main/java/net/luckperms/api/event/node/NodeClearEvent.java

@@ -25,9 +25,34 @@
 
 package net.luckperms.api.event.node;
 
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.node.Node;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+
 /**
  * Called when a holder has their nodes cleared
  */
 public interface NodeClearEvent extends NodeMutateEvent {
 
+    /**
+     * Gets the nodes that were cleared
+     *
+     * @return the nodes that were removed
+     * @since 5.3
+     */
+    @Param(3)
+    @NonNull @Unmodifiable Set<Node> getNodes();
+
+    @Override
+    default @NonNull @Unmodifiable Set<Node> getDataBefore() {
+        // Get data after, then reverse the action
+        Set<Node> nodes = new HashSet<>(this.getDataAfter());
+        nodes.addAll(this.getNodes());
+        return Collections.unmodifiableSet(nodes);
+    }
 }

api/src/main/java/net/luckperms/api/event/node/NodeMutateEvent.java

@@ -32,8 +32,8 @@ import net.luckperms.api.model.data.DataType;
 import net.luckperms.api.model.group.Group;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.node.Node;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Set;
 
@@ -63,16 +63,15 @@ public interface NodeMutateEvent extends LuckPermsEvent {
      *
      * @return the data before the change
      */
-    @Param(2)
-    @NonNull Set<Node> getDataBefore();
+    @NonNull @Unmodifiable Set<Node> getDataBefore();
 
     /**
      * Gets an immutable copy of the holders data after the change
      *
      * @return the data after the change
      */
-    @Param(3)
-    @NonNull Set<Node> getDataAfter();
+    @Param(2)
+    @NonNull @Unmodifiable Set<Node> getDataAfter();
 
     /**
      * Gets whether the target of this event is a {@link User}

api/src/main/java/net/luckperms/api/event/node/NodeRemoveEvent.java

@@ -27,8 +27,12 @@ package net.luckperms.api.event.node;
 
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.node.Node;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 
 /**
  * Called when a node is removed from a holder
@@ -40,7 +44,15 @@ public interface NodeRemoveEvent extends NodeMutateEvent {
      *
      * @return the node that was removed
      */
-    @Param(4)
+    @Param(3)
     @NonNull Node getNode();
 
+    @Override
+    default @NonNull @Unmodifiable Set<Node> getDataBefore() {
+        // Get data after, then reverse the action
+        Set<Node> nodes = new HashSet<>(this.getDataAfter());
+        nodes.add(this.getNode());
+        return Collections.unmodifiableSet(nodes);
+    }
+
 }

api/src/main/java/net/luckperms/api/event/node/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to changes to a {@link net.luckperms.api.model.user.User} or
+ * {@link net.luckperms.api.model.group.Group}s {@link net.luckperms.api.model.data.NodeMap}.
+ */
+package net.luckperms.api.event.node;

api/src/main/java/net/luckperms/api/event/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Main events package.
+ */
+package net.luckperms.api.event;

api/src/main/java/net/luckperms/api/event/player/PlayerDataSaveEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.PlayerSaveResult;
 import net.luckperms.api.model.user.UserManager;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;

api/src/main/java/net/luckperms/api/event/player/PlayerLoginProcessEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.util.Result;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 

api/src/main/java/net/luckperms/api/event/player/lookup/UniqueIdDetermineTypeEvent.java

@@ -0,0 +1,101 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.player.lookup;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.ResultEvent;
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Objects;
+import java.util.UUID;
+
+/**
+ * Called when the platform needs to determine the type of a player's {@link UUID unique id}.
+ *
+ * @since 5.3
+ */
+public interface UniqueIdDetermineTypeEvent extends LuckPermsEvent, ResultEvent<String> {
+
+    /**
+     * The players UUID has been obtained by authenticating with the Mojang session servers.
+     *
+     * <p>Usually indicated by the UUID being {@link UUID#version() version} 4.</p>
+     */
+    String TYPE_AUTHENTICATED = "authenticated";
+
+    /**
+     * The players UUID has not been obtained through authentication, and instead is likely based
+     * on the username they connected with.
+     *
+     * <p>Usually indicated by the UUID being {@link UUID#version() version} 3.</p>
+     */
+    String TYPE_UNAUTHENTICATED = "unauthenticated";
+
+    /**
+     * The players UUID most likely belongs to a NPC (non-player character).
+     *
+     * <p>Usually indicated by the UUID being {@link UUID#version() version} 2.</p>
+     *
+     * @since 5.4
+     */
+    String TYPE_NPC = "npc";
+
+    /**
+     * Unknown UUID type.
+     *
+     * @since 5.4
+     */
+    String TYPE_UNKNOWN = "unknown";
+
+    /**
+     * Gets the {@link UUID unique id} being queried.
+     *
+     * @return the unique id
+     */
+    @Param(0)
+    @NonNull UUID getUniqueId();
+
+    /**
+     * Gets the current result unique id type.
+     *
+     * @return the type
+     */
+    default @NonNull String getType() {
+        return result().get();
+    }
+
+    /**
+     * Sets the result unique id type.
+     *
+     * @param type the type
+     */
+    default void setType(@NonNull String type) {
+        Objects.requireNonNull(type, "type");
+        result().set(type);
+    }
+
+}

api/src/main/java/net/luckperms/api/event/player/lookup/UniqueIdLookupEvent.java

@@ -0,0 +1,60 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.player.lookup;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.ResultEvent;
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.UUID;
+
+/**
+ * Called when the platform needs a unique id for a given username.
+ *
+ * @since 5.3
+ */
+public interface UniqueIdLookupEvent extends LuckPermsEvent, ResultEvent<UUID> {
+
+    /**
+     * Gets the username being looked up.
+     *
+     * @return the username
+     */
+    @Param(0)
+    @NonNull String getUsername();
+
+    /**
+     * Sets the result unique id.
+     *
+     * @param uniqueId the unique id
+     */
+    default void setUniqueId(@Nullable UUID uniqueId) {
+        result().set(uniqueId);
+    }
+
+}

api/src/main/java/net/luckperms/api/event/player/lookup/UsernameLookupEvent.java

@@ -0,0 +1,60 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.player.lookup;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.ResultEvent;
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.UUID;
+
+/**
+ * Called when the platform needs a username for a given unique id.
+ *
+ * @since 5.3
+ */
+public interface UsernameLookupEvent extends LuckPermsEvent, ResultEvent<String> {
+
+    /**
+     * Gets the {@link UUID unique id} being looked up.
+     *
+     * @return the unique id
+     */
+    @Param(0)
+    @NonNull UUID getUniqueId();
+
+    /**
+     * Sets the result username.
+     *
+     * @param username the username
+     */
+    default void setUsername(@Nullable String username) {
+        result().set(username);
+    }
+
+}

api/src/main/java/net/luckperms/api/event/player/lookup/UsernameValidityCheckEvent.java

@@ -0,0 +1,75 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.player.lookup;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * Called when the validity of a username is being tested.
+ *
+ * @since 5.3
+ */
+public interface UsernameValidityCheckEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the username being tested.
+     *
+     * @return the username
+     */
+    @Param(0)
+    @NonNull String getUsername();
+
+    /**
+     * Gets the current validity state for the username.
+     *
+     * @return the validity state
+     */
+    @Param(1)
+    @NonNull AtomicBoolean validityState();
+
+    /**
+     * Gets if the username is currently considered to be valid.
+     *
+     * @return if the username is valid
+     */
+    default boolean isValid() {
+        return validityState().get();
+    }
+
+    /**
+     * Sets if the username should be considered valid or not.
+     *
+     * @param valid whether the username is valid
+     */
+    default void setValid(boolean valid) {
+        validityState().set(valid);
+    }
+
+}

api/src/main/java/net/luckperms/api/event/player/lookup/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to a player {@link java.util.UUID unique id} or username lookup.
+ */
+package net.luckperms.api.event.player.lookup;

api/src/main/java/net/luckperms/api/event/player/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to a player.
+ */
+package net.luckperms.api.event.player;

api/src/main/java/net/luckperms/api/event/source/EntitySource.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.event.source;
 
 import net.luckperms.api.platform.PlatformEntity;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/source/Source.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.event.source;
 
 import net.luckperms.api.platform.PlatformEntity;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/source/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Event sources.
+ */
+package net.luckperms.api.event.source;

api/src/main/java/net/luckperms/api/event/sync/PostNetworkSyncEvent.java

@@ -0,0 +1,81 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.sync;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.UUID;
+
+/**
+ * Called after a network synchronisation task has been completed.
+ *
+ * <p>Note: the generic {@link PostSyncEvent} will also be called for {@link SyncType#FULL full syncs}.</p>
+ *
+ * @since 5.5
+ */
+public interface PostNetworkSyncEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the ID of the sync request
+     *
+     * @return the id of the sync request
+     */
+    @Param(0)
+    @NonNull UUID getSyncId();
+
+    /**
+     * Gets the sync type.
+     *
+     * @return the sync type
+     */
+    @Param(1)
+    @NonNull SyncType getType();
+
+    /**
+     * Gets if a sync occurred.
+     *
+     * <p>For {@link SyncType} = {@link SyncType#FULL FULL}, this method always returns true.</p>
+     *
+     * <p>For {@link SyncType} = {@link SyncType#SPECIFIC_USER SPECIFIC_USER}, this method returns true if the
+     * user in question was online/loaded in memory at the time, and false otherwise.</p>
+     *
+     * @return if a sync occurred
+     */
+    @Param(2)
+    boolean didSyncOccur();
+
+    /**
+     * Gets the unique id of the specific user that has been synced, if applicable.
+     *
+     * @return the unique id of the specific user
+     */
+    @Param(3)
+    @Nullable UUID getSpecificUserUniqueId();
+
+}

api/src/main/java/net/luckperms/api/event/sync/PostSyncEvent.java

@@ -28,7 +28,10 @@ package net.luckperms.api.event.sync;
 import net.luckperms.api.event.LuckPermsEvent;
 
 /**
- * Called when an sync task has been completed
+ * Called after a full synchronisation task has been completed.
+ *
+ * <p>Note: this event is also called after synchronisations that were triggered over the network.
+ * In other words, this event will be called in addition to {@link PostNetworkSyncEvent}.</p>
  */
 public interface PostSyncEvent extends LuckPermsEvent {
 

api/src/main/java/net/luckperms/api/event/sync/PreNetworkSyncEvent.java

@@ -28,13 +28,16 @@ package net.luckperms.api.event.sync;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.UUID;
 
 /**
- * Called before a received network sync task runs
+ * Called after a request for synchronisation has been received via the messaging service,
+ * but before it has actually been completed.
+ *
+ * <p>Note: the generic {@link PreSyncEvent} will also be called for {@link SyncType#FULL full syncs}.</p>
  */
 public interface PreNetworkSyncEvent extends LuckPermsEvent, Cancellable {
 
@@ -46,4 +49,22 @@ public interface PreNetworkSyncEvent extends LuckPermsEvent, Cancellable {
     @Param(0)
     @NonNull UUID getSyncId();
 
+    /**
+     * Gets the sync type.
+     *
+     * @return the sync type
+     * @since 5.5
+     */
+    @Param(1)
+    @NonNull SyncType getType();
+
+    /**
+     * Gets the unique id of the specific user that will be synced, if applicable.
+     *
+     * @return the unique id of the specific user
+     * @since 5.5
+     */
+    @Param(2)
+    @Nullable UUID getSpecificUserUniqueId();
+
 }

api/src/main/java/net/luckperms/api/event/sync/PreSyncEvent.java

@@ -29,7 +29,10 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 
 /**
- * Called before a sync task runs
+ * Called just before a full synchronisation task runs.
+ *
+ * <p>Note: this event is also called before synchronisations that were triggered over the network.
+ * In other words, this event will be called in addition to {@link PreNetworkSyncEvent}.</p>
  */
 public interface PreSyncEvent extends LuckPermsEvent, Cancellable {
 

api/src/main/java/net/luckperms/api/event/sync/SyncType.java

@@ -0,0 +1,45 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.sync;
+
+/**
+ * Represents the type of synchronisation task.
+ *
+ * @since 5.5
+ */
+public enum SyncType {
+
+    /**
+     * A full sync will be performed - all groups, users and tracks
+     */
+    FULL,
+
+    /**
+     * Only a specific user will be synced
+     */
+    SPECIFIC_USER
+
+}

api/src/main/java/net/luckperms/api/event/sync/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to {@link net.luckperms.api.LuckPerms#runUpdateTask() sync/update task}s.
+ */
+package net.luckperms.api.event.sync;

api/src/main/java/net/luckperms/api/event/track/TrackCreateEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.cause.CreationCause;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.track.Track;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/track/TrackDeleteEvent.java

@@ -28,7 +28,6 @@ package net.luckperms.api.event.track;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.cause.DeletionCause;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.List;

api/src/main/java/net/luckperms/api/event/track/TrackLoadEvent.java

@@ -28,7 +28,6 @@ package net.luckperms.api.event.track;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.track.Track;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/track/mutate/TrackAddGroupEvent.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.event.track.mutate;
 
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/track/mutate/TrackMutateEvent.java

@@ -28,8 +28,8 @@ package net.luckperms.api.event.track.mutate;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.track.Track;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.List;
 
@@ -52,7 +52,7 @@ public interface TrackMutateEvent extends LuckPermsEvent {
      * @return the data before the change
      */
     @Param(1)
-    @NonNull List<String> getStateBefore();
+    @NonNull @Unmodifiable List<String> getStateBefore();
 
     /**
      * Gets an immutable copy of the tracks data after the change
@@ -60,6 +60,6 @@ public interface TrackMutateEvent extends LuckPermsEvent {
      * @return the data after the change
      */
     @Param(2)
-    @NonNull List<String> getStateAfter();
+    @NonNull @Unmodifiable List<String> getStateAfter();
 
 }

api/src/main/java/net/luckperms/api/event/track/mutate/TrackRemoveGroupEvent.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.event.track.mutate;
 
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/track/mutate/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to changes to a {@link net.luckperms.api.track.Track}s contents.
+ */
+package net.luckperms.api.event.track.mutate;

api/src/main/java/net/luckperms/api/event/track/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to {@link net.luckperms.api.track.Track}s.
+ */
+package net.luckperms.api.event.track;

api/src/main/java/net/luckperms/api/event/type/Cancellable.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.event.type;
 
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.concurrent.atomic.AtomicBoolean;

api/src/main/java/net/luckperms/api/event/type/ResultEvent.java

@@ -0,0 +1,58 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.type;
+
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Represents an event that has a result.
+ *
+ * @param <T> the type of the result
+ * @since 5.3
+ */
+public interface ResultEvent<T> {
+
+    /**
+     * Gets an {@link AtomicReference} containing the result.
+     *
+     * @return the result
+     */
+    @Param(-1)
+    @NonNull AtomicReference<T> result();
+
+    /**
+     * Gets if a result has been set for the event.
+     *
+     * @return if there is a result
+     */
+    default boolean hasResult() {
+        return result().get() != null;
+    }
+
+}

api/src/main/java/net/luckperms/api/event/type/Sourced.java

@@ -27,7 +27,6 @@ package net.luckperms.api.event.type;
 
 import net.luckperms.api.event.source.Source;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/type/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Event abstract types.
+ */
+package net.luckperms.api.event.type;

api/src/main/java/net/luckperms/api/event/user/UserCacheLoadEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.cacheddata.CachedDataManager;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.user.User;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/user/UserDataRecalculateEvent.java

@@ -29,7 +29,6 @@ import net.luckperms.api.cacheddata.CachedDataManager;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.user.User;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/user/UserFirstLoginEvent.java

@@ -27,7 +27,6 @@ package net.luckperms.api.event.user;
 
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;

api/src/main/java/net/luckperms/api/event/user/UserLoadEvent.java

@@ -28,7 +28,6 @@ package net.luckperms.api.event.user;
 import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.user.User;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/event/user/UserUnloadEvent.java

@@ -0,0 +1,49 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.event.user;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.model.user.User;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a user is about to be unloaded from memory.
+ *
+ * @since 5.3
+ */
+public interface UserUnloadEvent extends LuckPermsEvent, Cancellable {
+
+    /**
+     * Gets the user that is being unloaded
+     *
+     * @return the user that is being unloaded
+     */
+    @Param(0)
+    @NonNull User getUser();
+
+}

api/src/main/java/net/luckperms/api/event/user/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to {@link net.luckperms.api.model.user.User}s.
+ */
+package net.luckperms.api.event.user;

api/src/main/java/net/luckperms/api/event/user/track/UserTrackEvent.java

@@ -30,7 +30,6 @@ import net.luckperms.api.event.type.Sourced;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.track.Track;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Optional;

api/src/main/java/net/luckperms/api/event/user/track/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Events relating to a {@link net.luckperms.api.model.user.User}s movement on a
+ * {@link net.luckperms.api.track.Track}.
+ */
+package net.luckperms.api.event.user.track;

api/src/main/java/net/luckperms/api/event/util/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+/**
+ * Event utilities.
+ */
+package net.luckperms.api.event.util;