Implement luckiness calculator

3rd time lucky...

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 ### :speech_balloon: Looking for support?
 
-Details about support for the project can be found [here, on the Wiki Homepage](https://github.com/lucko/LuckPerms/wiki#support).
+Details about support for the project can be found [here, on the Wiki Homepage](https://luckperms.net/wiki/Home#support).
 
 ### :bug: Reporting bugs?
 
@@ -16,11 +16,11 @@ If you make any changes or improvements to the plugin which you think would be b
 
 LuckPerms loosely follows the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Generally, try to copy the style of code found in the class you're editing. 
 
-If you're considering submitting a substantial pull request, please open an issue so we can discuss the change before starting work on the contribution. Most pull requests are happily accepted, but larger changes may have an inpact on the maintainability of the project, and require more consideration. 
+If you're considering submitting a substantial pull request, please open an issue so we can discuss the change before starting work on the contribution. Most pull requests are happily accepted, but larger changes may have an impact on the maintainability of the project, and require more consideration. 
 
 #### Project Layout
-The project is split up into a few seperate modules.
+The project is split up into a few separate modules.
 
 * **API** - The public, semantically versioned API used by other plugins wishing to integrate with and retrieve data from LuckPerms. This module (for the most part) does not contain any implementation itself, and is provided by the plugin.
 * **Common** - The common module contains most of the code which implements the respective LuckPerms plugins. This abstract module reduces duplicated code throughout the project.
-* **Bukkit, BungeeCord, Sponge, Nukkit & Velocity** - Each use the common module to implement plugins on the respective server platforms.
+* **Bukkit, BungeeCord, Sponge, Nukkit, Velocity & Fabric** - Each use the common module to implement plugins on the respective server platforms.

README.md

@@ -1,12 +1,14 @@
-![alt text](https://i.imgur.com/ToguFkQ.png "Banner")
+![](https://i.imgur.com/ToguFkQ.png "Banner")
 # LuckPerms
 [![Build Status](https://ci.lucko.me/job/LuckPerms/badge/icon)](https://ci.lucko.me/job/LuckPerms/)
 [![javadoc](https://javadoc.io/badge2/net.luckperms/api/javadoc.svg)](https://javadoc.io/doc/net.luckperms/api)
 [![Maven Central](https://img.shields.io/maven-metadata/v/https/repo1.maven.org/maven2/net/luckperms/api/maven-metadata.xml.svg?label=maven%20central&colorB=brightgreen)](https://search.maven.org/artifact/net.luckperms/api)
-[![Discord](https://img.shields.io/discord/241667244927483904.svg?logo=discord&label=)](https://discord.gg/luckperms)
+[![Discord](https://img.shields.io/discord/241667244927483904.svg?label=discord&logo=discord)](https://discord.gg/luckperms)
 
 LuckPerms is a permissions plugin for Minecraft servers. It allows server admins to control what features players can use by creating groups and assigning permissions.
 
+The latest downloads, wiki & other useful links can be found on the project homepage at [luckperms.net](https://luckperms.net/).
+
 It is:
 
 * **fast** - written with performance and scalability in mind.
@@ -16,10 +18,7 @@ It is:
 * **extensive** - a plethora of customization options and settings which can be changed to suit your server.
 * **free** - available for download and usage at no cost, and permissively licensed so it can remain free forever.
 
-For more information, see the wiki article on [Why LuckPerms?](https://github.com/lucko/LuckPerms/wiki/Why-LuckPerms)
-
-## Useful Links
-The latest downloads & other useful links can be found on the project homepage at [luckperms.net](https://luckperms.net/).
+For more information, see the wiki article on [Why LuckPerms?](https://luckperms.net/wiki/Why-LuckPerms)
 
 ## Building
 LuckPerms uses Gradle to handle dependencies & building.
@@ -35,7 +34,7 @@ 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.
 
 ## Contributing
 #### Pull Requests
@@ -48,7 +47,7 @@ The project is split up into a few separate modules.
 
 * **API** - The public, semantically versioned API used by other plugins wishing to integrate with and retrieve data from LuckPerms. This module (for the most part) does not contain any implementation itself, and is provided by the plugin.
 * **Common** - The common module contains most of the code which implements the respective LuckPerms plugins. This abstract module reduces duplicated code throughout the project.
-* **Bukkit, BungeeCord, Sponge, Nukkit & Velocity** - Each use the common module to implement plugins on the respective server platforms.
+* **Bukkit, BungeeCord, Sponge, Fabric, Nukkit & 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.

api/build.gradle

@@ -1,8 +1,9 @@
 group = 'net.luckperms'
-project.version = '5.2'
+project.version = '5.3'
 
 dependencies {
-    compileOnly 'org.checkerframework:checker-qual:2.5.5'
+    compileOnly 'org.checkerframework:checker-qual:3.8.0'
+    compileOnly 'org.jetbrains:annotations:20.1.0'
 }
 
 // Only used occasionally for deployment - not needed for normal builds.
@@ -12,10 +13,13 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass
 
     javadoc {
         title = 'LuckPerms API (v' + project.ext.apiVersion + ')'
+        options.overview = 'javadoc/overview.html'
         options.encoding = 'UTF-8'
         options.charSet = 'UTF-8'
         options.links(
-                'https://docs.oracle.com/javase/8/docs/api/'
+                'https://docs.oracle.com/javase/8/docs/api/',
+                'https://checkerframework.org/api/',
+                'https://javadoc.io/static/org.jetbrains/annotations/20.1.0/'
         )
         options.addStringOption('Xdoclint:none', '-quiet')
     }

api/javadoc/overview.html

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

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

@@ -48,6 +48,7 @@ import net.luckperms.api.track.Track;
 import net.luckperms.api.track.TrackManager;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
@@ -131,6 +132,7 @@ public interface LuckPerms {
      * <li>{@code org.bukkit.entity.Player}</li>
      * <li>{@code net.md_5.bungee.api.connection.ProxiedPlayer}</li>
      * <li>{@code org.spongepowered.api/entity.living.player.Player}</li>
+     * <li>{@code net.minecraft.server.network.ServerPlayerEntity} (Fabric)</li>
      * <li>{@code cn.nukkit.Player}</li>
      * <li>{@code com.velocitypowered.api.proxy.Player}</li>
      * </ul>
@@ -194,21 +196,6 @@ public interface LuckPerms {
      */
     @NonNull ContextManager getContextManager();
 
-    /**
-     * Gets the {@link NodeBuilderRegistry}.
-     *
-     * @return the node builder registry
-     */
-    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
-
-    /**
-     * Gets the {@link QueryOptionsRegistry}.
-     *
-     * @return the query options registry
-     * @since 5.1
-     */
-    @NonNull QueryOptionsRegistry getQueryOptionsRegistry();
-
     /**
      * Gets the {@link MetaStackFactory}.
      *
@@ -220,14 +207,6 @@ public interface LuckPerms {
      */
     @NonNull MetaStackFactory getMetaStackFactory();
 
-    /**
-     * Gets the {@link NodeMatcherFactory}.
-     *
-     * @return the node matcher factory
-     * @since 5.1
-     */
-    @NonNull NodeMatcherFactory getNodeMatcherFactory();
-
     /**
      * Schedules the execution of an update task, and returns an encapsulation
      * of the task as a {@link CompletableFuture}.
@@ -251,4 +230,30 @@ public interface LuckPerms {
      */
     void registerMessengerProvider(@NonNull MessengerProvider messengerProvider);
 
+    /**
+     * Gets the {@link NodeBuilderRegistry}.
+     *
+     * @return the node builder registry
+     */
+    @Internal
+    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
+
+    /**
+     * Gets the {@link QueryOptionsRegistry}.
+     *
+     * @return the query options registry
+     * @since 5.1
+     */
+    @Internal
+    @NonNull QueryOptionsRegistry getQueryOptionsRegistry();
+
+    /**
+     * Gets the {@link NodeMatcherFactory}.
+     *
+     * @return the node matcher factory
+     * @since 5.1
+     */
+    @Internal
+    @NonNull NodeMatcherFactory getNodeMatcherFactory();
+
 }

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

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

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

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

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

@@ -26,6 +26,7 @@
 package net.luckperms.api.actionlog;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.SortedSet;
 import java.util.UUID;
@@ -47,7 +48,7 @@ public interface ActionLog {
      *
      * @return the content
      */
-    @NonNull SortedSet<Action> getContent();
+    @NonNull @Unmodifiable SortedSet<Action> getContent();
 
     /**
      * Gets the entries in the log performed by the given actor.
@@ -55,7 +56,7 @@ public interface ActionLog {
      * @param actor the uuid of the actor to filter by
      * @return the content for the given actor
      */
-    @NonNull SortedSet<Action> getContent(@NonNull UUID actor);
+    @NonNull @Unmodifiable SortedSet<Action> getContent(@NonNull UUID actor);
 
     /**
      * Gets the log content for a given user
@@ -63,7 +64,7 @@ public interface ActionLog {
      * @param uniqueId the uuid to filter by
      * @return all content in this log where the user = uuid
      */
-    @NonNull SortedSet<Action> getUserHistory(@NonNull UUID uniqueId);
+    @NonNull @Unmodifiable SortedSet<Action> getUserHistory(@NonNull UUID uniqueId);
 
     /**
      * Gets the log content for a given group
@@ -71,7 +72,7 @@ public interface ActionLog {
      * @param name the name to filter by
      * @return all content in this log where the group = name
      */
-    @NonNull SortedSet<Action> getGroupHistory(@NonNull String name);
+    @NonNull @Unmodifiable SortedSet<Action> getGroupHistory(@NonNull String name);
 
     /**
      * Gets the log content for a given track
@@ -79,6 +80,6 @@ public interface ActionLog {
      * @param name the name to filter by
      * @return all content in this log where the track = name
      */
-    @NonNull SortedSet<Action> getTrackHistory(@NonNull String name);
+    @NonNull @Unmodifiable SortedSet<Action> getTrackHistory(@NonNull String name);
 
 }

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

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

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

@@ -29,10 +29,13 @@ import net.luckperms.api.metastacking.MetaStackDefinition;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.SortedMap;
+import java.util.function.Function;
 
 /**
  * Holds cached meta lookup data for a specific set of contexts.
@@ -45,7 +48,37 @@ public interface CachedMetaData extends CachedData {
      * @param key the key
      * @return the value
      */
-    @Nullable String getMetaValue(String key);
+    @Nullable String getMetaValue(@NonNull String key);
+
+    /**
+     * Gets a value for the given meta key, and runs it through the given {@code transformer}.
+     *
+     * <p>If no such meta value exists, an {@link Optional#empty() empty optional} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in an {@link Optional#empty() empty optional} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     getMetaValue("my-int-val", Integer::parseInt).orElse(0);
+     * </pre></blockquote>
+     *
+     * @param key the key
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the meta value
+     * @since 5.3
+     */
+    default <T> @NonNull Optional<T> getMetaValue(@NonNull String key, @NonNull Function<String, ? extends T> valueTransformer) {
+        return Optional.ofNullable(getMetaValue(key)).map(value -> {
+            try {
+                return valueTransformer.apply(value);
+            } catch (IllegalArgumentException e) {
+                return null;
+            }
+        });
+    }
 
     /**
      * Gets the holder's highest priority prefix, or null if the holder has no prefixes
@@ -66,7 +99,7 @@ public interface CachedMetaData extends CachedData {
      *
      * @return an immutable map of meta
      */
-    @NonNull Map<String, List<String>> getMeta();
+    @NonNull @Unmodifiable Map<String, List<String>> getMeta();
 
     /**
      * Gets an immutable sorted map of all of the prefixes the holder has, whereby the first
@@ -74,7 +107,7 @@ public interface CachedMetaData extends CachedData {
      *
      * @return a sorted map of prefixes
      */
-    @NonNull SortedMap<Integer, String> getPrefixes();
+    @NonNull @Unmodifiable SortedMap<Integer, String> getPrefixes();
 
     /**
      * Gets an immutable sorted map of all of the suffixes the holder has, whereby the first
@@ -82,7 +115,7 @@ public interface CachedMetaData extends CachedData {
      *
      * @return a sorted map of suffixes
      */
-    @NonNull SortedMap<Integer, String> getSuffixes();
+    @NonNull @Unmodifiable SortedMap<Integer, String> getSuffixes();
 
     /**
      * Gets the name of the holders primary group.

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

@@ -28,6 +28,7 @@ package net.luckperms.api.cacheddata;
 import net.luckperms.api.util.Tristate;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Map;
 
@@ -57,6 +58,6 @@ public interface CachedPermissionData extends CachedData {
      *
      * @return an immutable set of permissions
      */
-    @NonNull Map<String, Boolean> getPermissionMap();
+    @NonNull @Unmodifiable Map<String, Boolean> getPermissionMap();
 
 }

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -67,7 +67,7 @@ public interface ImmutableContextSet extends ContextSet {
     }
 
     /**
-     * @deprecated Already immutable!
+     * @deprecated This context set is already immutable!
      */
     @Override
     @Deprecated

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -23,32 +23,37 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.bukkit.migration;
+package net.luckperms.api.event.type;
 
-import me.lucko.luckperms.common.util.ProgressLogger;
-import me.lucko.luckperms.common.util.Uuids;
+import net.luckperms.api.event.util.Param;
 
-import org.bukkit.Bukkit;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import java.util.UUID;
+import java.util.concurrent.atomic.AtomicReference;
 
-public final class BukkitUuids {
-    private BukkitUuids() {}
+/**
+ * Represents an event that has a result.
+ *
+ * @param <T> the type of the result
+ * @since 5.3
+ */
+public interface ResultEvent<T> {
 
-    public static UUID lookupUuid(ProgressLogger log, String s) {
-        UUID uuid = Uuids.parse(s);
-        if (uuid == null) {
-            try {
-                //noinspection deprecation
-                uuid = Bukkit.getOfflinePlayer(s).getUniqueId();
-            } catch (Exception ex) {
-                ex.printStackTrace();
-            }
-        }
-        if (uuid == null) {
-            log.logError("Unable to get a UUID for user identifier: " + s);
-        }
-        return uuid;
+    /**
+     * Gets an {@link AtomicReference} containing the result.
+     *
+     * @return the result
+     */
+    @Param(-1)
+    @NonNull AtomicReference<T> result();
+
+    /**
+     * Gets if a result has been set for the event.
+     *
+     * @return if there is a result
+     */
+    default boolean hasResult() {
+        return result().get() != null;
     }
 
 }

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

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

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

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

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

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

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

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

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

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

api/src/main/java/net/luckperms/api/extension/ExtensionManager.java

@@ -26,6 +26,7 @@
 package net.luckperms.api.extension;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.io.IOException;
 import java.nio.file.Path;
@@ -57,6 +58,6 @@ public interface ExtensionManager {
      *
      * @return the loaded extensions
      */
-    @NonNull Collection<Extension> getLoadedExtensions();
+    @NonNull @Unmodifiable Collection<Extension> getLoadedExtensions();
 
 }

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

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

api/src/main/java/net/luckperms/api/messaging/MessagingService.java

@@ -40,7 +40,7 @@ public interface MessagingService {
      *
      * @return the name of this messaging service
      */
-    String getName();
+    @NonNull String getName();
 
     /**
      * Uses the messaging service to inform other servers about a general

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

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

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

@@ -29,11 +29,13 @@ import net.luckperms.api.messenger.message.Message;
 import net.luckperms.api.messenger.message.OutgoingMessage;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 /**
  * Encapsulates the LuckPerms system which accepts incoming {@link Message}s
  * from implementations of {@link Messenger}.
  */
+@NonExtendable
 public interface IncomingMessageConsumer {
 
     /**

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

@@ -29,10 +29,12 @@ import net.luckperms.api.messenger.message.Message;
 import net.luckperms.api.messenger.message.OutgoingMessage;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.OverrideOnly;
 
 /**
  * Represents an object which dispatches {@link OutgoingMessage}s.
  */
+@OverrideOnly
 public interface Messenger extends AutoCloseable {
 
     /**

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

@@ -28,6 +28,7 @@ package net.luckperms.api.messenger;
 import net.luckperms.api.LuckPerms;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.OverrideOnly;
 
 /**
  * Represents a provider for {@link Messenger} instances.
@@ -37,6 +38,7 @@ import org.checkerframework.checker.nullness.qual.NonNull;
  *
  * @see LuckPerms#registerMessengerProvider(MessengerProvider)
  */
+@OverrideOnly
 public interface MessengerProvider {
 
     /**

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

@@ -28,12 +28,14 @@ package net.luckperms.api.messenger.message;
 import net.luckperms.api.messenger.Messenger;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.util.UUID;
 
 /**
  * Represents a message sent received via a {@link Messenger}.
  */
+@NonExtendable
 public interface Message {
 
     /**

api/src/main/java/net/luckperms/api/messenger/message/package-info.java

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

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

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

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

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

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

@@ -28,6 +28,7 @@ package net.luckperms.api.metastacking;
 import net.luckperms.api.query.OptionKey;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.List;
 
@@ -57,7 +58,7 @@ public interface MetaStackDefinition {
      *
      * @return the elements in this stack
      */
-    @NonNull List<MetaStackElement> getElements();
+    @NonNull @Unmodifiable List<MetaStackElement> getElements();
 
     /**
      * Gets the duplicate removal function, applied to the entries before

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

@@ -26,6 +26,7 @@
 package net.luckperms.api.metastacking;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.List;
 import java.util.Optional;
@@ -51,7 +52,7 @@ public interface MetaStackFactory {
      * @param definitions the definition strings
      * @return a list of parsed elements
      */
-    @NonNull List<MetaStackElement> fromStrings(@NonNull List<String> definitions);
+    @NonNull @Unmodifiable List<MetaStackElement> fromStrings(@NonNull List<String> definitions);
 
     /**
      * Creates a new {@link MetaStackDefinition} with the given properties.

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

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

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

@@ -37,6 +37,7 @@ import net.luckperms.api.query.Flag;
 import net.luckperms.api.query.QueryOptions;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.ArrayList;
 import java.util.Collection;
@@ -186,7 +187,7 @@ public interface PermissionHolder {
      *
      * @return a collection of the holders own nodes.
      */
-    default @NonNull Collection<Node> getNodes() {
+    default @NonNull @Unmodifiable Collection<Node> getNodes() {
         /* This default method is overridden in the implementation, and is just here
            to demonstrate what this method does in the API sources. */
         List<Node> nodes = new ArrayList<>();
@@ -204,7 +205,7 @@ public interface PermissionHolder {
      * @see #getNodes()
      * @since 5.1
      */
-    default <T extends Node> @NonNull Collection<T> getNodes(@NonNull NodeType<T> type) {
+    default <T extends Node> @NonNull @Unmodifiable Collection<T> getNodes(@NonNull NodeType<T> type) {
         /* This default method is overridden in the implementation, and is just here
            to demonstrate what this method does in the API sources. */
         return getNodes().stream()
@@ -223,7 +224,7 @@ public interface PermissionHolder {
      *
      * @return a sorted set of the holders own distinct nodes
      */
-    @NonNull SortedSet<Node> getDistinctNodes();
+    @NonNull @Unmodifiable SortedSet<Node> getDistinctNodes();
 
     /**
      * Gets a resolved view of the holders own and inherited {@link Node}s.
@@ -240,7 +241,7 @@ public interface PermissionHolder {
      * @param queryOptions the query options
      * @return a list of the holders inherited nodes
      */
-    @NonNull Collection<Node> resolveInheritedNodes(@NonNull QueryOptions queryOptions);
+    @NonNull @Unmodifiable Collection<Node> resolveInheritedNodes(@NonNull QueryOptions queryOptions);
 
     /**
      * Gets a resolved view of the holders own and inherited {@link Node}s of a given {@code type}.
@@ -252,7 +253,7 @@ public interface PermissionHolder {
      * @see #resolveInheritedNodes(QueryOptions)
      * @since 5.1
      */
-    default <T extends Node> @NonNull Collection<T> resolveInheritedNodes(@NonNull NodeType<T> type, @NonNull QueryOptions queryOptions) {
+    default <T extends Node> @NonNull @Unmodifiable Collection<T> resolveInheritedNodes(@NonNull NodeType<T> type, @NonNull QueryOptions queryOptions) {
         /* This default method is overridden in the implementation, and is just here
            to demonstrate what this method does in the API sources. */
         return resolveInheritedNodes(queryOptions).stream()
@@ -275,7 +276,7 @@ public interface PermissionHolder {
      * @param queryOptions the query options
      * @return a sorted set of the holders distinct inherited nodes
      */
-    @NonNull SortedSet<Node> resolveDistinctInheritedNodes(@NonNull QueryOptions queryOptions);
+    @NonNull @Unmodifiable SortedSet<Node> resolveDistinctInheritedNodes(@NonNull QueryOptions queryOptions);
 
     /**
      * Gets a collection of the {@link Group}s this holder inherits nodes from.
@@ -296,7 +297,7 @@ public interface PermissionHolder {
      * @return a collection of the groups the holder inherits from
      * @since 5.1
      */
-    @NonNull Collection<Group> getInheritedGroups(@NonNull QueryOptions queryOptions);
+    @NonNull @Unmodifiable Collection<Group> getInheritedGroups(@NonNull QueryOptions queryOptions);
 
     /**
      * Removes any temporary permissions that have expired.

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

@@ -29,6 +29,7 @@ import net.luckperms.api.model.user.UserManager;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Objects;
 import java.util.Set;
@@ -47,7 +48,7 @@ public interface PlayerSaveResult {
      *
      * @return the status
      */
-    @NonNull Set<Outcome> getOutcomes();
+    @NonNull @Unmodifiable Set<Outcome> getOutcomes();
 
     /**
      * Gets if the result includes a certain outcome.
@@ -80,7 +81,7 @@ public interface PlayerSaveResult {
      * @return the other uuids
      * @see Outcome#OTHER_UNIQUE_IDS_PRESENT_FOR_USERNAME
      */
-    @Nullable Set<UUID> getOtherUniqueIds();
+    @Nullable @Unmodifiable Set<UUID> getOtherUniqueIds();
 
     /**
      * The various states the result can take

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

@@ -37,6 +37,7 @@ import net.luckperms.api.node.NodeEqualityPredicate;
 import net.luckperms.api.util.Tristate;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Collection;
 import java.util.Map;
@@ -65,7 +66,7 @@ public interface NodeMap {
      *
      * @return a map of nodes
      */
-    @NonNull Map<ImmutableContextSet, Collection<Node>> toMap();
+    @NonNull @Unmodifiable Map<ImmutableContextSet, Collection<Node>> toMap();
 
     /**
      * Gets a flattened view of {@link Node}s contained within this instance.
@@ -75,7 +76,7 @@ public interface NodeMap {
      *
      * @return a flattened collection of nodes
      */
-    @NonNull Collection<Node> toCollection();
+    @NonNull @Unmodifiable Collection<Node> toCollection();
 
     /**
      * Gets if this instance contains a given {@link Node}.

api/src/main/java/net/luckperms/api/model/data/package-info.java

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

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

@@ -31,6 +31,7 @@ import net.luckperms.api.node.matcher.NodeMatcher;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Collection;
 import java.util.List;
@@ -138,7 +139,7 @@ public interface GroupManager {
      * @return the entries which matched
      * @since 5.1
      */
-    @NonNull <T extends Node> CompletableFuture<Map<String, Collection<T>>> searchAll(@NonNull NodeMatcher<? extends T> matcher);
+    <T extends Node> @NonNull CompletableFuture<@Unmodifiable Map<String, Collection<T>>> searchAll(@NonNull NodeMatcher<? extends T> matcher);
 
     /**
      * Searches for a list of groups with a given permission.
@@ -146,10 +147,10 @@ public interface GroupManager {
      * @param permission the permission to search for
      * @return a list of held permissions, or null if the operation failed
      * @throws NullPointerException if the permission is null
-     * @deprecated use {@link #searchAll(NodeMatcher)}
+     * @deprecated Use {@link #searchAll(NodeMatcher)} instead
      */
     @Deprecated
-    @NonNull CompletableFuture<List<HeldNode<String>>> getWithPermission(@NonNull String permission);
+    @NonNull CompletableFuture<@Unmodifiable List<HeldNode<String>>> getWithPermission(@NonNull String permission);
 
     /**
      * Gets a loaded group.
@@ -165,7 +166,7 @@ public interface GroupManager {
      *
      * @return a {@link Set} of {@link Group} objects
      */
-    @NonNull Set<Group> getLoadedGroups();
+    @NonNull @Unmodifiable Set<Group> getLoadedGroups();
 
     /**
      * Check if a group is loaded in memory

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

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

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

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

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

@@ -32,6 +32,7 @@ import net.luckperms.api.node.matcher.NodeMatcher;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.util.Collection;
 import java.util.List;
@@ -165,7 +166,7 @@ public interface UserManager {
      *
      * @return a set of uuids
      */
-    @NonNull CompletableFuture<Set<UUID>> getUniqueUsers();
+    @NonNull CompletableFuture<@Unmodifiable Set<UUID>> getUniqueUsers();
 
     /**
      * Searches the {@link User#data() normal node maps} of all known {@link User}s for {@link Node}
@@ -175,7 +176,7 @@ public interface UserManager {
      * @return the entries which matched
      * @since 5.1
      */
-    @NonNull <T extends Node> CompletableFuture<Map<UUID, Collection<T>>> searchAll(@NonNull NodeMatcher<? extends T> matcher);
+    <T extends Node> @NonNull CompletableFuture<@Unmodifiable Map<UUID, Collection<T>>> searchAll(@NonNull NodeMatcher<? extends T> matcher);
 
     /**
      * Searches for a list of users with a given permission.
@@ -183,10 +184,10 @@ public interface UserManager {
      * @param permission the permission to search for
      * @return a list of held permissions
      * @throws NullPointerException if the permission is null
-     * @deprecated use {@link #searchAll(NodeMatcher)}
+     * @deprecated Use {@link #searchAll(NodeMatcher)} instead
      */
     @Deprecated
-    @NonNull CompletableFuture<List<HeldNode<UUID>>> getWithPermission(@NonNull String permission);
+    @NonNull CompletableFuture<@Unmodifiable List<HeldNode<UUID>>> getWithPermission(@NonNull String permission);
 
     /**
      * Gets a loaded user.
@@ -211,7 +212,7 @@ public interface UserManager {
      *
      * @return a {@link Set} of {@link User} objects
      */
-    @NonNull Set<User> getLoadedUsers();
+    @NonNull @Unmodifiable Set<User> getLoadedUsers();
 
     /**
      * Check if a user is loaded in memory

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

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

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

@@ -33,6 +33,7 @@ import org.checkerframework.checker.nullness.qual.NonNull;
  * A relationship between a {@link PermissionHolder} and a {@link Node}.
  *
  * @param <T> the identifier type of the holder
+ * @deprecated The only usages of this interface are also deprecated.
  */
 @Deprecated
 public interface HeldNode<T> {

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

@@ -39,6 +39,8 @@ import net.luckperms.api.node.types.WeightNode;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.time.Duration;
 import java.time.Instant;
@@ -97,6 +99,7 @@ import java.util.stream.Stream;
  *
  * <p>The core node state must be immutable in all implementations.</p>
  */
+@NonExtendable
 public interface Node {
 
     /**
@@ -151,7 +154,7 @@ public interface Node {
      *
      * @return a list of full nodes
      */
-    @NonNull Collection<String> resolveShorthand();
+    @NonNull @Unmodifiable Collection<String> resolveShorthand();
 
     /**
      * Gets if this node is assigned temporarily.
@@ -198,11 +201,11 @@ public interface Node {
     /**
      * Gets the metadata corresponding to the given <code>key</code>, if present.
      *
-     * @param key the key
      * @param <T> the metadata type
+     * @param key the key
      * @return the data, if present
      */
-    <T> Optional<T> getMetadata(NodeMetadataKey<T> key);
+    <T> Optional<T> getMetadata(@NonNull NodeMetadataKey<T> key);
 
     /**
      * Gets the metadata corresponding to the given <code>key</code>, throwing an exception
@@ -213,7 +216,7 @@ public interface Node {
      * @return the data
      * @throws IllegalStateException if data isn't present
      */
-    default <T> T metadata(NodeMetadataKey<T> key) throws IllegalStateException {
+    default <T> T metadata(@NonNull NodeMetadataKey<T> key) throws IllegalStateException {
         return getMetadata(key).orElseThrow(() -> new IllegalStateException("Node '" + getKey() + "' does not have '" + key.name() + "' attached."));
     }
 

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

@@ -30,6 +30,7 @@ import net.luckperms.api.node.metadata.NodeMetadataKey;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.time.Duration;
 import java.time.temporal.TemporalAccessor;
@@ -43,6 +44,7 @@ import java.util.concurrent.TimeUnit;
  * @param <N> the node type
  * @param <B> the node builder type
  */
+@NonExtendable
 public interface NodeBuilder<N extends ScopedNode<N, B>, B extends NodeBuilder<N, B>> {
 
     /**
@@ -107,7 +109,7 @@ public interface NodeBuilder<N extends ScopedNode<N, B>, B extends NodeBuilder<N
      * @param unit     the unit <code>duration</code> is measured in
      * @return the builder
      */
-    default @NonNull B expiry(long duration, TimeUnit unit) {
+    default @NonNull B expiry(long duration, @NonNull TimeUnit unit) {
         if (duration <= 0) {
             throw new IllegalArgumentException("duration must be positive");
         }
@@ -161,7 +163,7 @@ public interface NodeBuilder<N extends ScopedNode<N, B>, B extends NodeBuilder<N
      * @param <T> the metadata type
      * @return the builder
      */
-    @NonNull <T> B withMetadata(@NonNull NodeMetadataKey<T> key, @Nullable T metadata);
+    <T> @NonNull B withMetadata(@NonNull NodeMetadataKey<T> key, @Nullable T metadata);
 
     /**
      * Creates a {@link Node} instance from the builder.

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

@@ -35,17 +35,19 @@ import net.luckperms.api.node.types.SuffixNode;
 import net.luckperms.api.node.types.WeightNode;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 /**
  * A registry of methods for obtaining {@link NodeBuilder}s for the various
  * node types.
  */
+@Internal
 public interface NodeBuilderRegistry {
 
     /**
      * Gets a {@link NodeBuilder} applicable for the given key.
      *
-     * <p>Prefer using the {@link Node#builder(String)} accessor.</p>
+     * <p>Prefer using the {@link Node#builder(String)} method.</p>
      *
      * @param key the key
      * @return the node builder
@@ -56,7 +58,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link PermissionNode}s.
      *
-     * <p>Prefer using the {@link PermissionNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link PermissionNode#builder()} method.</p>
      *
      * @return the node builder
      * @see PermissionNode#builder()
@@ -66,7 +68,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link RegexPermissionNode}s.
      *
-     * <p>Prefer using the {@link RegexPermissionNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link RegexPermissionNode#builder()} method.</p>
      *
      * @return the node builder
      * @see RegexPermissionNode#builder()
@@ -76,7 +78,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link InheritanceNode}s.
      *
-     * <p>Prefer using the {@link InheritanceNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link InheritanceNode#builder()} method.</p>
      *
      * @return the node builder
      * @see InheritanceNode#builder()
@@ -86,7 +88,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link PrefixNode}s.
      *
-     * <p>Prefer using the {@link PrefixNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link PrefixNode#builder()} method.</p>
      *
      * @return the node builder
      * @see PrefixNode#builder()
@@ -96,7 +98,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link SuffixNode}s.
      *
-     * <p>Prefer using the {@link SuffixNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link SuffixNode#builder()} method.</p>
      *
      * @return the node builder
      * @see SuffixNode#builder()
@@ -106,7 +108,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link MetaNode}s.
      *
-     * <p>Prefer using the {@link MetaNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link MetaNode#builder()} method.</p>
      *
      * @return the node builder
      * @see MetaNode#builder()
@@ -116,7 +118,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link WeightNode}s.
      *
-     * <p>Prefer using the {@link WeightNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link WeightNode#builder()} method.</p>
      *
      * @return the node builder
      * @see WeightNode#builder()
@@ -126,7 +128,7 @@ public interface NodeBuilderRegistry {
     /**
      * Gets a {@link NodeBuilder} for {@link DisplayNameNode}s.
      *
-     * <p>Prefer using the {@link DisplayNameNode#builder()} accessor.</p>
+     * <p>Prefer using the {@link DisplayNameNode#builder()} method.</p>
      *
      * @return the node builder
      * @see DisplayNameNode#builder()

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

@@ -35,6 +35,8 @@ import net.luckperms.api.node.types.RegexPermissionNode;
 import net.luckperms.api.node.types.SuffixNode;
 import net.luckperms.api.node.types.WeightNode;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Function;
@@ -48,59 +50,105 @@ public interface NodeType<T extends Node> {
     /**
      * Node type for {@link PermissionNode}.
      */
-    NodeType<PermissionNode> PERMISSION = new SimpleNodeType<>("PERMISSION", n ->  n instanceof PermissionNode, n -> ((PermissionNode) n));
+    NodeType<PermissionNode> PERMISSION = new SimpleNodeType<>(
+            "PERMISSION",
+            n -> n instanceof PermissionNode,
+            n -> (PermissionNode) n
+    );
 
     /**
      * Node type for {@link RegexPermissionNode}.
      */
-    NodeType<RegexPermissionNode> REGEX_PERMISSION = new SimpleNodeType<>("REGEX_PERMISSION", n ->  n instanceof RegexPermissionNode, n -> ((RegexPermissionNode) n));
+    NodeType<RegexPermissionNode> REGEX_PERMISSION = new SimpleNodeType<>(
+            "REGEX_PERMISSION",
+            n -> n instanceof RegexPermissionNode,
+            n -> (RegexPermissionNode) n
+    );
 
     /**
      * Node type for {@link InheritanceNode}.
      */
-    NodeType<InheritanceNode> INHERITANCE = new SimpleNodeType<>("INHERITANCE", n ->  n instanceof InheritanceNode, n -> ((InheritanceNode) n));
+    NodeType<InheritanceNode> INHERITANCE = new SimpleNodeType<>(
+            "INHERITANCE",
+            n -> n instanceof InheritanceNode,
+            n -> (InheritanceNode) n
+    );
 
     /**
      * Node type for {@link PrefixNode}.
      */
-    NodeType<PrefixNode> PREFIX = new SimpleNodeType<>("PREFIX", n ->  n instanceof PrefixNode, n -> ((PrefixNode) n));
+    NodeType<PrefixNode> PREFIX = new SimpleNodeType<>(
+            "PREFIX",
+            n -> n instanceof PrefixNode,
+            n -> (PrefixNode) n
+    );
 
     /**
      * Node type for {@link SuffixNode}.
      */
-    NodeType<SuffixNode> SUFFIX = new SimpleNodeType<>("SUFFIX", n ->  n instanceof SuffixNode, n -> ((SuffixNode) n));
+    NodeType<SuffixNode> SUFFIX = new SimpleNodeType<>(
+            "SUFFIX",
+            n -> n instanceof SuffixNode,
+            n -> (SuffixNode) n
+    );
 
     /**
      * Node type for {@link MetaNode}.
      */
-    NodeType<MetaNode> META = new SimpleNodeType<>("META", n ->  n instanceof MetaNode, n -> ((MetaNode) n));
+    NodeType<MetaNode> META = new SimpleNodeType<>(
+            "META",
+            n -> n instanceof MetaNode,
+            n -> (MetaNode) n
+    );
 
     /**
      * Node type for {@link WeightNode}.
      */
-    NodeType<WeightNode> WEIGHT = new SimpleNodeType<>("WEIGHT", n ->  n instanceof WeightNode, n -> ((WeightNode) n));
+    NodeType<WeightNode> WEIGHT = new SimpleNodeType<>(
+            "WEIGHT",
+            n -> n instanceof WeightNode,
+            n -> (WeightNode) n
+    );
 
     /**
      * Node type for {@link DisplayNameNode}.
      */
-    NodeType<DisplayNameNode> DISPLAY_NAME = new SimpleNodeType<>("DISPLAY_NAME", n ->  n instanceof DisplayNameNode, n -> ((DisplayNameNode) n));
+    NodeType<DisplayNameNode> DISPLAY_NAME = new SimpleNodeType<>(
+            "DISPLAY_NAME",
+            n -> n instanceof DisplayNameNode,
+            n -> (DisplayNameNode) n
+    );
 
     /**
      * Node type for {@link ChatMetaNode}.
+     *
+     * <p>This is an abstract type, and therefore will never
+     * be returned from {@link Node#getType()}.</p>
      */
-    NodeType<ChatMetaNode<?, ?>> CHAT_META = new SimpleNodeType<>("CHAT_META", n ->  n instanceof ChatMetaNode<?, ?>, n -> ((ChatMetaNode<?, ?>) n));
+    NodeType<ChatMetaNode<?, ?>> CHAT_META = new SimpleNodeType<>(
+            "CHAT_META",
+            n -> n instanceof ChatMetaNode<?, ?>,
+            n -> (ChatMetaNode<?, ?>) n
+    );
 
     /**
      * Node type for {@link ChatMetaNode} or {@link MetaNode}.
+     *
+     * <p>This is an abstract type, and therefore will never
+     * be returned from {@link Node#getType()}.</p>
      */
-    NodeType<Node> META_OR_CHAT_META = new SimpleNodeType<>("META_OR_CHAT_META", n ->  META.matches(n) || CHAT_META.matches(n), Function.identity());
+    NodeType<Node> META_OR_CHAT_META = new SimpleNodeType<>(
+            "META_OR_CHAT_META",
+            n -> META.matches(n) || CHAT_META.matches(n),
+            Function.identity()
+    );
 
     /**
      * Gets a name for the node type.
      *
      * @return a name
      */
-    String name();
+    @NonNull String name();
 
     /**
      * Returns if the passed node matches the type
@@ -108,7 +156,7 @@ public interface NodeType<T extends Node> {
      * @param node the node to test
      * @return true if the node has the same type
      */
-    boolean matches(Node node);
+    boolean matches(@NonNull Node node);
 
     /**
      * Casts the given {@link Node} to the type defined by the {@link NodeType}.
@@ -120,7 +168,7 @@ public interface NodeType<T extends Node> {
      * @return the casted node
      * @throws IllegalArgumentException if the node to cast does not match the type
      */
-    T cast(Node node);
+    @NonNull T cast(@NonNull Node node);
 
     /**
      * Attempts to cast the given {@link Node} to the type defined by the
@@ -132,7 +180,7 @@ public interface NodeType<T extends Node> {
      * @param node the node to cast
      * @return an optional, possibly containing a casted node
      */
-    default Optional<T> tryCast(Node node) {
+    default @NonNull Optional<T> tryCast(@NonNull Node node) {
         Objects.requireNonNull(node, "node");
         if (!matches(node)) {
             return Optional.empty();
@@ -147,7 +195,7 @@ public interface NodeType<T extends Node> {
      *
      * @return a predicate for the {@link #matches(Node)} method.
      */
-    default Predicate<Node> predicate() {
+    default @NonNull Predicate<Node> predicate() {
         return this::matches;
     }
 
@@ -159,7 +207,7 @@ public interface NodeType<T extends Node> {
      * @param and a predicate to AND with the result of the type match check
      * @return a matching predicate, ANDed with the given predicate parameter
      */
-    default Predicate<Node> predicate(Predicate<? super T> and) {
+    default @NonNull Predicate<Node> predicate(@NonNull Predicate<? super T> and) {
         return node -> matches(node) && and.test(cast(node));
     }
 

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

@@ -25,6 +25,9 @@
 
 package net.luckperms.api.node;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.NotNull;
+
 import java.util.Objects;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -41,18 +44,18 @@ final class SimpleNodeType<T extends Node> implements NodeType<T> {
     }
 
     @Override
-    public String name() {
+    public @NotNull String name() {
         return this.name;
     }
 
     @Override
-    public boolean matches(Node node) {
+    public boolean matches(@NonNull Node node) {
         Objects.requireNonNull(node, "node");
         return this.matches.test(node);
     }
 
     @Override
-    public T cast(Node node) {
+    public @NotNull T cast(@NonNull Node node) {
         if (!matches(node)) {
             throw new IllegalArgumentException("Node " + node.getClass() + " does not match " + this.name);
         }

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

@@ -32,15 +32,19 @@ import net.luckperms.api.node.NodeType;
 import net.luckperms.api.node.types.MetaNode;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.util.function.Predicate;
 
 /**
  * A predicate which matches certain {@link Node}s.
  *
+ * <p>API users should not implement this interface directly.</p>
+ *
  * @param <T> the node type matched
  * @since 5.1
  */
+@NonExtendable
 public interface NodeMatcher<T extends Node> extends Predicate<Node> {
 
     /**
@@ -130,7 +134,7 @@ public interface NodeMatcher<T extends Node> extends Predicate<Node> {
      * @param <T> the node type
      * @return the matcher
      */
-    static <T extends Node> @NonNull NodeMatcher<T> type(NodeType<? extends T> type) {
+    static <T extends Node> @NonNull NodeMatcher<T> type(@NonNull NodeType<? extends T> type) {
         return LuckPermsProvider.get().getNodeMatcherFactory().type(type);
     }
 

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

@@ -31,12 +31,14 @@ import net.luckperms.api.node.NodeType;
 import net.luckperms.api.node.types.MetaNode;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 /**
  * A factory which creates {@link NodeMatcher}s.
  *
  * @since 5.1
  */
+@Internal
 public interface NodeMatcherFactory {
 
     /**
@@ -87,7 +89,7 @@ public interface NodeMatcherFactory {
      * @param <T> the node type
      * @return the matcher
      */
-    @NonNull <T extends Node> NodeMatcher<T> equals(@NonNull T other, @NonNull NodeEqualityPredicate equalityPredicate);
+    <T extends Node> @NonNull NodeMatcher<T> equals(@NonNull T other, @NonNull NodeEqualityPredicate equalityPredicate);
 
     /**
      * Gets a {@link NodeMatcher} which matches {@link MetaNode}s with the same
@@ -115,6 +117,6 @@ public interface NodeMatcherFactory {
      * @param <T> the node type
      * @return the matcher
      */
-    <T extends Node> @NonNull NodeMatcher<T> type(NodeType<? extends T> type);
+    <T extends Node> @NonNull NodeMatcher<T> type(@NonNull NodeType<? extends T> type);
 
 }

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

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

api/src/main/java/net/luckperms/api/node/metadata/NodeMetadataKey.java

@@ -26,6 +26,7 @@
 package net.luckperms.api.node.metadata;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.util.Objects;
 
@@ -40,6 +41,7 @@ import java.util.Objects;
  *
  * @param <T> the metadata type
  */
+@NonExtendable
 public interface NodeMetadataKey<T> {
 
     /**

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

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

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

@@ -30,10 +30,12 @@ import net.luckperms.api.node.Node;
 import net.luckperms.api.node.metadata.NodeMetadataKey;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 /**
  * Node metadata indicating where a node was inherited from.
  */
+@NonExtendable
 public interface InheritanceOriginMetadata {
 
     /**
@@ -54,4 +56,17 @@ public interface InheritanceOriginMetadata {
      */
     PermissionHolder.@NonNull Identifier getOrigin();
 
+    /**
+     * Gets whether the associated node was inherited from another holder.
+     *
+     * <p>In other terms, it returns whether the origin is not equal to the given holder.</p>
+     *
+     * @param holder the holder defining the node
+     * @return if true the node was inherited, false if it was defined by the same holder
+     * @since 5.3
+     */
+    default boolean wasInherited(PermissionHolder.@NonNull Identifier holder) {
+        return !holder.equals(getOrigin());
+    }
+
 }

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

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

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

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

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

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

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

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

api/src/main/java/net/luckperms/api/platform/Platform.java

@@ -26,6 +26,7 @@
 package net.luckperms.api.platform;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.time.Instant;
 import java.util.Collection;
@@ -49,14 +50,14 @@ public interface Platform {
      *
      * @return the unique connections
      */
-    @NonNull Set<UUID> getUniqueConnections();
+    @NonNull @Unmodifiable Set<UUID> getUniqueConnections();
 
     /**
      * Gets a {@link Collection} of all known permission strings.
      *
      * @return a collection of the known permissions
      */
-    @NonNull Collection<String> getKnownPermissions();
+    @NonNull @Unmodifiable Collection<String> getKnownPermissions();
 
     /**
      * Gets the time when the plugin first started.
@@ -73,7 +74,8 @@ public interface Platform {
         BUNGEECORD("BungeeCord"),
         SPONGE("Sponge"),
         NUKKIT("Nukkit"),
-        VELOCITY("Velocity");
+        VELOCITY("Velocity"),
+        FABRIC("Fabric");
 
         private final String friendlyName;
 

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

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

api/src/main/java/net/luckperms/api/query/OptionKey.java

@@ -28,6 +28,7 @@ package net.luckperms.api.query;
 import net.luckperms.api.node.metadata.NodeMetadataKey;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.util.Objects;
 
@@ -41,6 +42,7 @@ import java.util.Objects;
  *
  * @param <T> the option type
  */
+@NonExtendable
 public interface OptionKey<T> {
 
     /**

api/src/main/java/net/luckperms/api/query/QueryOptions.java

@@ -32,6 +32,7 @@ import net.luckperms.api.context.ImmutableContextSet;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
 
 import java.util.Map;
 import java.util.Optional;
@@ -40,6 +41,7 @@ import java.util.Set;
 /**
  * Represents the parameters for a lookup query.
  */
+@NonExtendable
 public interface QueryOptions {
 
     /**
@@ -201,6 +203,7 @@ public interface QueryOptions {
     /**
      * Builder for {@link QueryOptions}.
      */
+    @NonExtendable
     interface Builder {
 
         /**

api/src/main/java/net/luckperms/api/query/QueryOptionsRegistry.java

@@ -26,12 +26,14 @@
 package net.luckperms.api.query;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 /**
  * A registry providing useful {@link QueryOptions} instances.
  *
  * @since 5.1
  */
+@Internal
 public interface QueryOptionsRegistry {
 
     /**

api/src/main/java/net/luckperms/api/query/dataorder/DataQueryOrder.java

@@ -93,7 +93,7 @@ public enum DataQueryOrder implements Comparator<DataType> {
      * @param comparator the comparator
      * @return the ordered data types
      */
-    public static List<DataType> order(@NonNull Comparator<? super DataType> comparator) {
+    public static @NonNull List<DataType> order(@NonNull Comparator<? super DataType> comparator) {
         int compare = comparator.compare(DataType.TRANSIENT, DataType.NORMAL);
         if (compare > 0) {
             // transient first

api/src/main/java/net/luckperms/api/query/dataorder/DataQueryOrderFunction.java

@@ -32,6 +32,7 @@ import net.luckperms.api.query.OptionKey;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Comparator;
+import java.util.Objects;
 
 /**
  * A function that generates a {@link DataQueryOrder} comparator for
@@ -52,7 +53,8 @@ public interface DataQueryOrderFunction {
      * @return the data query order function
      * @since 5.2
      */
-    static DataQueryOrderFunction always(Comparator<DataType> comparator) {
+    static @NonNull DataQueryOrderFunction always(@NonNull Comparator<DataType> comparator) {
+        Objects.requireNonNull(comparator, "comparator");
         return id -> comparator;
     }
 

api/src/main/java/net/luckperms/api/query/dataorder/DataTypeFilter.java

@@ -93,8 +93,8 @@ public enum DataTypeFilter implements Predicate<DataType> {
     };
 
     private static final List<DataType> ALL_LIST = Collections.unmodifiableList(Arrays.asList(DataType.NORMAL, DataType.TRANSIENT));
-    private static final List<DataType> NORMAL_ONLY_LIST = Collections.unmodifiableList(Collections.singletonList(DataType.NORMAL));
-    private static final List<DataType> TRANSIENT_ONLY_LIST = Collections.unmodifiableList(Collections.singletonList(DataType.TRANSIENT));
+    private static final List<DataType> NORMAL_ONLY_LIST = Collections.singletonList(DataType.NORMAL);
+    private static final List<DataType> TRANSIENT_ONLY_LIST = Collections.singletonList(DataType.TRANSIENT);
 
     /**
      * Gets a {@link List} of all {@link DataType}s, filtered by the {@code predicate}.

api/src/main/java/net/luckperms/api/query/dataorder/DataTypeFilterFunction.java

@@ -31,6 +31,7 @@ import net.luckperms.api.query.OptionKey;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+import java.util.Objects;
 import java.util.function.Predicate;
 
 /**
@@ -53,7 +54,8 @@ public interface DataTypeFilterFunction {
      * @param predicate the predicate
      * @return the data type filter function
      */
-    static DataTypeFilterFunction always(Predicate<DataType> predicate) {
+    static @NonNull DataTypeFilterFunction always(@NonNull Predicate<DataType> predicate) {
+        Objects.requireNonNull(predicate, "predicate");
         return id -> predicate;
     }
 

api/src/main/java/net/luckperms/api/query/dataorder/package-info.java

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

api/src/main/java/net/luckperms/api/query/meta/package-info.java

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

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

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