Fix Fabric placeholders throwing when resolved without a player (#4321 )

Make the first-time setup suggested command clickable to copy (#4337 )
Update to Hytale Update 7
2026-11-04 08:42:04 -05:00 · 2026-11-01 14:42:10 +00:00 · 2026-11-01 14:23:57 +00:00 · 2026-10-20 21:28:14 +01:00 · 2026-10-04 16:51:35 +01:00 · 2026-10-04 16:49:40 +01:00
1087 changed files with 47345 additions and 11588 deletions
@@ -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
@@ -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. -->
-
@@ -0,0 +1,63 @@
+name: 🐛  Bug report
+description: Report an issue or problem with the way LuckPerms is functioning.
+labels: ["type: issue"]
+body:
+  - type: markdown
+    attributes:
+      value: "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"
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please provide a short description of the issue in the space below.
+      placeholder: Description goes here!
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Reproduction Steps
+      description: Please provide a clear list of steps we should follow in order to reproduce your issue in the space below.
+      placeholder: List reproduction steps here, please!
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behaviour
+    attributes:
+      label: Expected Behaviour
+      description: Please provide a description of what you expected to happen.
+      placeholder: Describe what you expected to happen here.
+    validations:
+      required: true
+  - type: input
+    id: server-info
+    attributes:
+      label: Server Details
+      description: Please provide a description of the server details, including type and specific version number.
+      placeholder: 'git-Paper-124 (MC: 1.17.1)'
+    validations:
+      required: true
+  - type: input
+    id: luckperms-version
+    attributes:
+      label: LuckPerms Version
+      description: Please provide the specific, precise version number of LuckPerms you are using to reproduce this bug.
+      placeholder: v5.3.70
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs and Configs
+      description: 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. 
+      placeholder: https://gist.github.com/HelpfulBugReporter/ThisIsAVeryUsefulLogOutput
+    validations:
+      required: false
+  - type: textarea
+    id: extra-info
+    attributes:
+      label: Extra Details
+      description: Please include any other relevant details in the space below.
+      placeholder: I was able to reproduce this only at the end of a rainbow.
+    validations:
+      required: false
@@ -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. -->
-
@@ -0,0 +1,31 @@
+name: 💡  Suggestion
+description: Suggest an idea for an improvement or change to LuckPerms.
+labels: ["type: suggestion"]
+body:
+  - type: markdown
+    attributes:
+      value: "Before going any further, please check to see if your suggestion has already been added by checking the [wiki](https://luckperms.net/wiki/Home). The latest development builds can be obtained from https://luckperms.net/download"
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please provide a short description of your suggestion in the space below.
+      placeholder: Hello, perhaps you should...
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-behaviour
+    attributes:
+      label: Proposed Behaviour
+      description: Please provide a short explanation of how the feature should work / be changed, and how this will affect the project.
+      placeholder: It would...
+    validations:
+      required: true
+  - type: textarea
+    id: extra-info
+    attributes:
+      label: Extra Details
+      description: Please include any other relevant details in the space below.
+      placeholder: I think this should only function at the end of a rainbow.
+    validations:
+      required: false
@@ -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: '25'
+
+      - 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 }}
@@ -1,3 +1,6 @@
+### LuckPerms Standalone ###
+standalone/loader/data/
+
 ### Gradle & IntelliJ ###
 .gradle/
 /.idea/
