Release API v5.5

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

.gitattributes

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

.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: Build Gradle and Publish Docker image
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'master'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-gradle:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Run build and tests with Gradle wrapper
+        run: ./gradlew test build -PdockerTests
+
+      - name: Publish test report
+        uses: mikepenz/action-junit-report@v5
+        if: success() || failure()
+        with:
+          report_paths: '**/build/test-results/test/TEST-*.xml'
+          annotate_notice: true
+          detailed_summary: true
+
+      - name: Upload all artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: jars
+          path: |
+            bukkit/loader/build/libs/LuckPerms-Bukkit-*.jar
+            bukkit-legacy/loader/build/libs/LuckPerms-Bukkit-Legacy-*.jar
+            bungee/loader/build/libs/LuckPerms-Bungee-*.jar
+            sponge/loader/build/libs/LuckPerms-Sponge-*.jar
+            nukkit/loader/build/libs/LuckPerms-Nukkit-*.jar
+            velocity/build/libs/LuckPerms-Velocity-*.jar
+            fabric/build/libs/LuckPerms-Fabric-*.jar
+            forge/loader/build/libs/LuckPerms-Forge-*.jar
+            standalone/loader/build/libs/LuckPerms-Standalone-*.jar
+
+      - name: Upload standalone artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: standalone-binary
+          path: standalone/loader/build/libs/LuckPerms-Standalone-*.jar
+
+
+  build-docker:
+    needs: build-gradle
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Retrieve saved standalone jar artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: standalone-binary
+          path: standalone/docker/
+
+      - name: Remove version number from jar artifact name
+        run: mv standalone/docker/LuckPerms-Standalone-*.jar standalone/docker/luckperms-standalone.jar
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine the LuckPerms version
+        run: |
+          echo "luckperms_version=$(git describe --tags | awk -F "-" '{print $1 "." $2}')" >> "$GITHUB_ENV"
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          flavor: |
+            latest=${{ github.ref == 'refs/heads/master' }}
+          tags: |
+            type=schedule
+            type=ref,event=branch
+            type=ref,event=tag
+            type=ref,event=pr
+            type=raw,enable=${{ github.ref == 'refs/heads/master' }},value=${{ env.luckperms_version }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: standalone/docker/
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

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

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Before reporting a bug or issue, please make sure that the issue is actually bei
 
 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).
+Bugs or issues should be reported using the [GitHub Issues tab](https://github.com/LuckPerms/LuckPerms/issues).
 
 ### :pencil: Want to contribute code?
 #### Pull Requests
@@ -23,4 +23,4 @@ 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 & Fabric** - 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.

README.md

@@ -24,18 +24,24 @@ For more information, see the wiki article on [Why LuckPerms?](https://luckperms
 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 `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
 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!)
@@ -47,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, Fabric, 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,9 +1,15 @@
 group = 'net.luckperms'
-project.version = '5.3'
+project.version = '5.5'
+
+jar {
+    manifest {
+        attributes('Automatic-Module-Name': 'net.luckperms.api')
+    }
+}
 
 dependencies {
-    compileOnly 'org.checkerframework:checker-qual:3.12.0'
-    compileOnly 'org.jetbrains:annotations:20.1.0'
+    compileOnly 'org.checkerframework:checker-qual:3.49.3'
+    compileOnly 'org.jetbrains:annotations:26.0.2'
 }
 
 // Only used occasionally for deployment - not needed for normal builds.
@@ -18,36 +24,21 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass
         options.charSet = 'UTF-8'
         options.links(
                 'https://checkerframework.org/api/',
-                'https://javadoc.io/static/org.jetbrains/annotations/20.1.0/'
+                'https://javadoc.io/static/org.jetbrains/annotations/26.0.2/'
         )
         options.addStringOption('Xdoclint:none', '-quiet')
+        options.addStringOption('-since', '5.0,5.1,5.2,5.3,5.4,5.5')
 
         if (JavaVersion.current() > JavaVersion.VERSION_1_8) {
-            options.addBooleanOption('-no-module-directories', true)
-            options.links.add('https://docs.oracle.com/en/java/javase/11/docs/api/')
+            options.links.add('https://docs.oracle.com/en/java/javase/21/docs/api/')
         } else {
             options.links.add('https://docs.oracle.com/javase/8/docs/api/')
         }
     }
 
-    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
+    java {
+        withJavadocJar()
+        withSourcesJar()
     }
 
     publishing {
@@ -69,48 +60,47 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass
                 artifactId = 'api'
 
                 from components.java
-                artifact sourcesJar
-                artifact javadocJar
 
                 pom {
-                    name 'LuckPerms API'
-                    description 'A permissions plugin for Minecraft servers.'
-                    url 'https://luckperms.net'
+                    name = 'LuckPerms API'
+                    description = 'A permissions manager for Minecraft servers.'
+                    url = 'https://luckperms.net'
 
                     licenses {
                         license {
-                            name 'MIT'
-                            url 'https://opensource.org/licenses/MIT'
+                            name = 'MIT'
+                            url = 'https://opensource.org/licenses/MIT'
                         }
                     }
 
                     developers {
                         developer {
-                            id 'lucko'
-                            name 'Luck'
-                            url 'https://lucko.me'
-                            email 'git@lucko.me'
+                            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'
+                        connection = 'scm:git:https://github.com/LuckPerms/LuckPerms.git'
+                        developerConnection = 'scm:git:git@github.com:LuckPerms/LuckPerms.git'
+                        url = 'https://github.com/LuckPerms/LuckPerms'
                     }
 
                     issueManagement {
-                        system 'GitHub'
-                        url 'https://github.com/lucko/LuckPerms/issues'
+                        system = 'GitHub'
+                        url = 'https://github.com/LuckPerms/LuckPerms/issues'
                     }
                 }
             }
         }
     }
+
+    signing {
+        useGpgCmd()
+        sign publishing.publications.mavenJava
+        required = true
+    }
 }
 */

api/javadoc/overview.html

@@ -1,6 +1,6 @@
 <body>
 <p>
-    LuckPerms is a permissions plugin for Minecraft servers. It allows server admins to control what
+    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>
@@ -8,10 +8,11 @@
     <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 under
+    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>

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,13 +41,13 @@ 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;
 
@@ -220,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.
      *
@@ -256,4 +268,14 @@ public interface LuckPerms {
     @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

@@ -79,7 +79,8 @@ public final class LuckPermsProvider {
                 "  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";
+                "     (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

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

@@ -25,6 +25,7 @@
 
 package net.luckperms.api.actionlog;
 
+import net.luckperms.api.actionlog.filter.ActionFilter;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.Unmodifiable;
 
@@ -40,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 {
 
     /**

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/cacheddata/CachedData.java

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

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;

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

@@ -29,7 +29,7 @@ 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;
@@ -177,6 +177,30 @@ public interface CachedMetaData extends CachedData {
         return querySuffix().result();
     }
 
+    /**
+     * Query for a weight.
+     *
+     * <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 Result<Integer, WeightNode> queryWeight();
+
+    /**
+     * 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}.
      *

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

@@ -27,7 +27,6 @@ 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;
 

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

@@ -26,7 +26,6 @@
 package net.luckperms.api.cacheddata;
 
 import net.luckperms.api.node.Node;
-
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**

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

@@ -28,7 +28,6 @@ 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;
 

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;

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;

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/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/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/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/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/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,7 +27,6 @@ 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;
 

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

@@ -27,7 +27,6 @@ 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;
 

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

@@ -32,7 +32,6 @@ 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;
 

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

@@ -27,7 +27,6 @@ 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;
 

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

@@ -28,7 +28,6 @@ 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;

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

@@ -28,7 +28,6 @@ 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;
 

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

@@ -28,7 +28,6 @@ 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;
 

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

@@ -27,7 +27,6 @@ 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;

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/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/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,7 +28,6 @@ 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;
 

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/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

@@ -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.AtomicReference;

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/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

@@ -29,7 +29,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.model.user.User;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

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/messaging/MessagingService.java

@@ -26,12 +26,12 @@
 package net.luckperms.api.messaging;
 
 import net.luckperms.api.LuckPerms;
+import net.luckperms.api.event.messaging.CustomMessageReceiveEvent;
 import net.luckperms.api.model.user.User;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A means to push changes to other servers using the platforms networking
+ * A means to send messages to other servers using the platforms networking
  */
 public interface MessagingService {
 
@@ -72,4 +72,44 @@ public interface MessagingService {
      */
     void pushUserUpdate(@NonNull User user);
 
+    /**
+     * Uses the messaging service to send a message with a custom payload.
+     *
+     * <p>The intended use case of this functionality is to allow plugins/mods
+     * to send <b>lightweight</b> and <b>permissions-related</b> custom messages
+     * between instances, piggy-backing on top of the messenger abstraction
+     * already built into LuckPerms.</p>
+     *
+     * <p>It is <b>not</b> intended as a full message broker replacement/abstraction.
+     * Note that some of the messenger implementations in LuckPerms cannot handle
+     * a high volume of messages being sent (for example the SQL messenger).
+     * Additionally, some implementations do not give any guarantees that a message
+     * will be delivered on time or even at all (for example the plugin message
+     * messengers).</p>
+     *
+     * <p>With all of that in mind, please consider that if you are using this
+     * functionality to send messages that have nothing to do with LuckPerms or
+     * permissions, or that require guarantees around delivery reliability, you
+     * are most likely misusing the API and would be better off building your own
+     * integration with a message broker.</p>
+     *
+     * <p>Whilst there is (currently) no strict validation, it is recommended
+     * that the channel id should use the same format as Minecraft resource locations /
+     * namespaced keys. For example, a plugin called "SuperRanks" sending rank-up
+     * notifications using custom payload messages might use the channel id
+     * {@code "superranks:notifications"} for this purpose.</p>
+     *
+     * <p>The payload can be any valid UTF-8 string.</p>
+     *
+     * <p>The message will be delivered asynchronously.</p>
+     *
+     * <p>Other LuckPerms instances that receive the message will publish it to API
+     * consumers using the {@link CustomMessageReceiveEvent}.</p>
+     *
+     * @param channelId the channel id
+     * @param payload the message payload
+     * @since 5.5
+     */
+    void sendCustomMessage(@NonNull String channelId, @NonNull String payload);
+
 }

api/src/main/java/net/luckperms/api/messenger/IncomingMessageConsumer.java

@@ -27,7 +27,6 @@ package net.luckperms.api.messenger;
 
 import net.luckperms.api.messenger.message.Message;
 import net.luckperms.api.messenger.message.OutgoingMessage;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.NonExtendable;
 

api/src/main/java/net/luckperms/api/messenger/Messenger.java

@@ -27,7 +27,6 @@ package net.luckperms.api.messenger;
 
 import net.luckperms.api.messenger.message.Message;
 import net.luckperms.api.messenger.message.OutgoingMessage;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.OverrideOnly;
 

api/src/main/java/net/luckperms/api/messenger/MessengerProvider.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.messenger;
 
 import net.luckperms.api.LuckPerms;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.OverrideOnly;
 

api/src/main/java/net/luckperms/api/messenger/message/Message.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.messenger.message;
 
 import net.luckperms.api.messenger.Messenger;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.NonExtendable;
 

api/src/main/java/net/luckperms/api/messenger/message/OutgoingMessage.java

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

api/src/main/java/net/luckperms/api/messenger/message/type/ActionLogMessage.java

@@ -27,7 +27,6 @@ package net.luckperms.api.messenger.message.type;
 
 import net.luckperms.api.actionlog.Action;
 import net.luckperms.api.messenger.message.Message;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/messenger/message/type/CustomMessage.java

@@ -0,0 +1,56 @@
+/*
+ * 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.messenger.message.type;
+
+import net.luckperms.api.messenger.message.Message;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents a "custom payload" message.
+ *
+ * <p>Used by API consumers to send custom messages between servers.</p>
+ *
+ * @see net.luckperms.api.messaging.MessagingService#sendCustomMessage(String, String)
+ * @see net.luckperms.api.event.messaging.CustomMessageReceiveEvent
+ * @since 5.5
+ */
+public interface CustomMessage extends Message {
+
+    /**
+     * Gets the channel identifier.
+     *
+     * @return the namespace
+     */
+    @NonNull String getChannelId();
+
+    /**
+     * Gets the payload.
+     *
+     * @return the payload
+     */
+    @NonNull String getPayload();
+
+}

api/src/main/java/net/luckperms/api/messenger/message/type/UserUpdateMessage.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.messenger.message.type;
 
 import net.luckperms.api.messenger.message.Message;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;

api/src/main/java/net/luckperms/api/metastacking/MetaStackDefinition.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.metastacking;
 
 import net.luckperms.api.query.OptionKey;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.Unmodifiable;
 

api/src/main/java/net/luckperms/api/metastacking/MetaStackElement.java

@@ -27,7 +27,6 @@ package net.luckperms.api.metastacking;
 
 import net.luckperms.api.node.ChatMetaType;
 import net.luckperms.api.node.types.ChatMetaNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 

api/src/main/java/net/luckperms/api/model/PermissionHolder.java

@@ -35,7 +35,6 @@ import net.luckperms.api.node.Node;
 import net.luckperms.api.node.NodeType;
 import net.luckperms.api.query.Flag;
 import net.luckperms.api.query.QueryOptions;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.Unmodifiable;
 

api/src/main/java/net/luckperms/api/model/PlayerSaveResult.java

@@ -26,7 +26,6 @@
 package net.luckperms.api.model;
 
 import net.luckperms.api.model.user.UserManager;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.jetbrains.annotations.Unmodifiable;

api/src/main/java/net/luckperms/api/model/data/DataMutateResult.java

@@ -29,7 +29,6 @@ import net.luckperms.api.model.PermissionHolder;
 import net.luckperms.api.node.Node;
 import net.luckperms.api.track.Track;
 import net.luckperms.api.util.Result;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/model/data/NodeMap.java

@@ -35,7 +35,6 @@ import net.luckperms.api.model.user.UserManager;
 import net.luckperms.api.node.Node;
 import net.luckperms.api.node.NodeEqualityPredicate;
 import net.luckperms.api.util.Tristate;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.Unmodifiable;
 

api/src/main/java/net/luckperms/api/model/group/Group.java

@@ -27,7 +27,6 @@ package net.luckperms.api.model.group;
 
 import net.luckperms.api.model.PermissionHolder;
 import net.luckperms.api.query.QueryOptions;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 

api/src/main/java/net/luckperms/api/model/group/GroupManager.java

@@ -28,7 +28,6 @@ package net.luckperms.api.model.group;
 import net.luckperms.api.node.HeldNode;
 import net.luckperms.api.node.Node;
 import net.luckperms.api.node.matcher.NodeMatcher;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.jetbrains.annotations.Unmodifiable;

api/src/main/java/net/luckperms/api/model/user/User.java

@@ -27,7 +27,6 @@ package net.luckperms.api.model.user;
 
 import net.luckperms.api.model.PermissionHolder;
 import net.luckperms.api.model.data.DataMutateResult;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 

api/src/main/java/net/luckperms/api/model/user/UserManager.java

@@ -29,7 +29,6 @@ import net.luckperms.api.model.PlayerSaveResult;
 import net.luckperms.api.node.HeldNode;
 import net.luckperms.api.node.Node;
 import net.luckperms.api.node.matcher.NodeMatcher;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.jetbrains.annotations.Unmodifiable;

api/src/main/java/net/luckperms/api/node/ChatMetaType.java

@@ -28,7 +28,6 @@ package net.luckperms.api.node;
 import net.luckperms.api.node.types.ChatMetaNode;
 import net.luckperms.api.node.types.PrefixNode;
 import net.luckperms.api.node.types.SuffixNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Locale;

api/src/main/java/net/luckperms/api/node/HeldNode.java

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

api/src/main/java/net/luckperms/api/node/Node.java

@@ -36,7 +36,6 @@ import net.luckperms.api.node.types.PrefixNode;
 import net.luckperms.api.node.types.RegexPermissionNode;
 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.ApiStatus.NonExtendable;

api/src/main/java/net/luckperms/api/node/NodeBuilder.java

@@ -27,7 +27,6 @@ package net.luckperms.api.node;
 
 import net.luckperms.api.context.ContextSet;
 import net.luckperms.api.node.metadata.NodeMetadataKey;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.jetbrains.annotations.ApiStatus.NonExtendable;

api/src/main/java/net/luckperms/api/node/NodeBuilderRegistry.java

@@ -33,7 +33,6 @@ import net.luckperms.api.node.types.PrefixNode;
 import net.luckperms.api.node.types.RegexPermissionNode;
 import net.luckperms.api.node.types.SuffixNode;
 import net.luckperms.api.node.types.WeightNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.Internal;
 

api/src/main/java/net/luckperms/api/node/NodeType.java

@@ -34,7 +34,6 @@ import net.luckperms.api.node.types.PrefixNode;
 import net.luckperms.api.node.types.RegexPermissionNode;
 import net.luckperms.api.node.types.SuffixNode;
 import net.luckperms.api.node.types.WeightNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Objects;

api/src/main/java/net/luckperms/api/node/matcher/NodeMatcher.java

@@ -30,7 +30,6 @@ import net.luckperms.api.node.Node;
 import net.luckperms.api.node.NodeEqualityPredicate;
 import net.luckperms.api.node.NodeType;
 import net.luckperms.api.node.types.MetaNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.NonExtendable;
 

api/src/main/java/net/luckperms/api/node/matcher/NodeMatcherFactory.java

@@ -29,7 +29,6 @@ import net.luckperms.api.node.Node;
 import net.luckperms.api.node.NodeEqualityPredicate;
 import net.luckperms.api.node.NodeType;
 import net.luckperms.api.node.types.MetaNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.Internal;
 

api/src/main/java/net/luckperms/api/node/metadata/types/InheritanceOriginMetadata.java

@@ -29,7 +29,6 @@ import net.luckperms.api.model.PermissionHolder;
 import net.luckperms.api.model.data.DataType;
 import net.luckperms.api.node.Node;
 import net.luckperms.api.node.metadata.NodeMetadataKey;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.NonExtendable;
 

api/src/main/java/net/luckperms/api/node/types/ChatMetaNode.java

@@ -28,7 +28,6 @@ package net.luckperms.api.node.types;
 import net.luckperms.api.node.ChatMetaType;
 import net.luckperms.api.node.NodeBuilder;
 import net.luckperms.api.node.ScopedNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**

api/src/main/java/net/luckperms/api/node/types/DisplayNameNode.java

@@ -30,7 +30,6 @@ import net.luckperms.api.node.Node;
 import net.luckperms.api.node.NodeBuilder;
 import net.luckperms.api.node.NodeType;
 import net.luckperms.api.node.ScopedNode;
-
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
@@ -64,6 +63,7 @@ public interface DisplayNameNode extends ScopedNode<DisplayNameNode, DisplayName
      *
      * @param displayName the display name to set
      * @return the builder
+     * @throws IllegalArgumentException if {@code displayName} is empty
      */
     static @NonNull Builder builder(@NonNull String displayName) {
         return builder().displayName(displayName);
@@ -79,6 +79,7 @@ public interface DisplayNameNode extends ScopedNode<DisplayNameNode, DisplayName
          *
          * @param displayName the display name
          * @return the builder
+         * @throws IllegalArgumentException if {@code displayName} is empty
          */
         @NonNull Builder displayName(@NonNull String displayName);