@@ -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.
@@ -1,4 +1,4 @@
-![](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)
@@ -24,17 +24,23 @@ 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 `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
@@ -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.
@@ -1,9 +1,21 @@
+apply plugin: 'java-library'
+
 group = 'net.luckperms'
-project.version = '5.3'
+project.version = '5.5'
+
+tasks.withType(JavaCompile).configureEach {
+    options.release = 8
+}
+
+jar {
+    manifest {
+        attributes('Automatic-Module-Name': 'net.luckperms.api')
+    }
+}

 dependencies {
-    compileOnly 'org.checkerframework:checker-qual:3.8.0'
-    compileOnly 'org.jetbrains:annotations:20.1.0'
+    api 'org.jspecify:jspecify:1.0.0'
+    compileOnlyApi 'org.jetbrains:annotations:26.1.0'
 }

 // Only used occasionally for deployment - not needed for normal builds.
@@ -17,87 +29,84 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass
        options.encoding = 'UTF-8'
        options.charSet = 'UTF-8'
        options.links(
-                'https://docs.oracle.com/javase/8/docs/api/',
-                'https://checkerframework.org/api/',
-                'https://javadoc.io/static/org.jetbrains/annotations/20.1.0/'
+                'https://jspecify.dev/docs/api/',
+                '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.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
+    java {
+        withJavadocJar()
+        withSourcesJar()
    }

-    task sourcesJar(type: Jar) {
-        classifier 'sources'
-        from sourceSets.main.allSource
-    }
-
-    artifacts {
-        archives javadocJar
-        archives sourcesJar
-    }
-
-    signing {
-        useGpgCmd()
-        sign configurations.archives
-    }
-
-    uploadArchives {
+    publishing {
        repositories {
-            mavenDeployer {
-                beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) }
+            maven {
+                def releasesRepoUrl = 'https://oss.sonatype.org/service/local/staging/deploy/maven2/'
+                def snapshotsRepoUrl = 'https://oss.sonatype.org/content/repositories/snapshots/'
+                url = version.endsWith('SNAPSHOT') ? snapshotsRepoUrl : releasesRepoUrl

-                repository(url: 'https://oss.sonatype.org/service/local/staging/deploy/maven2/') {
-                    authentication(userName: sonatypeUsername, password: sonatypePassword)
+                credentials {
+                    username sonatypeUsername
+                    password sonatypePassword
                }
+            }
+        }

-                snapshotRepository(url: 'https://oss.sonatype.org/content/repositories/snapshots/') {
-                    authentication(userName: sonatypeUsername, password: sonatypePassword)
-                }
+        publications {
+            mavenJava(MavenPublication) {
+                artifactId = 'api'
+
+                from components.java

                pom {
-                    project {
-                        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'
-                            }
+                    licenses {
+                        license {
+                            name = 'MIT'
+                            url = 'https://opensource.org/licenses/MIT'
                        }
+                    }

-                        developers {
-                            developer {
-                                id 'lucko'
-                                name 'Luck'
-                                url 'https://lucko.me'
-                                email 'git@lucko.me'
-                            }
+                    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'
-                        }
+                    scm {
+                        connection = 'scm:git:https://github.com/LuckPerms/LuckPerms.git'
+                        developerConnection = 'scm:git:git@github.com:LuckPerms/LuckPerms.git'
+                        url = 'https://github.com/LuckPerms/LuckPerms'
+                    }

-                        ciManagement {
-                            system 'Jenkins'
-                            url 'https://ci.lucko.me/job/LuckPerms'
-                        }
-
-                        issueManagement {
-                            system 'GitHub'
-                            url 'https://github.com/lucko/LuckPerms/issues'
-                        }
+                    issueManagement {
+                        system = 'GitHub'
+                        url = 'https://github.com/LuckPerms/LuckPerms/issues'
                    }
                }
            }
        }
    }
+
+    signing {
+        useGpgCmd()
+        sign publishing.publications.mavenJava
+        required = true
+    }
 }
 */
@@ -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>
@@ -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,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;

 import java.util.Optional;
@@ -83,18 +83,18 @@ public interface LuckPerms {
     *
     * @return the server name
     */
-    @NonNull String getServerName();
+    String getServerName();

    /**
     * Gets the {@link UserManager}, responsible for managing
     * {@link User} instances.
     *
-     * <p>This manager can be used to retrieve instances of {@link User} by uuid
+     * <p>This manager can be used to retrieve instances of {@link User} by UUID
     * or name, or query all loaded users.</p>
     *
     * @return the user manager
     */
-    @NonNull UserManager getUserManager();
+    UserManager getUserManager();

    /**
     * Gets the {@link GroupManager}, responsible for managing
@@ -105,7 +105,7 @@ public interface LuckPerms {
     *
     * @return the group manager
     */
-    @NonNull GroupManager getGroupManager();
+    GroupManager getGroupManager();

    /**
     * Gets the {@link TrackManager}, responsible for managing
@@ -116,7 +116,7 @@ public interface LuckPerms {
     *
     * @return the track manager
     */
-    @NonNull TrackManager getTrackManager();
+    TrackManager getTrackManager();

    /**
     * Gets the {@link PlayerAdapter} instance, a utility class for adapting platform Player
@@ -143,7 +143,7 @@ public interface LuckPerms {
     * @throws IllegalArgumentException if the player class is not correct
     * @since 5.1
     */
-    <T> @NonNull PlayerAdapter<T> getPlayerAdapter(@NonNull Class<T> playerClass);
+    <T> PlayerAdapter<T> getPlayerAdapter(Class<T> playerClass);

    /**
     * Gets the {@link Platform}, which represents the server platform the
@@ -151,7 +151,7 @@ public interface LuckPerms {
     *
     * @return the platform
     */
-    @NonNull Platform getPlatform();
+    Platform getPlatform();

    /**
     * Gets the {@link PluginMetadata}, responsible for providing metadata about
@@ -159,7 +159,7 @@ public interface LuckPerms {
     *
     * @return the plugin metadata
     */
-    @NonNull PluginMetadata getPluginMetadata();
+    PluginMetadata getPluginMetadata();

    /**
     * Gets the {@link EventBus}, used for subscribing to internal LuckPerms
@@ -167,7 +167,7 @@ public interface LuckPerms {
     *
     * @return the event bus
     */
-    @NonNull EventBus getEventBus();
+    EventBus getEventBus();

    /**
     * Gets the {@link MessagingService}, used to dispatch updates throughout a
@@ -178,7 +178,7 @@ public interface LuckPerms {
     *
     * @return the messaging service instance, if present.
     */
-    @NonNull Optional<MessagingService> getMessagingService();
+    Optional<MessagingService> getMessagingService();

    /**
     * Gets the {@link ActionLogger}, responsible for saving and broadcasting
@@ -186,7 +186,7 @@ public interface LuckPerms {
     *
     * @return the action logger
     */
-    @NonNull ActionLogger getActionLogger();
+    ActionLogger getActionLogger();

    /**
     * Gets the {@link ContextManager}, responsible for managing
@@ -194,7 +194,7 @@ public interface LuckPerms {
     *
     * @return the context manager
     */
-    @NonNull ContextManager getContextManager();
+    ContextManager getContextManager();

    /**
     * Gets the {@link MetaStackFactory}.
@@ -205,7 +205,7 @@ public interface LuckPerms {
     *
     * @return the meta stack factory
     */
-    @NonNull MetaStackFactory getMetaStackFactory();
+    MetaStackFactory getMetaStackFactory();

    /**
     * Schedules the execution of an update task, and returns an encapsulation
@@ -218,7 +218,18 @@ public interface LuckPerms {
     *
     * @return a future
     */
-    @NonNull CompletableFuture<Void> runUpdateTask();
+    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
+     */
+    Health runHealthCheck();

    /**
     * Registers a {@link MessengerProvider} for use by the platform.
@@ -228,7 +239,7 @@ public interface LuckPerms {
     *
     * @param messengerProvider the messenger provider.
     */
-    void registerMessengerProvider(@NonNull MessengerProvider messengerProvider);
+    void registerMessengerProvider(MessengerProvider messengerProvider);

    /**
     * Gets the {@link NodeBuilderRegistry}.
@@ -236,7 +247,7 @@ public interface LuckPerms {
     * @return the node builder registry
     */
    @Internal
-    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
+    NodeBuilderRegistry getNodeBuilderRegistry();

    /**
     * Gets the {@link QueryOptionsRegistry}.
@@ -245,7 +256,7 @@ public interface LuckPerms {
     * @since 5.1
     */
    @Internal
-    @NonNull QueryOptionsRegistry getQueryOptionsRegistry();
+    QueryOptionsRegistry getQueryOptionsRegistry();

    /**
     * Gets the {@link NodeMatcherFactory}.
@@ -254,6 +265,15 @@ public interface LuckPerms {
     * @since 5.1
     */
    @Internal
-    @NonNull NodeMatcherFactory getNodeMatcherFactory();
+    NodeMatcherFactory getNodeMatcherFactory();
+
+    /**
+     * Gets the {@link ActionFilterFactory}.
+     *
+     * @return the action filter factory
+     * @since 5.5
+     */
+    @Internal
+    ActionFilterFactory getActionFilterFactory();

 }
@@ -25,7 +25,7 @@

 package net.luckperms.api;

-import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jspecify.annotations.Nullable;

 import static org.jetbrains.annotations.ApiStatus.Internal;

@@ -36,7 +36,7 @@ import static org.jetbrains.annotations.ApiStatus.Internal;
 * instance, however, this provider can be used if this is not viable.</p>
 */
 public final class LuckPermsProvider {
-    private static LuckPerms instance = null;
+    private static @Nullable LuckPerms instance = null;

    /**
     * Gets an instance of the {@link LuckPerms} API,
@@ -47,7 +47,8 @@ public final class LuckPermsProvider {
     * @return an instance of the LuckPerms API
     * @throws IllegalStateException if the API is not loaded yet
     */
-    public static @NonNull LuckPerms get() {
+    public static LuckPerms get() {
+        LuckPerms instance = LuckPermsProvider.instance;
        if (instance == null) {
            throw new NotLoadedException();
        }
@@ -76,9 +77,10 @@ public final class LuckPermsProvider {
        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) your plugin does not declare a dependency on LuckPerms\n" +
-                "  c) you are attempting to use the API before plugins reach the 'enable' phase\n" +
-                "     (call the #get method in onEnable, not in your plugin constructor!)\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);
@@ -26,9 +26,8 @@
 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 org.jspecify.annotations.Nullable;

 import java.time.Instant;
 import java.util.Optional;
@@ -36,7 +35,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> {

    /**
@@ -44,7 +46,7 @@ public interface Action extends Comparable<Action> {
     *
     * @return a new builder
     */
-    static @NonNull Builder builder() {
+    static Builder builder() {
        return LuckPermsProvider.get().getActionLogger().actionBuilder();
    }

@@ -53,21 +55,21 @@ public interface Action extends Comparable<Action> {
     *
     * @return the timestamp
     */
-    @NonNull Instant getTimestamp();
+    Instant getTimestamp();

    /**
     * Gets the source of the action.
     *
     * @return the source
     */
-    @NonNull Source getSource();
+    Source getSource();

    /**
     * Gets the target of the action.
     *
     * @return the target
     */
-    @NonNull Target getTarget();
+    Target getTarget();

    /**
     * Returns a string describing the action which took place.
@@ -77,11 +79,12 @@ public interface Action extends Comparable<Action> {
     *
     * @return the action
     */
-    @NonNull String getDescription();
+    String getDescription();

    /**
     * Represents the source of an action.
     */
+    @NonExtendable
    interface Source {

        /**
@@ -89,20 +92,21 @@ public interface Action extends Comparable<Action> {
         *
         * @return the source unique id
         */
-        @NonNull UUID getUniqueId();
+        UUID getUniqueId();

        /**
         * Gets the source name.
         *
         * @return the source name
         */
-        @NonNull String getName();
+        String getName();

    }

    /**
     * Represents the target of an action.
     */
+    @NonExtendable
    interface Target {

        /**
@@ -110,24 +114,24 @@ public interface Action extends Comparable<Action> {
         *
         * @return the target unique id
         */
-        @NonNull Optional<UUID> getUniqueId();
+        Optional<UUID> getUniqueId();

        /**
         * Gets the target name.
         *
         * @return the target name
         */
-        @NonNull String getName();
+        String getName();

        /**
         * Gets the target type.
         *
         * @return the target type
         */
-        @NonNull Type getType();
+        Type getType();

        /**
-         * Represents the type of a {@link Target}.
+         * Represents the type of {@link Target}.
         */
        enum Type {
            USER, GROUP, TRACK
@@ -146,7 +150,7 @@ public interface Action extends Comparable<Action> {
         * @return the builder
         * @see Action#getTimestamp()
         */
-        @NonNull Builder timestamp(@NonNull Instant timestamp);
+        Builder timestamp(Instant timestamp);

        /**
         * Sets the actor of the entry.
@@ -154,7 +158,7 @@ public interface Action extends Comparable<Action> {
         * @param actor the actor
         * @return the builder
         */
-        @NonNull Builder source(@NonNull UUID actor);
+        Builder source(UUID actor);

        /**
         * Sets the actor name of the entry.
@@ -162,7 +166,7 @@ public interface Action extends Comparable<Action> {
         * @param actorName the actor name
         * @return the builder
         */
-        @NonNull Builder sourceName(@NonNull String actorName);
+        Builder sourceName(String actorName);

        /**
         * Sets the type of the entry.
@@ -170,7 +174,7 @@ public interface Action extends Comparable<Action> {
         * @param type the type
         * @return the builder
         */
-        @NonNull Builder targetType(Action.Target.Type type);
+        Builder targetType(Target.Type type);

        /**
         * Sets the acted object for the entry.
@@ -178,7 +182,7 @@ public interface Action extends Comparable<Action> {
         * @param acted the acted object
         * @return the builder
         */
-        @NonNull Builder target(@Nullable UUID acted);
+        Builder target(@Nullable UUID acted);

        /**
         * Sets the acted name for the entry.
@@ -186,7 +190,7 @@ public interface Action extends Comparable<Action> {
         * @param actedName the acted name
         * @return the builder
         */
-        @NonNull Builder targetName(@NonNull String actedName);
+        Builder targetName(String actedName);

        /**
         * Sets the action of the entry.
@@ -194,14 +198,14 @@ public interface Action extends Comparable<Action> {
         * @param action the action
         * @return the builder
         */
-        @NonNull Builder description(@NonNull String action);
+        Builder description(String action);

        /**
         * Creates a {@link Action} instance from the builder.
         *
         * @return a new log entry instance
         */
-        @NonNull Action build();
+        Action build();

    }

@@ -25,7 +25,7 @@

 package net.luckperms.api.actionlog;

-import org.checkerframework.checker.nullness.qual.NonNull;
+import net.luckperms.api.actionlog.filter.ActionFilter;
 import org.jetbrains.annotations.Unmodifiable;

 import java.util.SortedSet;
@@ -40,7 +40,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 {

    /**
@@ -48,23 +52,23 @@ public interface ActionLog {
     *
     * @return the content
     */
-    @NonNull @Unmodifiable SortedSet<Action> getContent();
+    @Unmodifiable SortedSet<Action> getContent();

    /**
     * Gets the entries in the log performed by the given actor.
     *
-     * @param actor the uuid of the actor to filter by
+     * @param actor the UUID of the actor to filter by
     * @return the content for the given actor
     */
-    @NonNull @Unmodifiable SortedSet<Action> getContent(@NonNull UUID actor);
+    @Unmodifiable SortedSet<Action> getContent(UUID actor);

    /**
     * Gets the log content for a given user
     *
-     * @param uniqueId the uuid to filter by
-     * @return all content in this log where the user = uuid
+     * @param uniqueId the UUID to filter by
+     * @return all content in this log where the user = UUID
     */
-    @NonNull @Unmodifiable SortedSet<Action> getUserHistory(@NonNull UUID uniqueId);
+    @Unmodifiable SortedSet<Action> getUserHistory(UUID uniqueId);

    /**
     * Gets the log content for a given group
@@ -72,7 +76,7 @@ public interface ActionLog {
     * @param name the name to filter by
     * @return all content in this log where the group = name
     */
-    @NonNull @Unmodifiable SortedSet<Action> getGroupHistory(@NonNull String name);
+    @Unmodifiable SortedSet<Action> getGroupHistory(String name);

    /**
     * Gets the log content for a given track
@@ -80,6 +84,6 @@ public interface ActionLog {
     * @param name the name to filter by
     * @return all content in this log where the track = name
     */
-    @NonNull @Unmodifiable SortedSet<Action> getTrackHistory(@NonNull String name);
+    @Unmodifiable SortedSet<Action> getTrackHistory(String name);

 }
@@ -25,10 +25,10 @@

 package net.luckperms.api.actionlog;

-import net.luckperms.api.messaging.MessagingService;
-
-import org.checkerframework.checker.nullness.qual.NonNull;
+import net.luckperms.api.actionlog.filter.ActionFilter;
+import net.luckperms.api.util.Page;

+import java.util.List;
 import java.util.concurrent.CompletableFuture;

 /**
@@ -41,50 +41,85 @@ public interface ActionLogger {
     *
     * @return a new builder
     */
-    Action.@NonNull Builder actionBuilder();
+    Action.Builder actionBuilder();

    /**
     * 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.
     */
-    @NonNull CompletableFuture<ActionLog> getLog();
+    @Deprecated
+    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
+     */
+    CompletableFuture<List<Action>> queryActions(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
+     */
+    CompletableFuture<Page<Action>> queryActions(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);
+    CompletableFuture<Void> submit(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);
+    CompletableFuture<Void> submitToStorage(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);
+    CompletableFuture<Void> broadcastAction(Action entry);

 }
@@ -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);
+
+}
@@ -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);
+
+}
@@ -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.
+ */
+
+/**
+ * {@link net.luckperms.api.actionlog.Action} filters.
+ */
+@org.jspecify.annotations.NullMarked
+package net.luckperms.api.actionlog.filter;
@@ -24,6 +24,7 @@
 */

 /**
- * {@link net.luckperms.api.actionlog.ActionLog} related functionality.
+ * {@link net.luckperms.api.actionlog.ActionLogger} related functionality.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.actionlog;
@@ -27,10 +27,12 @@ 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 {

@@ -39,6 +41,6 @@ public interface CachedData {
     *
     * @return the query options this container is caching
     */
-    @NonNull QueryOptions getQueryOptions();
+    QueryOptions getQueryOptions();

 }
@@ -31,15 +31,13 @@ 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;

 /**
 * 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 {
@@ -49,14 +47,14 @@ public interface CachedDataManager {
     *
     * @return the permission data manager
     */
-    @NonNull Container<CachedPermissionData> permissionData();
+    Container<CachedPermissionData> permissionData();

    /**
     * Gets the manager for {@link CachedMetaData}.
     *
     * @return the meta data manager
     */
-    @NonNull Container<CachedMetaData> metaData();
+    Container<CachedMetaData> metaData();

    /**
     * Gets PermissionData from the cache, using the given query options.
@@ -64,7 +62,7 @@ public interface CachedDataManager {
     * @param queryOptions the query options
     * @return a permission data instance
     */
-    @NonNull CachedPermissionData getPermissionData(@NonNull QueryOptions queryOptions);
+    CachedPermissionData getPermissionData(QueryOptions queryOptions);

    /**
     * Gets MetaData from the cache, using the given query options.
@@ -72,7 +70,7 @@ public interface CachedDataManager {
     * @param queryOptions the query options
     * @return a meta data instance
     */
-    @NonNull CachedMetaData getMetaData(@NonNull QueryOptions queryOptions);
+    CachedMetaData getMetaData(QueryOptions queryOptions);

    /**
     * Gets PermissionData from the cache, using the most appropriate query options
@@ -80,17 +78,16 @@ 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>
+     * corresponding player is online, and otherwise, will fall back to
+     * {@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
     */
-    @NonNull CachedPermissionData getPermissionData();
+    CachedPermissionData getPermissionData();

    /**
     * Gets MetaData from the cache, using the most appropriate query options
@@ -98,18 +95,17 @@ 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>
+     * corresponding player is online, and otherwise, will fall back to
+     * {@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
     * @see PermissionHolder#getQueryOptions()
     */
-    @NonNull CachedMetaData getMetaData();
+    CachedMetaData getMetaData();

    /**
     * Invalidates all cached {@link CachedPermissionData} and {@link CachedMetaData}
@@ -118,7 +114,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>
     */
@@ -139,7 +135,7 @@ public interface CachedDataManager {
         * @return a data instance
         * @throws NullPointerException if contexts is null
         */
-        @NonNull T get(@NonNull QueryOptions queryOptions);
+        T get(QueryOptions queryOptions);

        /**
         * Calculates {@link T data}, bypassing the cache.
@@ -156,7 +152,7 @@ public interface CachedDataManager {
         * @return a data instance
         * @throws NullPointerException if contexts is null
         */
-        @NonNull T calculate(@NonNull QueryOptions queryOptions);
+        T calculate(QueryOptions queryOptions);

        /**
         * (Re)calculates data for a given context.
@@ -174,7 +170,7 @@ public interface CachedDataManager {
         * @param queryOptions the query options
         * @throws NullPointerException if contexts is null
         */
-        void recalculate(@NonNull QueryOptions queryOptions);
+        void recalculate(QueryOptions queryOptions);

        /**
         * (Re)loads permission data for a given context.
@@ -200,7 +196,7 @@ public interface CachedDataManager {
         * @return a future
         * @throws NullPointerException if contexts is null
         */
-        @NonNull CompletableFuture<? extends T> reload(@NonNull QueryOptions queryOptions);
+        CompletableFuture<? extends T> reload(QueryOptions queryOptions);

        /**
         * Recalculates data for all known contexts.
@@ -232,14 +228,14 @@ public interface CachedDataManager {
         *
         * @return a future
         */
-        @NonNull CompletableFuture<Void> reload();
+        CompletableFuture<Void> reload();

        /**
         * Invalidates any cached data instances mapped to the given context.
         *
         * @param queryOptions the queryOptions to invalidate for
         */
-        void invalidate(@NonNull QueryOptions queryOptions);
+        void invalidate(QueryOptions queryOptions);

        /**
         * Invalidates all cached data instances.
@@ -26,10 +26,12 @@
 package net.luckperms.api.cacheddata;

 import net.luckperms.api.metastacking.MetaStackDefinition;
-
-import org.checkerframework.checker.nullness.qual.NonNull;
-import org.checkerframework.checker.nullness.qual.Nullable;
+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.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.Nullable;

 import java.util.List;
 import java.util.Map;
@@ -39,16 +41,40 @@ 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
+     */
+    Result<String, MetaNode> queryMetaValue(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(@NonNull String key);
+    default @Nullable String getMetaValue(String key) {
+        return queryMetaValue(key).result();
+    }

    /**
     * Gets a value for the given meta key, and runs it through the given {@code transformer}.
@@ -70,7 +96,7 @@ public interface CachedMetaData extends CachedData {
     * @return the meta value
     * @since 5.3
     */
-    default <T> @NonNull Optional<T> getMetaValue(@NonNull String key, @NonNull Function<String, ? extends T> valueTransformer) {
+    default <T> Optional<T> getMetaValue(String key, Function<String, ? extends T> valueTransformer) {
        return Optional.ofNullable(getMetaValue(key)).map(value -> {
            try {
                return valueTransformer.apply(value);
@@ -81,41 +107,125 @@ public interface CachedMetaData extends CachedData {
    }

    /**
-     * Gets the holder's highest priority prefix, or null if the holder has no prefixes
+     * 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
+     * the resultant prefix stack contained no elements.</p>
+     *
+     * @return a result containing the prefix
+     * @since 5.4
+     */
+    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
+     * the resultant suffix stack contained no elements.</p>
+     *
+     * @return a result containing the suffix
+     * @since 5.4
+     */
+    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 @Unmodifiable Map<String, List<String>> getMeta();
+    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
+     */
+    @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 @Unmodifiable SortedMap<Integer, String> getPrefixes();
+    @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 @Unmodifiable SortedMap<Integer, String> getSuffixes();
+    @Unmodifiable SortedMap<Integer, String> getSuffixes();

    /**
     * Gets the name of the holders primary group.
@@ -128,17 +238,17 @@ 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();
+    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
     */
-    @NonNull MetaStackDefinition getSuffixStackDefinition();
+    MetaStackDefinition getSuffixStackDefinition();

 }
@@ -25,26 +25,47 @@

 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
+     */
+    Result<Tristate, Node> queryPermission(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 Tristate checkPermission(String permission) {
+        return queryPermission(permission).result();
+    }

    /**
     * Invalidates the underlying permission calculator cache.
@@ -58,6 +79,6 @@ public interface CachedPermissionData extends CachedData {
     *
     * @return an immutable set of permissions
     */
-    @NonNull @Unmodifiable Map<String, Boolean> getPermissionMap();
+    @Unmodifiable Map<String, Boolean> getPermissionMap();

 }
@@ -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.jspecify.annotations.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();
+
+}
@@ -24,7 +24,8 @@
 */

 /**
- * CachedData lookup API for {@link net.luckperms.api.model.user.User}s and
+ * Caches permission checks and meta lookups for {@link net.luckperms.api.model.user.User}s and
 * {@link net.luckperms.api.model.group.Group}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.cacheddata;
@@ -25,8 +25,7 @@

 package net.luckperms.api.context;

-import org.checkerframework.checker.nullness.qual.NonNull;
-import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jspecify.annotations.Nullable;

 /**
 * Represents an individual context pair.
@@ -89,13 +88,13 @@ public interface Context {
     *
     * @return the key
     */
-    @NonNull String getKey();
+    String getKey();

    /**
     * Gets the context value
     *
     * @return the value
     */
-    @NonNull String getValue();
+    String getValue();

 }
@@ -25,7 +25,7 @@

 package net.luckperms.api.context;

-import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jspecify.annotations.Nullable;

 import java.util.Objects;
 import java.util.function.Function;
@@ -38,8 +38,8 @@ import java.util.function.Function;
 * <ul>
 *     <li>Context lookups should be <i>fast</i>: lookup methods are likely to
 *     be invoked frequently, and should therefore be fast to execute. If
- *     determining the current contexts involves a particularly time consuming
- *     lookup (database queries, network requests, etc), then such results
+ *     determining the current contexts involves a particularly time-consuming
+ *     lookup (database queries, network requests, etc.), then such results
 *     should be cached ahead of time.</li>
 *
 *     <li>Context lookups should be <i>thread-safe</i>: lookups will sometimes
@@ -70,7 +70,7 @@ public interface ContextCalculator<T> {
     * @param <T> the contextual type
     * @return the resultant calculator
     */
-    static <T> @NonNull ContextCalculator<T> forSingleContext(@NonNull String key, @NonNull Function<T, String> valueFunction) {
+    static <T> ContextCalculator<T> forSingleContext(String key, Function<T, @Nullable String> valueFunction) {
        Objects.requireNonNull(key, "key");
        Objects.requireNonNull(valueFunction, "valueFunction");
        return (target, consumer) -> {
@@ -92,7 +92,7 @@ public interface ContextCalculator<T> {
     * @param target the target contextual subject for this operation
     * @param consumer the {@link ContextConsumer} to submit contexts to
     */
-    void calculate(@NonNull T target, @NonNull ContextConsumer consumer);
+    void calculate(T target, ContextConsumer consumer);

    /**
     * Gets a {@link ContextSet}, containing some/all of the contexts this
@@ -25,8 +25,6 @@

 package net.luckperms.api.context;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 /**
 * Functional interface that accepts context key value pairs.
 */
@@ -39,14 +37,14 @@ public interface ContextConsumer {
     * @param key the key
     * @param value the value
     */
-    void accept(@NonNull String key, @NonNull String value);
+    void accept(String key, String value);

    /**
     * Accepts a context pair.
     *
     * @param context the context
     */
-    default void accept(@NonNull Context context) {
+    default void accept(Context context) {
        accept(context.getKey(), context.getValue());
    }

@@ -55,7 +53,7 @@ public interface ContextConsumer {
     *
     * @param contextSet the context set
     */
-    default void accept(@NonNull ContextSet contextSet) {
+    default void accept(ContextSet contextSet) {
        for (Context entry : contextSet) {
            accept(entry);
        }
@@ -28,8 +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;

 import java.util.Optional;
@@ -62,7 +60,7 @@ public interface ContextManager {
     * @param subject the subject
     * @return the applicable context for the subject
     */
-    @NonNull ImmutableContextSet getContext(@NonNull Object subject);
+    ImmutableContextSet getContext(Object subject);

    /**
     * Queries the ContextManager for current context values for the given User.
@@ -77,7 +75,7 @@ public interface ContextManager {
     * @param user the user
     * @return the applicable context for the subject
     */
-    @NonNull Optional<ImmutableContextSet> getContext(@NonNull User user);
+    Optional<ImmutableContextSet> getContext(User user);

    /**
     * Gets the contexts from the static calculators in this manager.
@@ -87,7 +85,7 @@ public interface ContextManager {
     *
     * @return the current active static contexts
     */
-    @NonNull ImmutableContextSet getStaticContext();
+    ImmutableContextSet getStaticContext();

    /**
     * Creates a new {@link QueryOptions.Builder}.
@@ -95,7 +93,7 @@ public interface ContextManager {
     * @param mode the mode
     * @return a new query options builder
     */
-    QueryOptions.@NonNull Builder queryOptionsBuilder(@NonNull QueryMode mode);
+    QueryOptions.Builder queryOptionsBuilder(QueryMode mode);

    /**
     * Obtains current {@link QueryOptions} for the subject.
@@ -103,7 +101,7 @@ public interface ContextManager {
     * @param subject the subject
     * @return the query options for the subject
     */
-    @NonNull QueryOptions getQueryOptions(@NonNull Object subject);
+    QueryOptions getQueryOptions(Object subject);

    /**
     * Obtains current {@link QueryOptions} for the given User.
@@ -117,28 +115,28 @@ public interface ContextManager {
     * @param user the user
     * @return the query options for the subject
     */
-    @NonNull Optional<QueryOptions> getQueryOptions(@NonNull User user);
+    Optional<QueryOptions> getQueryOptions(User user);

    /**
     * Gets the static query options, using the registered static context calculators.
     *
     * @return the current static query options
     */
-    @NonNull QueryOptions getStaticQueryOptions();
+    QueryOptions getStaticQueryOptions();

    /**
     * Registers a context calculator with the manager.
     *
     * @param calculator the calculator
     */
-    void registerCalculator(@NonNull ContextCalculator<?> calculator);
+    void registerCalculator(ContextCalculator<?> calculator);

    /**
     * Unregisters a context calculator with the manager.
     *
     * @param calculator the calculator
     */
-    void unregisterCalculator(@NonNull ContextCalculator<?> calculator);
+    void unregisterCalculator(ContextCalculator<?> calculator);

    /**
     * Signal to the {@link ContextManager} that a {@code subject}s
@@ -150,7 +148,7 @@ public interface ContextManager {
     * @param subject the subject
     * @since 5.2
     */
-    void signalContextUpdate(@NonNull Object subject);
+    void signalContextUpdate(Object subject);

    /**
     * Gets the {@link ContextSetFactory}, responsible for creating
@@ -159,7 +157,7 @@ public interface ContextManager {
     * @return the context set factory
     */
    @Internal
-    @NonNull ContextSetFactory getContextSetFactory();
+    ContextSetFactory getContextSetFactory();

    /**
     * Invalidates the lookup cache for a given subject
@@ -168,7 +166,7 @@ public interface ContextManager {
     * @deprecated Use {@link #signalContextUpdate(Object)} instead
     */
    @Deprecated
-    default void invalidateCache(@NonNull Object subject) {
+    default void invalidateCache(Object subject) {
        signalContextUpdate(subject);
    }

@@ -25,7 +25,6 @@

 package net.luckperms.api.context;

-import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.Unmodifiable;

 import java.util.Iterator;
@@ -65,7 +64,7 @@ import java.util.Set;
 * the '{@code :}' character. (e.g. "{@code worldguard:region}" for WorldGuard
 * regions)</p>
 *
- * <p>Contexts can be combined with each other to form so called
+ * <p>Contexts can be combined with each other to form so-called
 * "context sets" - simply a collection of context pairs.</p>
 *
 * <p>Two default ContextSet implementations are provided.
@@ -91,7 +90,7 @@ public interface ContextSet extends Iterable<Context> {
     *
     * @return an immutable representation of this set
     */
-    @NonNull ImmutableContextSet immutableCopy();
+    ImmutableContextSet immutableCopy();

    /**
     * Creates a mutable copy of this {@link ContextSet}.
@@ -101,7 +100,7 @@ public interface ContextSet extends Iterable<Context> {
     *
     * @return a mutable ContextSet
     */
-    @NonNull MutableContextSet mutableCopy();
+    MutableContextSet mutableCopy();

    /**
     * Returns a {@link Set} of {@link Context}s representing the current
@@ -112,7 +111,7 @@ public interface ContextSet extends Iterable<Context> {
     *
     * @return an immutable set
     */
-    @NonNull @Unmodifiable Set<Context> toSet();
+    @Unmodifiable Set<Context> toSet();

    /**
     * Returns a {@link Map} representing the current state of this
@@ -123,7 +122,7 @@ public interface ContextSet extends Iterable<Context> {
     *
     * @return a map
     */
-    @NonNull @Unmodifiable Map<String, Set<String>> toMap();
+    @Unmodifiable Map<String, Set<String>> toMap();

    /**
     * Returns a {@link Map} <b>loosely</b> representing the current state of
@@ -139,7 +138,7 @@ public interface ContextSet extends Iterable<Context> {
     * @deprecated Deprecated because the returned map may not contain all data in the ContextSet
     */
    @Deprecated
-    @NonNull @Unmodifiable Map<String, String> toFlattenedMap();
+    @Unmodifiable Map<String, String> toFlattenedMap();

    /**
     * Returns an {@link Iterator} over each of the context pairs in this set.
@@ -152,7 +151,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return an iterator
     */
    @Override
-    @NonNull @Unmodifiable Iterator<Context> iterator();
+    @Unmodifiable Iterator<Context> iterator();

    /**
     * Returns if the {@link ContextSet} contains at least one value for the
@@ -162,7 +161,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return true if the set contains a value for the key
     * @throws NullPointerException if the key is null
     */
-    boolean containsKey(@NonNull String key);
+    boolean containsKey(String key);

    /**
     * Returns a {@link Set} of the values mapped to the given key.
@@ -174,7 +173,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return a set of values
     * @throws NullPointerException if the key is null
     */
-    @NonNull @Unmodifiable Set<String> getValues(@NonNull String key);
+    @Unmodifiable Set<String> getValues(String key);

    /**
     * Returns any value from this {@link ContextSet} matching the key, if present.
@@ -185,7 +184,7 @@ public interface ContextSet extends Iterable<Context> {
     * @param key the key to find values for
     * @return an optional containing any match
     */
-    default @NonNull Optional<String> getAnyValue(@NonNull String key) {
+    default Optional<String> getAnyValue(String key) {
        return getValues(key).stream().findAny();
    }

@@ -197,7 +196,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return true if the set contains the context pair
     * @throws NullPointerException if the key or value is null
     */
-    boolean contains(@NonNull String key, @NonNull String value);
+    boolean contains(String key, String value);

    /**
     * Returns if the {@link ContextSet} contains a given context pairing.
@@ -206,7 +205,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return true if the set contains the context pair
     * @throws NullPointerException if the key or value is null
     */
-    default boolean contains(@NonNull Context entry) {
+    default boolean contains(Context entry) {
        Objects.requireNonNull(entry, "entry");
        return contains(entry.getKey(), entry.getValue());
    }
@@ -219,7 +218,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return true if the set contains any of the pairs
     * @since 5.2
     */
-    default boolean containsAny(@NonNull String key, @NonNull Iterable<String> values) {
+    default boolean containsAny(String key, Iterable<String> values) {
        Objects.requireNonNull(key, "key");
        Objects.requireNonNull(values, "values");

@@ -239,7 +238,7 @@ public interface ContextSet extends Iterable<Context> {
     * @param other the other set
     * @return true if this context set is satisfied by the other
     */
-    default boolean isSatisfiedBy(@NonNull ContextSet other) {
+    default boolean isSatisfiedBy(ContextSet other) {
        return isSatisfiedBy(other, ContextSatisfyMode.AT_LEAST_ONE_VALUE_PER_KEY);
    }

@@ -252,7 +251,7 @@ public interface ContextSet extends Iterable<Context> {
     * @return true if this context set is satisfied by the other
     * @since 5.2
     */
-    boolean isSatisfiedBy(@NonNull ContextSet other, @NonNull ContextSatisfyMode mode);
+    boolean isSatisfiedBy(ContextSet other, ContextSatisfyMode mode);

    /**
     * Returns if the {@link ContextSet} is empty.
@@ -25,7 +25,6 @@

 package net.luckperms.api.context;

-import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.ApiStatus.Internal;

 /**
@@ -40,10 +39,10 @@ public interface ContextSetFactory {
    /**
     * Prefer using {@link ImmutableContextSet#builder()}.
     *
-     * @return a immutable context set builder
+     * @return an immutable context set builder
     * @see ImmutableContextSet#builder()
     */
-    ImmutableContextSet.@NonNull Builder immutableBuilder();
+    ImmutableContextSet.Builder immutableBuilder();

    /**
     * Prefer using {@link ImmutableContextSet#of(String, String)}.
@@ -53,7 +52,7 @@ public interface ContextSetFactory {
     * @return an immutable context set
     * @see ImmutableContextSet#of(String, String)
     */
-    @NonNull ImmutableContextSet immutableOf(@NonNull String key, @NonNull String value);
+    ImmutableContextSet immutableOf(String key, String value);

    /**
     * Prefer using {@link ImmutableContextSet#empty()}.
@@ -61,7 +60,7 @@ public interface ContextSetFactory {
     * @return an empty immutable context set
     * @see ImmutableContextSet#empty()
     */
-    @NonNull ImmutableContextSet immutableEmpty();
+    ImmutableContextSet immutableEmpty();

    /**
     * Prefer using {@link MutableContextSet#create()}.
@@ -69,6 +68,6 @@ public interface ContextSetFactory {
     * @return a new mutable context set
     * @see MutableContextSet#create()
     */
-    @NonNull MutableContextSet mutable();
+    MutableContextSet mutable();

 }
@@ -34,17 +34,17 @@ public final class DefaultContextKeys {
    }

    /**
-     * The context key used to denote the name of the subjects server.
+     * The context key used to denote the name of the subject's server.
     */
    public static final String SERVER_KEY = "server";

    /**
-     * The context key used to denote the name of the subjects world.
+     * The context key used to denote the name of the subject's world.
     */
    public static final String WORLD_KEY = "world";

    /**
-     * The context key used to denote the dimension type of the subjects world.
+     * The context key used to denote the dimension type of the subject's world.
     *
     * <p>Possible values: overworld, the_nether, the_end</p>
     *
@@ -53,7 +53,7 @@ public final class DefaultContextKeys {
    public static final String DIMENSION_TYPE_KEY = "dimension-type";

    /**
-     * The context key used to denote the subjects gamemode.
+     * The context key used to denote the subject's gamemode.
     *
     * <p>Possible values: survival, creative, adventure, spectator</p>
     *
@@ -27,8 +27,6 @@ package net.luckperms.api.context;

 import net.luckperms.api.LuckPermsProvider;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 import java.util.Objects;

 /**
@@ -41,7 +39,7 @@ public interface ImmutableContextSet extends ContextSet {
     *
     * @return a new ImmutableContextSet builder
     */
-    static @NonNull Builder builder() {
+    static Builder builder() {
        return LuckPermsProvider.get().getContextManager().getContextSetFactory().immutableBuilder();
    }

@@ -50,7 +48,7 @@ public interface ImmutableContextSet extends ContextSet {
     *
     * @return an empty ImmutableContextSet
     */
-    static @NonNull ImmutableContextSet empty() {
+    static ImmutableContextSet empty() {
        return LuckPermsProvider.get().getContextManager().getContextSetFactory().immutableEmpty();
    }

@@ -62,7 +60,7 @@ public interface ImmutableContextSet extends ContextSet {
     * @return a new ImmutableContextSet containing one context pair
     * @throws NullPointerException if key or value is null
     */
-    static @NonNull ImmutableContextSet of(@NonNull String key, @NonNull String value) {
+    static ImmutableContextSet of(String key, String value) {
        return LuckPermsProvider.get().getContextManager().getContextSetFactory().immutableOf(key, value);
    }

@@ -71,7 +69,7 @@ public interface ImmutableContextSet extends ContextSet {
     */
    @Override
    @Deprecated
-    @NonNull ImmutableContextSet immutableCopy();
+    ImmutableContextSet immutableCopy();

    /**
     * A builder for {@link ImmutableContextSet}.
@@ -87,7 +85,7 @@ public interface ImmutableContextSet extends ContextSet {
         * @throws NullPointerException if the key or value is null
         * @see MutableContextSet#add(String, String)
         */
-        @NonNull Builder add(@NonNull String key, @NonNull String value);
+        Builder add(String key, String value);

        /**
         * Adds a context to the set.
@@ -97,7 +95,7 @@ public interface ImmutableContextSet extends ContextSet {
         * @throws NullPointerException if the entry is null
         * @see MutableContextSet#add(Context)
         */
-        default @NonNull Builder add(@NonNull Context entry) {
+        default Builder add(Context entry) {
            Objects.requireNonNull(entry, "entry");
            add(entry.getKey(), entry.getValue());
            return this;
@@ -111,7 +109,7 @@ public interface ImmutableContextSet extends ContextSet {
         * @throws NullPointerException if iterable is null
         * @see MutableContextSet#addAll(Iterable)
         */
-        default @NonNull Builder addAll(@NonNull Iterable<Context> iterable) {
+        default Builder addAll(Iterable<Context> iterable) {
            for (Context e : Objects.requireNonNull(iterable, "iterable")) {
                add(e);
            }
@@ -119,14 +117,14 @@ 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
         * @throws NullPointerException if the contextSet is null
         * @see MutableContextSet#addAll(ContextSet)
         */
-        @NonNull Builder addAll(@NonNull ContextSet contextSet);
+        Builder addAll(ContextSet contextSet);

        /**
         * Creates a {@link ImmutableContextSet} from the values previously
@@ -134,6 +132,6 @@ public interface ImmutableContextSet extends ContextSet {
         *
         * @return an {@link ImmutableContextSet} from the builder
         */
-        @NonNull ImmutableContextSet build();
+        ImmutableContextSet build();
    }
 }
@@ -27,8 +27,6 @@ package net.luckperms.api.context;

 import net.luckperms.api.LuckPermsProvider;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 import java.util.Objects;

 /**
@@ -41,7 +39,7 @@ public interface MutableContextSet extends ContextSet {
     *
     * @return a new MutableContextSet
     */
-    static @NonNull MutableContextSet create() {
+    static MutableContextSet create() {
        return LuckPermsProvider.get().getContextManager().getContextSetFactory().mutable();
    }

@@ -53,7 +51,7 @@ public interface MutableContextSet extends ContextSet {
     * @return a new MutableContextSet containing one context pair
     * @throws NullPointerException if key or value is null
     */
-    static @NonNull MutableContextSet of(@NonNull String key, @NonNull String value) {
+    static MutableContextSet of(String key, String value) {
        Objects.requireNonNull(key, "key");
        Objects.requireNonNull(value, "value");
        MutableContextSet set = create();
@@ -68,7 +66,7 @@ public interface MutableContextSet extends ContextSet {
     * @param value the value to add
     * @throws NullPointerException if the key or value is null
     */
-    void add(@NonNull String key, @NonNull String value);
+    void add(String key, String value);

    /**
     * Adds a context to this set.
@@ -76,7 +74,7 @@ public interface MutableContextSet extends ContextSet {
     * @param entry the entry to add
     * @throws NullPointerException if the entry is null
     */
-    default void add(@NonNull Context entry) {
+    default void add(Context entry) {
        Objects.requireNonNull(entry, "entry");
        add(entry.getKey(), entry.getValue());
    }
@@ -87,19 +85,19 @@ public interface MutableContextSet extends ContextSet {
     * @param iterable an iterable of key value context pairs
     * @throws NullPointerException if iterable is null
     */
-    default void addAll(@NonNull Iterable<Context> iterable) {
+    default void addAll(Iterable<Context> iterable) {
        for (Context e : Objects.requireNonNull(iterable, "iterable")) {
            add(e);
        }
    }

    /**
-     * 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
     */
-    void addAll(@NonNull ContextSet contextSet);
+    void addAll(ContextSet contextSet);

    /**
     * Removes a context from this set.
@@ -108,7 +106,7 @@ public interface MutableContextSet extends ContextSet {
     * @param value the value to remove
     * @throws NullPointerException if the key or value is null
     */
-    void remove(@NonNull String key, @NonNull String value);
+    void remove(String key, String value);

    /**
     * Removes all contexts from this set with the given key.
@@ -116,7 +114,7 @@ public interface MutableContextSet extends ContextSet {
     * @param key the key to remove
     * @throws NullPointerException if the key is null
     */
-    void removeAll(@NonNull String key);
+    void removeAll(String key);

    /**
     * Removes all contexts from the set.
@@ -25,7 +25,7 @@

 package net.luckperms.api.context;

-import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jspecify.annotations.Nullable;

 import java.util.Objects;
 import java.util.function.Supplier;
@@ -46,7 +46,7 @@ public interface StaticContextCalculator extends ContextCalculator<Object> {
     *                      if the value returned is null.
     * @return the resultant calculator
     */
-    static StaticContextCalculator forSingleContext(String key, Supplier<String> valueFunction) {
+    static StaticContextCalculator forSingleContext(String key, Supplier<@Nullable String> valueFunction) {
        Objects.requireNonNull(key, "key");
        Objects.requireNonNull(valueFunction, "valueFunction");
        return consumer -> {
@@ -66,10 +66,10 @@ public interface StaticContextCalculator extends ContextCalculator<Object> {
     *
     * @param consumer the {@link ContextConsumer} to submit contexts to
     */
-    void calculate(@NonNull ContextConsumer consumer);
+    void calculate(ContextConsumer consumer);

    @Override
-    default void calculate(@NonNull Object target, @NonNull ContextConsumer consumer) {
+    default void calculate(Object target, ContextConsumer consumer) {
        calculate(consumer);
    }
 }
@@ -27,4 +27,5 @@
 * Context functionality, including {@link net.luckperms.api.context.ContextSet}s and
 * {@link net.luckperms.api.context.ContextCalculator}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.context;
@@ -25,7 +25,6 @@

 package net.luckperms.api.event;

-import org.checkerframework.checker.nullness.qual.NonNull;
 import org.jetbrains.annotations.Unmodifiable;

 import java.util.Set;
@@ -50,7 +49,7 @@ public interface EventBus {
     * @param <T>        the event class
     * @return an event handler instance representing this subscription
     */
-    <T extends LuckPermsEvent> @NonNull EventSubscription<T> subscribe(@NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
+    <T extends LuckPermsEvent> EventSubscription<T> subscribe(Class<T> eventClass, Consumer<? super T> handler);

    /**
     * Registers a new subscription to the given event.
@@ -70,7 +69,7 @@ public interface EventBus {
     * @param handler    the event handler
     * @return an event handler instance representing this subscription
     */
-    <T extends LuckPermsEvent> @NonNull EventSubscription<T> subscribe(Object plugin, @NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
+    <T extends LuckPermsEvent> EventSubscription<T> subscribe(Object plugin, Class<T> eventClass, Consumer<? super T> handler);

    /**
     * Gets a set of all registered handlers for a given event.
@@ -79,6 +78,6 @@ public interface EventBus {
     * @param <T>        the event class
     * @return an immutable set of event handlers
     */
-    <T extends LuckPermsEvent> @NonNull @Unmodifiable Set<EventSubscription<T>> getSubscriptions(@NonNull Class<T> eventClass);
+    <T extends LuckPermsEvent> @Unmodifiable Set<EventSubscription<T>> getSubscriptions(Class<T> eventClass);

 }
@@ -25,8 +25,6 @@

 package net.luckperms.api.event;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 import java.util.function.Consumer;

 /**
@@ -41,7 +39,7 @@ public interface EventSubscription<T extends LuckPermsEvent> extends AutoCloseab
     *
     * @return the event class
     */
-    @NonNull Class<T> getEventClass();
+    Class<T> getEventClass();

    /**
     * Returns true if this handler is active
@@ -61,5 +59,5 @@ public interface EventSubscription<T extends LuckPermsEvent> extends AutoCloseab
     *
     * @return the event consumer
     */
-    @NonNull Consumer<? super T> getHandler();
+    Consumer<? super T> getHandler();
 }
@@ -27,8 +27,6 @@ package net.luckperms.api.event;

 import net.luckperms.api.LuckPerms;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 /**
 * A superinterface for all LuckPerms events.
 */
@@ -39,13 +37,13 @@ public interface LuckPermsEvent {
     *
     * @return the api instance
     */
-    @NonNull LuckPerms getLuckPerms();
+    LuckPerms getLuckPerms();

    /**
     * Gets the type of the event.
     *
     * @return the type of the event
     */
-    @NonNull Class<? extends LuckPermsEvent> getEventType();
+    Class<? extends LuckPermsEvent> getEventType();

 }
@@ -26,4 +26,5 @@
 /**
 * Event causes.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.cause;
@@ -29,8 +29,6 @@ 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;

 /**
@@ -59,16 +57,16 @@ public interface ContextUpdateEvent extends LuckPermsEvent {
     * @return the subject
     */
    @Param(0)
-    @NonNull Object getSubject();
+    Object getSubject();

    /**
-     * Gets the subject whose contexts were updated, casted to a given type.
+     * Gets the subject whose contexts were updated, cast to a given type.
     *
     * @param subjectClass the type to cast to
     * @param <T> the subject type
-     * @return the casted subject
+     * @return the cast subject
     */
-    default <T> @NonNull Optional<T> getSubject(@NonNull Class<T> subjectClass) {
+    default <T> Optional<T> getSubject(Class<T> subjectClass) {
        Object subject = getSubject();
        return subjectClass.isInstance(subject) ? Optional.of(subjectClass.cast(subject)) : Optional.empty();
    }
@@ -26,4 +26,5 @@
 /**
 * Events relating to {@link net.luckperms.api.context.Context}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.context;
@@ -29,8 +29,6 @@ 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;
-
 /**
 * Called when an {@link Extension} is loaded.
 */
@@ -42,6 +40,6 @@ public interface ExtensionLoadEvent extends LuckPermsEvent {
     * @return the extension
     */
    @Param(0)
-    @NonNull Extension getExtension();
+    Extension getExtension();

 }
@@ -26,4 +26,5 @@
 /**
 * Events relating to {@link net.luckperms.api.extension.Extension}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.extension;
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a groups {@link CachedDataManager} is loaded.
 */
@@ -43,7 +41,7 @@ public interface GroupCacheLoadEvent extends LuckPermsEvent {
     * @return the group
     */
    @Param(0)
-    @NonNull Group getGroup();
+    Group getGroup();

    /**
     * Gets the data that was loaded
@@ -51,6 +49,6 @@ public interface GroupCacheLoadEvent extends LuckPermsEvent {
     * @return the loaded data
     */
    @Param(1)
-    @NonNull CachedDataManager getLoadedData();
+    CachedDataManager getLoadedData();

 }
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a group is created
 */
@@ -43,7 +41,7 @@ public interface GroupCreateEvent extends LuckPermsEvent {
     * @return the new group
     */
    @Param(0)
-    @NonNull Group getGroup();
+    Group getGroup();

    /**
     * Gets the cause of the creation
@@ -51,6 +49,6 @@ public interface GroupCreateEvent extends LuckPermsEvent {
     * @return the cause of the creation
     */
    @Param(1)
-    @NonNull CreationCause getCause();
+    CreationCause getCause();

 }
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a groups cached data is refreshed
 */
@@ -43,7 +41,7 @@ public interface GroupDataRecalculateEvent extends LuckPermsEvent {
     * @return the group
     */
    @Param(0)
-    @NonNull Group getGroup();
+    Group getGroup();

    /**
     * Gets the data that was recalculated
@@ -51,6 +49,6 @@ public interface GroupDataRecalculateEvent extends LuckPermsEvent {
     * @return the data
     */
    @Param(1)
-    @NonNull CachedDataManager getData();
+    CachedDataManager getData();

 }
@@ -30,8 +30,6 @@ 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;

 /**
@@ -45,7 +43,7 @@ public interface GroupDeleteEvent extends LuckPermsEvent {
     * @return the name of the deleted group
     */
    @Param(0)
-    @NonNull String getGroupName();
+    String getGroupName();

    /**
     * Gets an immutable copy of the groups existing data
@@ -53,7 +51,7 @@ public interface GroupDeleteEvent extends LuckPermsEvent {
     * @return a copy of the groups existing data
     */
    @Param(1)
-    @NonNull Set<Node> getExistingData();
+    Set<Node> getExistingData();

    /**
     * Gets the cause of the deletion
@@ -61,6 +59,6 @@ public interface GroupDeleteEvent extends LuckPermsEvent {
     * @return the cause of the deletion
     */
    @Param(2)
-    @NonNull DeletionCause getCause();
+    DeletionCause getCause();

 }
@@ -29,12 +29,10 @@ 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;
-
 /**
 * Called when a group is loaded into memory from the storage.
 *
- * Note that this event is not the same as {@link GroupCreateEvent}
+ * <p>Note that this event is not the same as {@link GroupCreateEvent}.</p>
 */
 public interface GroupLoadEvent extends LuckPermsEvent {

@@ -44,6 +42,6 @@ public interface GroupLoadEvent extends LuckPermsEvent {
     * @return the group that was loaded
     */
    @Param(0)
-    @NonNull Group getGroup();
+    Group getGroup();

 }
@@ -26,4 +26,5 @@
 /**
 * Events relating to {@link net.luckperms.api.model.group.Group}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.group;
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a log entry is about to be sent to notifiable players on the platform
 */
@@ -43,7 +41,7 @@ public interface LogBroadcastEvent extends LuckPermsEvent, Cancellable {
     * @return the log entry to be broadcasted
     */
    @Param(0)
-    @NonNull Action getEntry();
+    Action getEntry();

    /**
     * Gets where the log entry originated from.
@@ -51,7 +49,7 @@ public interface LogBroadcastEvent extends LuckPermsEvent, Cancellable {
     * @return the origin of the log
     */
    @Param(1)
-    @NonNull Origin getOrigin();
+    Origin getOrigin();

    /**
     * Represents where a log entry is from
@@ -30,8 +30,6 @@ 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;

 /**
@@ -45,7 +43,7 @@ public interface LogNetworkPublishEvent extends LuckPermsEvent, Cancellable {
     * @return the id of the log entry being published
     */
    @Param(0)
-    @NonNull UUID getLogId();
+    UUID getLogId();

    /**
     * Gets the log entry to be published
@@ -53,6 +51,6 @@ public interface LogNetworkPublishEvent extends LuckPermsEvent, Cancellable {
     * @return the log entry to be published
     */
    @Param(1)
-    @NonNull Action getEntry();
+    Action getEntry();

 }
@@ -31,8 +31,6 @@ 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;
-
 /**
 * Called when a log entry is about to be sent to specific notifiable object on
 * the platform.
@@ -49,7 +47,7 @@ public interface LogNotifyEvent extends LuckPermsEvent, Cancellable {
     * @return the log entry to be sent
     */
    @Param(0)
-    @NonNull Action getEntry();
+    Action getEntry();

    /**
     * Gets where the log entry originated from.
@@ -57,7 +55,7 @@ public interface LogNotifyEvent extends LuckPermsEvent, Cancellable {
     * @return the origin of the log
     */
    @Param(1)
-    @NonNull Origin getOrigin();
+    Origin getOrigin();

    /**
     * Gets the object to be notified.
@@ -65,7 +63,7 @@ public interface LogNotifyEvent extends LuckPermsEvent, Cancellable {
     * @return the object to notify
     */
    @Param(2)
-    @NonNull PlatformEntity getNotifiable();
+    PlatformEntity getNotifiable();

    /**
     * Represents where a log entry is from
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a log is about to be published to the storage file/table
 */
@@ -43,6 +41,6 @@ public interface LogPublishEvent extends LuckPermsEvent, Cancellable {
     * @return the log entry to be published
     */
    @Param(0)
-    @NonNull Action getEntry();
+    Action getEntry();

 }
@@ -29,12 +29,14 @@ 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 {

@@ -44,7 +46,7 @@ public interface LogReceiveEvent extends LuckPermsEvent {
     * @return the id of the log entry being received
     */
    @Param(0)
-    @NonNull UUID getLogId();
+    UUID getLogId();

    /**
     * Gets the log entry being received
@@ -52,6 +54,6 @@ public interface LogReceiveEvent extends LuckPermsEvent {
     * @return the log entry being received
     */
    @Param(1)
-    @NonNull Action getEntry();
+    Action getEntry();

 }
@@ -24,6 +24,7 @@
 */

 /**
- * Events relating to the {@link net.luckperms.api.actionlog.ActionLog}.
+ * Events relating to the {@link net.luckperms.api.actionlog.ActionLogger}.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.log;
@@ -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.messaging;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.messaging.MessagingService;
+
+/**
+ * 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)
+    String getChannelId();
+
+    /**
+     * Gets the custom payload that was sent.
+     *
+     * @return the custom payload
+     */
+    @Param(1)
+    String getPayload();
+
+}
@@ -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 the {@link net.luckperms.api.messaging.MessagingService}.
+ */
+@org.jspecify.annotations.NullMarked
+package net.luckperms.api.event.messaging;
@@ -27,8 +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;

 import java.util.Collections;
@@ -46,10 +44,10 @@ public interface NodeAddEvent extends NodeMutateEvent {
     * @return the node that was added
     */
    @Param(3)
-    @NonNull Node getNode();
+    Node getNode();

    @Override
-    default @NonNull @Unmodifiable Set<Node> getDataBefore() {
+    default @Unmodifiable Set<Node> getDataBefore() {
        // Get data after, then reverse the action
        Set<Node> nodes = new HashSet<>(this.getDataAfter());
        nodes.remove(this.getNode());
@@ -27,8 +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;

 import java.util.Collections;
@@ -47,10 +45,10 @@ public interface NodeClearEvent extends NodeMutateEvent {
     * @since 5.3
     */
    @Param(3)
-    @NonNull @Unmodifiable Set<Node> getNodes();
+    @Unmodifiable Set<Node> getNodes();

    @Override
-    default @NonNull @Unmodifiable Set<Node> getDataBefore() {
+    default @Unmodifiable Set<Node> getDataBefore() {
        // Get data after, then reverse the action
        Set<Node> nodes = new HashSet<>(this.getDataAfter());
        nodes.addAll(this.getNodes());
@@ -32,8 +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;

 import java.util.Set;
@@ -49,7 +47,7 @@ public interface NodeMutateEvent extends LuckPermsEvent {
     * @return the event target
     */
    @Param(0)
-    @NonNull PermissionHolder getTarget();
+    PermissionHolder getTarget();

    /**
     * Gets the data type that was mutated.
@@ -57,14 +55,14 @@ public interface NodeMutateEvent extends LuckPermsEvent {
     * @return the data type
     */
    @Param(1)
-    @NonNull DataType getDataType();
+    DataType getDataType();

    /**
     * Gets an immutable copy of the holders data before the change
     *
     * @return the data before the change
     */
-    @NonNull @Unmodifiable Set<Node> getDataBefore();
+    @Unmodifiable Set<Node> getDataBefore();

    /**
     * Gets an immutable copy of the holders data after the change
@@ -72,7 +70,7 @@ public interface NodeMutateEvent extends LuckPermsEvent {
     * @return the data after the change
     */
    @Param(2)
-    @NonNull @Unmodifiable Set<Node> getDataAfter();
+    @Unmodifiable Set<Node> getDataAfter();

    /**
     * Gets whether the target of this event is a {@link User}
@@ -27,8 +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;

 import java.util.Collections;
@@ -46,10 +44,10 @@ public interface NodeRemoveEvent extends NodeMutateEvent {
     * @return the node that was removed
     */
    @Param(3)
-    @NonNull Node getNode();
+    Node getNode();

    @Override
-    default @NonNull @Unmodifiable Set<Node> getDataBefore() {
+    default @Unmodifiable Set<Node> getDataBefore() {
        // Get data after, then reverse the action
        Set<Node> nodes = new HashSet<>(this.getDataAfter());
        nodes.add(this.getNode());
@@ -27,4 +27,5 @@
 * 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}.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.node;
@@ -26,4 +26,5 @@
 /**
 * Main events package.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event;
@@ -30,8 +30,6 @@ 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;

 /**
@@ -44,10 +42,10 @@ public interface PlayerDataSaveEvent extends LuckPermsEvent {
    /**
     * Gets the unique ID that was saved.
     *
-     * @return the uuid
+     * @return the UUID
     */
    @Param(0)
-    @NonNull UUID getUniqueId();
+    UUID getUniqueId();

    /**
     * Gets the username that was saved.
@@ -55,7 +53,7 @@ public interface PlayerDataSaveEvent extends LuckPermsEvent {
     * @return the username
     */
    @Param(1)
-    @NonNull String getUsername();
+    String getUsername();

    /**
     * Gets the result of the operation.
@@ -63,6 +61,6 @@ public interface PlayerDataSaveEvent extends LuckPermsEvent {
     * @return the result
     */
    @Param(2)
-    @NonNull PlayerSaveResult getResult();
+    PlayerSaveResult getResult();

 }
@@ -29,9 +29,7 @@ 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;
+import org.jspecify.annotations.Nullable;

 import java.util.UUID;

@@ -56,10 +54,10 @@ public interface PlayerLoginProcessEvent extends LuckPermsEvent, Result {
    /**
     * Gets the UUID of the connection which was processed
     *
-     * @return the uuid of the connection which was processed
+     * @return the UUID of the connection which was processed
     */
    @Param(0)
-    @NonNull UUID getUniqueId();
+    UUID getUniqueId();

    /**
     * Gets the username of the connection which was processed
@@ -67,7 +65,7 @@ public interface PlayerLoginProcessEvent extends LuckPermsEvent, Result {
     * @return the username of the connection which was processed
     */
    @Param(1)
-    @NonNull String getUsername();
+    String getUsername();

    /**
     * Gets if the login was processed successfully.
@@ -29,47 +29,61 @@ 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}.
+ * Called when the platform needs to determine a player's {@link UUID unique id} type.
 *
 * @since 5.3
 */
 public interface UniqueIdDetermineTypeEvent extends LuckPermsEvent, ResultEvent<String> {

    /**
-     * The players UUID has been obtained by authenticating with the Mojang session servers.
+     * The player's 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
+     * The player's 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 player's 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();
+    UUID getUniqueId();

    /**
     * Gets the current result unique id type.
     *
     * @return the type
     */
-    default @NonNull String getType() {
+    default String getType() {
        return result().get();
    }

@@ -78,7 +92,7 @@ public interface UniqueIdDetermineTypeEvent extends LuckPermsEvent, ResultEvent<
     *
     * @param type the type
     */
-    default void setType(@NonNull String type) {
+    default void setType(String type) {
        Objects.requireNonNull(type, "type");
        result().set(type);
    }
@@ -28,9 +28,7 @@ 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 org.jspecify.annotations.Nullable;

 import java.util.UUID;

@@ -39,7 +37,7 @@ import java.util.UUID;
 *
 * @since 5.3
 */
-public interface UniqueIdLookupEvent extends LuckPermsEvent, ResultEvent<UUID> {
+public interface UniqueIdLookupEvent extends LuckPermsEvent, ResultEvent<@Nullable UUID> {

    /**
     * Gets the username being looked up.
@@ -47,7 +45,7 @@ public interface UniqueIdLookupEvent extends LuckPermsEvent, ResultEvent<UUID> {
     * @return the username
     */
    @Param(0)
-    @NonNull String getUsername();
+    String getUsername();

    /**
     * Sets the result unique id.
@@ -28,9 +28,7 @@ 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 org.jspecify.annotations.Nullable;

 import java.util.UUID;

@@ -39,7 +37,7 @@ import java.util.UUID;
 *
 * @since 5.3
 */
-public interface UsernameLookupEvent extends LuckPermsEvent, ResultEvent<String> {
+public interface UsernameLookupEvent extends LuckPermsEvent, ResultEvent<@Nullable String> {

    /**
     * Gets the {@link UUID unique id} being looked up.
@@ -47,7 +45,7 @@ public interface UsernameLookupEvent extends LuckPermsEvent, ResultEvent<String>
     * @return the unique id
     */
    @Param(0)
-    @NonNull UUID getUniqueId();
+    UUID getUniqueId();

    /**
     * Sets the result username.
@@ -28,8 +28,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;

 /**
@@ -45,7 +43,7 @@ public interface UsernameValidityCheckEvent extends LuckPermsEvent {
     * @return the username
     */
    @Param(0)
-    @NonNull String getUsername();
+    String getUsername();

    /**
     * Gets the current validity state for the username.
@@ -53,7 +51,7 @@ public interface UsernameValidityCheckEvent extends LuckPermsEvent {
     * @return the validity state
     */
    @Param(1)
-    @NonNull AtomicBoolean validityState();
+    AtomicBoolean validityState();

    /**
     * Gets if the username is currently considered to be valid.
@@ -26,4 +26,5 @@
 /**
 * Events relating to a player {@link java.util.UUID unique id} or username lookup.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.player.lookup;
@@ -26,4 +26,5 @@
 /**
 * Events relating to a player.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.player;
@@ -27,8 +27,6 @@ package net.luckperms.api.event.source;

 import net.luckperms.api.platform.PlatformEntity;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 /**
 * Represents an {@link PlatformEntity} which was the {@link Source} of something.
 */
@@ -39,6 +37,6 @@ public interface EntitySource extends Source {
     *
     * @return the entity
     */
-    @NonNull PlatformEntity getEntity();
+    PlatformEntity getEntity();

 }
@@ -27,8 +27,6 @@ package net.luckperms.api.event.source;

 import net.luckperms.api.platform.PlatformEntity;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 /**
 * Represents the source of an event.
 *
@@ -41,7 +39,7 @@ public interface Source {
     *
     * @return the type
     */
-    @NonNull Type getType();
+    Type getType();

    /**
     * Represents a type of source
@@ -26,4 +26,5 @@
 /**
 * Event sources.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.source;
@@ -0,0 +1,80 @@
+/*
+ * 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.jspecify.annotations.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)
+    UUID getSyncId();
+
+    /**
+     * Gets the sync type.
+     *
+     * @return the sync type
+     */
+    @Param(1)
+    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();
+
+}
@@ -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 {

@@ -28,13 +28,15 @@ 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.jspecify.annotations.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 {

@@ -44,6 +46,24 @@ public interface PreNetworkSyncEvent extends LuckPermsEvent, Cancellable {
     * @return the id of the sync request
     */
    @Param(0)
-    @NonNull UUID getSyncId();
+    UUID getSyncId();
+
+    /**
+     * Gets the sync type.
+     *
+     * @return the sync type
+     * @since 5.5
+     */
+    @Param(1)
+    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();

 }
@@ -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 {

@@ -23,20 +23,23 @@
 *  SOFTWARE.
 */

-package org.spongepowered.api.service.permission;
-
-import java.util.concurrent.CompletableFuture;
+package net.luckperms.api.event.sync;

 /**
- * This is included, as the interface didn't exist in API6.
- * We just shade it into the LP jar so we can still implement it. :)
+ * Represents the type of synchronisation task.
+ *
+ * @since 5.5
 */
-public interface SubjectReference {
+public enum SyncType {

-    String getCollectionIdentifier();
+    /**
+     * A full sync will be performed - all groups, users and tracks
+     */
+    FULL,

-    String getSubjectIdentifier();
+    /**
+     * Only a specific user will be synced
+     */
+    SPECIFIC_USER

-    CompletableFuture<Subject> resolve();
-
-}
+}
@@ -26,4 +26,5 @@
 /**
 * Events relating to {@link net.luckperms.api.LuckPerms#runUpdateTask() sync/update task}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.sync;
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a track is created
 */
@@ -43,7 +41,7 @@ public interface TrackCreateEvent extends LuckPermsEvent {
     * @return the new track
     */
    @Param(0)
-    @NonNull Track getTrack();
+    Track getTrack();

    /**
     * Gets the cause of the creation
@@ -51,6 +49,6 @@ public interface TrackCreateEvent extends LuckPermsEvent {
     * @return the cause of the creation
     */
    @Param(1)
-    @NonNull CreationCause getCause();
+    CreationCause getCause();

 }
@@ -29,8 +29,6 @@ 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;

 /**
@@ -44,7 +42,7 @@ public interface TrackDeleteEvent extends LuckPermsEvent {
     * @return the name of the deleted track
     */
    @Param(0)
-    @NonNull String getTrackName();
+    String getTrackName();

    /**
     * Gets an immutable copy of the tracks existing data
@@ -52,7 +50,7 @@ public interface TrackDeleteEvent extends LuckPermsEvent {
     * @return a copy of the tracks existing data
     */
    @Param(1)
-    @NonNull List<String> getExistingData();
+    List<String> getExistingData();

    /**
     * Gets the cause of the deletion
@@ -60,6 +58,6 @@ public interface TrackDeleteEvent extends LuckPermsEvent {
     * @return the cause of the deletion
     */
    @Param(2)
-    @NonNull DeletionCause getCause();
+    DeletionCause getCause();

 }
@@ -29,12 +29,10 @@ 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;
-
 /**
 * Called when a track is loaded into memory from the storage.
 *
- * Note that this event is not the same as {@link TrackCreateEvent}
+ * <p>Note that this event is not the same as {@link TrackCreateEvent}.</p>
 */
 public interface TrackLoadEvent extends LuckPermsEvent {

@@ -44,6 +42,6 @@ public interface TrackLoadEvent extends LuckPermsEvent {
     * @return the track that was loaded
     */
    @Param(0)
-    @NonNull Track getTrack();
+    Track getTrack();

 }
@@ -27,8 +27,6 @@ package net.luckperms.api.event.track.mutate;

 import net.luckperms.api.event.util.Param;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 /**
 * Called when a group is added to a track
 */
@@ -40,6 +38,6 @@ public interface TrackAddGroupEvent extends TrackMutateEvent {
     * @return the group that was added
     */
    @Param(3)
-    @NonNull String getGroup();
+    String getGroup();

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

 import java.util.List;
@@ -45,7 +43,7 @@ public interface TrackMutateEvent extends LuckPermsEvent {
     * @return the track that was mutated
     */
    @Param(0)
-    @NonNull Track getTrack();
+    Track getTrack();

    /**
     * Gets an immutable copy of the tracks data before the change
@@ -53,7 +51,7 @@ public interface TrackMutateEvent extends LuckPermsEvent {
     * @return the data before the change
     */
    @Param(1)
-    @NonNull @Unmodifiable List<String> getStateBefore();
+    @Unmodifiable List<String> getStateBefore();

    /**
     * Gets an immutable copy of the tracks data after the change
@@ -61,6 +59,6 @@ public interface TrackMutateEvent extends LuckPermsEvent {
     * @return the data after the change
     */
    @Param(2)
-    @NonNull @Unmodifiable List<String> getStateAfter();
+    @Unmodifiable List<String> getStateAfter();

 }
@@ -27,8 +27,6 @@ package net.luckperms.api.event.track.mutate;

 import net.luckperms.api.event.util.Param;

-import org.checkerframework.checker.nullness.qual.NonNull;
-
 /**
 * Called when a group is removed from a track
 */
@@ -40,6 +38,6 @@ public interface TrackRemoveGroupEvent extends TrackMutateEvent {
     * @return the group that was removed
     */
    @Param(3)
-    @NonNull String getGroup();
+    String getGroup();

 }
@@ -26,4 +26,5 @@
 /**
 * Events relating to changes to a {@link net.luckperms.api.track.Track}s contents.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.track.mutate;
@@ -26,4 +26,5 @@
 /**
 * Events relating to {@link net.luckperms.api.track.Track}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.track;
@@ -27,8 +27,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;

 /**
@@ -42,7 +40,7 @@ public interface Cancellable {
     * @return the cancellation
     */
    @Param(-1)
-    @NonNull AtomicBoolean cancellationState();
+    AtomicBoolean cancellationState();

    /**
     * Returns true if the event is currently cancelled.
@@ -26,8 +26,7 @@
 package net.luckperms.api.event.type;

 import net.luckperms.api.event.util.Param;
-
-import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jspecify.annotations.Nullable;

 import java.util.concurrent.atomic.AtomicReference;

@@ -37,7 +36,7 @@ import java.util.concurrent.atomic.AtomicReference;
 * @param <T> the type of the result
 * @since 5.3
 */
-public interface ResultEvent<T> {
+public interface ResultEvent<T extends @Nullable Object> {

    /**
     * Gets an {@link AtomicReference} containing the result.
@@ -45,7 +44,7 @@ public interface ResultEvent<T> {
     * @return the result
     */
    @Param(-1)
-    @NonNull AtomicReference<T> result();
+    AtomicReference<T> result();

    /**
     * Gets if a result has been set for the event.
@@ -28,8 +28,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;
-
 /**
 * Represents an event with a {@link Source}.
 */
@@ -43,6 +41,6 @@ public interface Sourced {
     *
     * @return the source
     */
-    @NonNull @Param(-1) Source getSource();
+    @Param(-1) Source getSource();

 }
@@ -26,4 +26,5 @@
 /**
 * Event abstract types.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.type;
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a users {@link CachedDataManager} is loaded.
 */
@@ -43,7 +41,7 @@ public interface UserCacheLoadEvent extends LuckPermsEvent {
     * @return the user
     */
    @Param(0)
-    @NonNull User getUser();
+    User getUser();

    /**
     * Gets the data that was loaded
@@ -51,6 +49,6 @@ public interface UserCacheLoadEvent extends LuckPermsEvent {
     * @return the loaded data
     */
    @Param(1)
-    @NonNull CachedDataManager getLoadedData();
+    CachedDataManager getLoadedData();

 }
@@ -30,8 +30,6 @@ 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;
-
 /**
 * Called when a users cached data is refreshed
 */
@@ -43,7 +41,7 @@ public interface UserDataRecalculateEvent extends LuckPermsEvent {
     * @return the user
     */
    @Param(0)
-    @NonNull User getUser();
+    User getUser();

    /**
     * Gets the data that was recalculated
@@ -51,6 +49,6 @@ public interface UserDataRecalculateEvent extends LuckPermsEvent {
     * @return the data
     */
    @Param(1)
-    @NonNull CachedDataManager getData();
+    CachedDataManager getData();

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

 /**
@@ -48,10 +46,10 @@ public interface UserFirstLoginEvent extends LuckPermsEvent {
    /**
     * Gets the UUID of the user
     *
-     * @return the uuid of the user
+     * @return the UUID of the user
     */
    @Param(0)
-    @NonNull UUID getUniqueId();
+    UUID getUniqueId();

    /**
     * Gets the username of the user
@@ -59,6 +57,6 @@ public interface UserFirstLoginEvent extends LuckPermsEvent {
     * @return the username of the user
     */
    @Param(1)
-    @NonNull String getUsername();
+    String getUsername();

 }
@@ -29,8 +29,6 @@ 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;
-
 /**
 * Called when a user is loaded into memory from the storage.
 */
@@ -42,6 +40,6 @@ public interface UserLoadEvent extends LuckPermsEvent {
     * @return the user that was loaded
     */
    @Param(0)
-    @NonNull User getUser();
+    User getUser();

 }
@@ -30,8 +30,6 @@ 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.
 *
@@ -45,6 +43,6 @@ public interface UserUnloadEvent extends LuckPermsEvent, Cancellable {
     * @return the user that is being unloaded
     */
    @Param(0)
-    @NonNull User getUser();
+    User getUser();

 }
@@ -26,4 +26,5 @@
 /**
 * Events relating to {@link net.luckperms.api.model.user.User}s.
 */
+@org.jspecify.annotations.NullMarked
 package net.luckperms.api.event.user;