API 5.3

This means that if a user accidentally deletes data locally but still has a working web editor session, they can automatically recover the data contained in the session by importing it with the --upload flag.

Of course, this will only be able to recover the data present in the session. The sensible thing would be to create proper backups (using /lp export or otherwise) - but hey, people are dumb.

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/bug-report.md

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/suggestion.md

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

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,21 +1,24 @@
-![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/)
-[![Javadocs](https://javadoc.io/badge/me.lucko.luckperms/luckperms-api.svg)](https://javadoc.io/doc/me.lucko.luckperms/luckperms-api)
-[![Maven Central](https://img.shields.io/maven-metadata/v/https/repo1.maven.org/maven2/me/lucko/luckperms/luckperms-api/maven-metadata.xml.svg?label=maven%20central&colorB=brightgreen)](https://search.maven.org/artifact/me.lucko.luckperms/luckperms-api)
-[![Discord](https://img.shields.io/discord/241667244927483904.svg?logo=discord&label=)](https://discord.gg/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?label=discord&logo=discord)](https://discord.gg/luckperms)
 
-LuckPerms is an advanced permissions implementation aiming to be a fast, reliable and flexible alternative to existing permission plugins. The project's main goals are centered around high performance and a wide feature set, filling the gaps of functionality and building upon existing features found in other plugins.
+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.
 
-LuckPerms also includes an extensive API for developers, and support for a variety of Minecraft server software & data storage options.
+The latest downloads, wiki & other useful links can be found on the project homepage at [luckperms.net](https://luckperms.net/).
 
-Still not convinced? More information can be found on the wiki, under: [Why LuckPerms?](https://github.com/lucko/LuckPerms/wiki/Why-LuckPerms)
+It is:
 
-## Useful Links
+* **fast** - written with performance and scalability in mind.
+* **reliable** - trusted by thousands of server admins, and the largest of server networks.
+* **easy to use** - setup permissions using commands, directly in config files, or using the web editor.
+* **flexible** - supports a variety of data storage options, and works on lots of different server types.
+* **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.
 
-The latest **downloads** can be found on the [project's homepage](https://luckperms.net/).
-
-More information about the project & how to use the plugin can be found in the [wiki](https://github.com/lucko/LuckPerms/wiki).
+For more information, see the wiki article on [Why LuckPerms?](https://luckperms.net/wiki/Why-LuckPerms)
 
 ## Building
 LuckPerms uses Gradle to handle dependencies & building.
@@ -44,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.0'
+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')
     }
@@ -56,7 +60,7 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass
                 pom {
                     project {
                         name 'LuckPerms API'
-                        description 'An advanced permissions plugin for Bukkit/Spigot, BungeeCord, Sponge, Nukkit and Velocity.'
+                        description 'A permissions plugin for Minecraft servers.'
                         url 'https://luckperms.net'
 
                         licenses {
@@ -68,9 +72,10 @@ if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePass
 
                         developers {
                             developer {
+                                id 'lucko'
                                 name 'Luck'
+                                url 'https://lucko.me'
                                 email 'git@lucko.me'
-                                url 'https://github.com/lucko'
                             }
                         }
 

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

@@ -39,12 +39,16 @@ import net.luckperms.api.model.group.GroupManager;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.model.user.UserManager;
 import net.luckperms.api.node.NodeBuilderRegistry;
+import net.luckperms.api.node.matcher.NodeMatcherFactory;
 import net.luckperms.api.platform.Platform;
+import net.luckperms.api.platform.PlayerAdapter;
 import net.luckperms.api.platform.PluginMetadata;
+import net.luckperms.api.query.QueryOptionsRegistry;
 import net.luckperms.api.track.Track;
 import net.luckperms.api.track.TrackManager;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
@@ -114,6 +118,33 @@ public interface LuckPerms {
      */
     @NonNull TrackManager getTrackManager();
 
+    /**
+     * Gets the {@link PlayerAdapter} instance, a utility class for adapting platform Player
+     * instances to {@link User}s.
+     *
+     * <p>The {@code playerClass} parameter must be equal to the class or interface used by the
+     * server platform to represent players.</p>
+     *
+     * <p>Specifically:</p>
+     *
+     * <p></p>
+     * <ul>
+     * <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>
+     *
+     * @param playerClass the class used by the platform to represent players
+     * @param <T> the player class type
+     * @return the player adapter
+     * @throws IllegalArgumentException if the player class is not correct
+     * @since 5.1
+     */
+    <T> @NonNull PlayerAdapter<T> getPlayerAdapter(@NonNull Class<T> playerClass);
+
     /**
      * Gets the {@link Platform}, which represents the server platform the
      * plugin is running on.
@@ -165,13 +196,6 @@ public interface LuckPerms {
      */
     @NonNull ContextManager getContextManager();
 
-    /**
-     * Gets the {@link NodeBuilderRegistry}.
-     *
-     * @return the node builder registry
-     */
-    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
-
     /**
      * Gets the {@link MetaStackFactory}.
      *
@@ -206,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/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

@@ -23,15 +23,7 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.common.dependencies.classloader;
-
-import java.nio.file.Path;
-
 /**
- * Represents the plugins classloader
+ * {@link net.luckperms.api.actionlog.ActionLog} related functionality.
  */
-public interface PluginClassLoader {
-
-    void loadJar(Path file);
-
-}
+package net.luckperms.api.actionlog;

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

@@ -25,7 +25,10 @@
 
 package net.luckperms.api.cacheddata;
 
+import net.luckperms.api.context.ContextManager;
 import net.luckperms.api.model.PermissionHolder;
+import net.luckperms.api.model.group.Group;
+import net.luckperms.api.model.user.User;
 import net.luckperms.api.query.QueryOptions;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
@@ -56,23 +59,58 @@ public interface CachedDataManager {
     @NonNull Container<CachedMetaData> metaData();
 
     /**
-     * Gets PermissionData from the cache, given a specified context.
+     * Gets PermissionData from the cache, using the given query options.
      *
      * @param queryOptions the query options
      * @return a permission data instance
-     * @throws NullPointerException if contexts is null
      */
     @NonNull CachedPermissionData getPermissionData(@NonNull QueryOptions queryOptions);
 
     /**
-     * Gets MetaData from the cache, given a specified context.
+     * Gets MetaData from the cache, using the given query options.
      *
      * @param queryOptions the query options
      * @return a meta data instance
-     * @throws NullPointerException if contexts is null
      */
     @NonNull CachedMetaData getMetaData(@NonNull QueryOptions queryOptions);
 
+    /**
+     * Gets PermissionData from the cache, using the most appropriate query options
+     * available at the time.
+     *
+     * <p>For {@link User}s, the most appropriate query options will be their
+     * {@link ContextManager#getQueryOptions(User) current active query options} if the
+     * corresponding player is online, and otherwise, will fallback to
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}
+     * if they are offline.</p>
+     *
+     * <p>For {@link Group}s, the most appropriate query options will always be
+     * {@link ContextManager#getStaticQueryOptions()} the current static query options.</p>
+     *
+     * @return a permission data instance
+     * @since 5.1
+     */
+    @NonNull CachedPermissionData getPermissionData();
+
+    /**
+     * Gets MetaData from the cache, using the most appropriate query options
+     * available at the time.
+     *
+     * <p>For {@link User}s, the most appropriate query options will be their
+     * {@link ContextManager#getQueryOptions(User) current active query options} if the
+     * corresponding player is online, and otherwise, will fallback to
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}
+     * if they are offline.</p>
+     *
+     * <p>For {@link Group}s, the most appropriate query options will always be
+     * {@link ContextManager#getStaticQueryOptions()} the current static query options.</p>
+     *
+     * @return a meta data instance
+     * @since 5.1
+     * @see PermissionHolder#getQueryOptions()
+     */
+    @NonNull CachedMetaData getMetaData();
+
     /**
      * Invalidates all cached {@link CachedPermissionData} and {@link CachedMetaData}
      * instances.

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,44 +48,84 @@ public interface CachedMetaData extends CachedData {
      * @param key the key
      * @return the value
      */
-    @Nullable String getMetaValue(String key);
+    @Nullable String getMetaValue(@NonNull String key);
 
     /**
-     * Gets the user's highest priority prefix, or null if the user has no prefixes
+     * Gets a value for the given meta key, and runs it through the given {@code transformer}.
+     *
+     * <p>If no such meta value exists, an {@link Optional#empty() empty optional} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in an {@link Optional#empty() empty optional} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     getMetaValue("my-int-val", Integer::parseInt).orElse(0);
+     * </pre></blockquote>
+     *
+     * @param key the key
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the meta value
+     * @since 5.3
+     */
+    default <T> @NonNull Optional<T> getMetaValue(@NonNull String key, @NonNull Function<String, ? extends T> valueTransformer) {
+        return Optional.ofNullable(getMetaValue(key)).map(value -> {
+            try {
+                return valueTransformer.apply(value);
+            } catch (IllegalArgumentException e) {
+                return null;
+            }
+        });
+    }
+
+    /**
+     * Gets the holder's highest priority prefix, or null if the holder has no prefixes
      *
      * @return a prefix string, or null
      */
     @Nullable String getPrefix();
 
     /**
-     * Gets the user's highest priority suffix, or null if the user has no suffixes
+     * Gets the holder's highest priority suffix, or null if the holder has no suffixes
      *
      * @return a suffix string, or null
      */
     @Nullable String getSuffix();
 
     /**
-     * Gets an immutable copy of the meta this user has.
+     * Gets an immutable copy of the meta this holder has.
      *
      * @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 user has, whereby the first value is the highest priority
-     * prefix.
+     * Gets an immutable sorted map of all of the prefixes the holder has, whereby the first
+     * value is the highest priority prefix.
      *
      * @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 user has, whereby the first value is the highest priority
-     * suffix.
+     * Gets an immutable sorted map of all of the suffixes the holder has, whereby the first
+     * value is the highest priority suffix.
      *
      * @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.
+     *
+     * <p>Will return {@code null} for Group holder types.</p>
+     *
+     * @return the name of the primary group
+     * @since 5.1
+     */
+    @Nullable String getPrimaryGroup();
 
     /**
      * Gets the definition used for the prefix stack

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/Context.java

@@ -26,12 +26,64 @@
 package net.luckperms.api.context;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * Represents an individual context pair.
+ *
+ * <p>Context keys and values may not be null or empty. A key/value will be
+ * deemed empty if it's length is zero, or if it consists of only space
+ * characters.</p>
+ *
+ * @see ContextSet
  */
 public interface Context {
 
+    /**
+     * Tests whether {@code key} is valid.
+     *
+     * <p>Context keys and values may not be null or empty. A key/value will be
+     * deemed empty if it's length is zero, or if it consists of only space
+     * characters.</p>
+     *
+     * <p>An exception is thrown when an invalid key is added to a {@link ContextSet}.</p>
+     *
+     * @param key the key to test
+     * @return true if valid, false otherwise.
+     * @since 5.1
+     */
+    static boolean isValidKey(@Nullable String key) {
+        if (key == null || key.isEmpty()) {
+            return false;
+        }
+
+        // look for a non-whitespace character
+        for (int i = 0, n = key.length(); i < n; i++) {
+            if (key.charAt(i) != ' ') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Tests whether {@code value} is valid.
+     *
+     * <p>Context keys and values may not be null or empty. A key/value will be
+     * deemed empty if it's length is zero, or if it consists of only space
+     * characters.</p>
+     *
+     * <p>An exception is thrown when an invalid value is added to a {@link ContextSet}.</p>
+     *
+     * @param value the value to test
+     * @return true if valid, false otherwise.
+     * @since 5.1
+     */
+    static boolean isValidValue(@Nullable String value) {
+        return isValidKey(value); // the same for now...
+    }
+
     /**
      * Gets the context key.
      *

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;
 
@@ -37,17 +38,18 @@ import java.util.Optional;
  * Manages {@link ContextCalculator}s, and calculates applicable contexts for a
  * given type.
  *
- * This interface accepts {@link Object} types as a parameter to avoid having to depend
+ * <p>This interface accepts {@link Object} types as a parameter to avoid having to depend
  * on specific server implementations. In all cases, the "player" or "subject" type for
- * the platform must be used.
+ * the platform must be used.</p>
  *
- * Specifically:
+ * <p>Specifically:</p>
  *
  * <p></p>
  * <ul>
  * <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>
@@ -138,19 +140,36 @@ public interface ContextManager {
      */
     void unregisterCalculator(@NonNull ContextCalculator<?> calculator);
 
+    /**
+     * Signal to the {@link ContextManager} that a {@code subject}s
+     * current contexts have changed.
+     *
+     * <p>It is not strictly necessary to make a call to this method every time a context
+     * changes.</p>
+     *
+     * @param subject the subject
+     * @since 5.2
+     */
+    void signalContextUpdate(@NonNull Object subject);
+
     /**
      * Gets the {@link ContextSetFactory}, responsible for creating
      * {@link ContextSet} instances.
      *
      * @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)} instead
      */
-    void invalidateCache(@NonNull Object subject);
+    @Deprecated
+    default void invalidateCache(@NonNull Object subject) {
+        signalContextUpdate(subject);
+    }
 
 }

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

@@ -0,0 +1,63 @@
+/*
+ * 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.context;
+
+import net.luckperms.api.query.OptionKey;
+
+/**
+ * Mode for determining whether a {@link ContextSet} satisfies another.
+ *
+ * @since 5.2
+ * @see ContextSet#isSatisfiedBy(ContextSet, ContextSatisfyMode)
+ */
+public enum ContextSatisfyMode {
+
+    /**
+     * Mode where a {@link ContextSet} A will be satisfied by another set B, if at least one of the
+     * key-value entries per key in A are also in B.
+     *
+     * <p>For example, given <code>A = {server=survival, world=overworld, world=nether}</code>,
+     * another set {@code X} will satisfy {@code A} if {@code X} contains
+     * <code>server=survival AND (world=overworld OR world=nether)</code>.</p>
+     */
+    AT_LEAST_ONE_VALUE_PER_KEY,
+
+    /**
+     * Mode where a {@link ContextSet} A will be satisfied by another set B, if all key-value
+     * entries in A are also in B.
+     *
+     * <p>For example, given <code>A = {server=survival, world=overworld, world=nether}</code>,
+     * another set {@code X} will satisfy {@code A} if {@code X} contains
+     * <code>server=survival AND world=overworld AND world=nether</code>.</p>
+     */
+    ALL_VALUES_PER_KEY;
+
+    /**
+     * The {@link OptionKey} for {@link ContextSatisfyMode}.
+     */
+    public static final OptionKey<ContextSatisfyMode> KEY = OptionKey.of("contextsatisfymode", ContextSatisfyMode.class);
+
+}

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;
@@ -40,19 +41,33 @@ import java.util.Set;
  * something will apply.</p>
  *
  * <p>A single "context" consists of a key and a value, both strings. The key
- * represents the type of context, and the value represents the setting of the
- * context key.</p>
+ * describes the type of the context, and the value represents what the key is
+ * set to.</p>
+ *
+ * <p>For example, a context with {@code key=world} and {@code value=world_nether}
+ * describes that a subject is in the "world_nether" world.</p>
+ *
+ * <p>Contexts are exposed to end users and manipulated when managing permissions.
+ * For this reason, context keys should strike a balance between being descriptive
+ * and succinct.</p>
+ *
+ * <p>Context keys and values are case-insensitive, and will be automatically
+ * converted to {@link String#toLowerCase() lowercase} when added to a
+ * context set. Keys and values cannot be null or empty (len=0 or consisting of
+ * only whitespace).</p>
+ *
+ * <p>If a context key is formed of more than one word, the parts should be
+ * separated by the '{@code -}' character. (e.g. "{@code server-type}")</p>
+ *
+ * <p>If a context key is likely to conflict with another plugin, it should be
+ * appropriately namespaced using the name of the plugin providing the context.
+ * The namespace should be at the start of the context key, and separated using
+ * the '{@code :}' character. (e.g. "{@code worldguard:region}" for WorldGuard
+ * regions)</p>
  *
  * <p>Contexts can be combined with each other to form so called
  * "context sets" - simply a collection of context pairs.</p>
  *
- * <p>Context keys and values are case-insensitive, and will be converted to
- * {@link String#toLowerCase() lowercase} by all implementations.</p>
- *
- * <p>Context keys and values may not be null or empty. A key/value will be
- * deemed empty if it's length is zero, or if it consists of only space
- * characters.</p>
- *
  * <p>Two default ContextSet implementations are provided.
  * {@link MutableContextSet} allows the addition and removal of context keys
  * after construction, and {@link ImmutableContextSet} does not.</p>
@@ -97,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
@@ -108,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
@@ -121,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.
@@ -137,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
@@ -159,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.
@@ -197,17 +212,47 @@ public interface ContextSet extends Iterable<Context> {
     }
 
     /**
-     * Returns if this {@link ContextSet} is fully "satisfied" by another set.
+     * Returns if the {@link ContextSet} contains any of the given context pairings.
      *
-     * <p>For a context set to "satisfy" another, it must itself contain all of
-     * the context pairings in the other set.</p>
-     *
-     * <p>Mathematically, this method returns true if this set is a <b>subset</b> of the other.</p>
-     *
-     * @param other the other set to check
-     * @return true if all entries in this set are also in the other set
+     * @param key the key to look for
+     * @param values the values to look for
+     * @return true if the set contains any of the pairs
+     * @since 5.2
      */
-    boolean isSatisfiedBy(@NonNull ContextSet other);
+    default boolean containsAny(@NonNull String key, @NonNull Iterable<String> values) {
+        Objects.requireNonNull(key, "key");
+        Objects.requireNonNull(values, "values");
+
+        for (String value : values) {
+            if (contains(key, value)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Returns if this {@link ContextSet} is "satisfied" by another set.
+     *
+     * <p>{@link ContextSatisfyMode#AT_LEAST_ONE_VALUE_PER_KEY} is the mode used by this method.</p>
+     *
+     * @param other the other set
+     * @return true if this context set is satisfied by the other
+     */
+    default boolean isSatisfiedBy(@NonNull ContextSet other) {
+        return isSatisfiedBy(other, ContextSatisfyMode.AT_LEAST_ONE_VALUE_PER_KEY);
+    }
+
+    /**
+     * Returns if this {@link ContextSet} is "satisfied" by another set, according to the given
+     * {@code mode}.
+     *
+     * @param other the other set
+     * @param mode the mode to use
+     * @return true if this context set is satisfied by the other
+     * @since 5.2
+     */
+    boolean isSatisfiedBy(@NonNull ContextSet other, @NonNull ContextSatisfyMode mode);
 
     /**
      * Returns if the {@link ContextSet} is empty.

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/ContextUpdateEvent.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.context;
+
+import net.luckperms.api.context.ContextManager;
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Optional;
+
+/**
+ * Called when a subject's current/active contexts are updated.
+ *
+ * <p>There are no guarantees that this event will be called for every update. It is merely to be
+ * used as a "hint" for plugins which depend on the current active contexts for a player.</p>
+ *
+ * <p>It will always be fired following a call to
+ * {@link ContextManager#signalContextUpdate(Object)}.</p>
+ *
+ * <p>The {@link #getSubject() subject} is always an instance of the platform's subject type. See
+ * {@link ContextManager} for details.</p>
+ *
+ * <p>Unlike most other LuckPerms events, this event is not fired asynchronously. Care should be
+ * taken to ensure listeners are lightweight. Additionally, listeners should ensure they do not
+ * cause further updates to player context, thus possibly causing a stack overflow.</p>
+ *
+ * @since 5.2
+ */
+public interface ContextUpdateEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the subject whose contexts were updated.
+     *
+     * @return the subject
+     */
+    @Param(0)
+    @NonNull Object getSubject();
+
+    /**
+     * Gets the subject whose contexts were updated, casted to a given type.
+     *
+     * @param subjectClass the type to cast to
+     * @param <T> the subject type
+     * @return the casted subject
+     */
+    default <T> @NonNull Optional<T> getSubject(@NonNull Class<T> subjectClass) {
+        Object subject = getSubject();
+        return subjectClass.isInstance(subject) ? Optional.of(subjectClass.cast(subject)) : Optional.empty();
+    }
+
+}

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/GroupCreateEvent.java

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.group;
 
 import net.luckperms.api.event.LuckPermsEvent;
-import net.luckperms.api.event.util.Param;
 import net.luckperms.api.event.cause.CreationCause;
+import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.group.Group;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.group;
 
 import net.luckperms.api.event.LuckPermsEvent;
-import net.luckperms.api.event.util.Param;
 import net.luckperms.api.event.cause.DeletionCause;
+import net.luckperms.api.event.util.Param;
 import net.luckperms.api.node.Node;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

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

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

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.log;
 
 import net.luckperms.api.actionlog.Action;
-import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.log;
 
 import net.luckperms.api.actionlog.Action;
-import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.log;
 
 import net.luckperms.api.actionlog.Action;
-import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 import net.luckperms.api.platform.PlatformEntity;
 

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.log;
 
 import net.luckperms.api.actionlog.Action;
-import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

api/src/main/java/net/luckperms/api/event/log/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

@@ -23,48 +23,54 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.common.metastacking;
+package net.luckperms.api.event.player.lookup;
 
-import net.luckperms.api.metastacking.MetaStackDefinition;
-import net.luckperms.api.node.ChatMetaType;
-import net.luckperms.api.node.types.ChatMetaNode;
+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;
 
 /**
- * A live stack of {@link MetaStackEntry} instances, formed from a
- * {@link MetaStackDefinition}.
+ * Called when the validity of a username is being tested.
  *
- * This class is used to construct a formatted string, by accumulating
- * nodes to each element.
+ * @since 5.3
  */
-public interface MetaStack {
+public interface UsernameValidityCheckEvent extends LuckPermsEvent {
 
     /**
-     * Gets the definition this stack is based upon
+     * Gets the username being tested.
      *
-     * @return the definition of the stack
+     * @return the username
      */
-    MetaStackDefinition getDefinition();
+    @Param(0)
+    @NonNull String getUsername();
 
     /**
-     * Gets the target of this stack
+     * Gets the current validity state for the username.
      *
-     * @return the stack target
+     * @return the validity state
      */
-    ChatMetaType getTargetType();
+    @Param(1)
+    @NonNull AtomicBoolean validityState();
 
     /**
-     * Returns a formatted string, as defined by the {@link MetaStackDefinition},
-     * using the accumulated elements in the stack.
+     * Gets if the username is currently considered to be valid.
      *
-     * @return the string output
+     * @return if the username is valid
      */
-    String toFormattedString();
+    default boolean isValid() {
+        return validityState().get();
+    }
 
     /**
-     * Tries to accumulate the given node to all elements in the stack.
+     * Sets if the username should be considered valid or not.
      *
-     * @param node the node to accumulate
+     * @param valid whether the username is valid
      */
-    void accumulateToAll(ChatMetaNode<?, ?> node);
+    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/PreNetworkSyncEvent.java

@@ -25,8 +25,8 @@
 
 package net.luckperms.api.event.sync;
 
-import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

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

@@ -25,8 +25,8 @@
 
 package net.luckperms.api.event.sync;
 
-import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 
 /**
  * Called before a sync task runs

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

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

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.track;
 
 import net.luckperms.api.event.LuckPermsEvent;
-import net.luckperms.api.event.util.Param;
 import net.luckperms.api.event.cause.CreationCause;
+import net.luckperms.api.event.util.Param;
 import net.luckperms.api.track.Track;
 
 import org.checkerframework.checker.nullness.qual.NonNull;

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

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.track;
 
 import net.luckperms.api.event.LuckPermsEvent;
-import net.luckperms.api.event.util.Param;
 import net.luckperms.api.event.cause.DeletionCause;
+import net.luckperms.api.event.util.Param;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 

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

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

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

api/src/main/java/net/luckperms/api/event/type/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/UserTrackEvent.java

@@ -26,8 +26,8 @@
 package net.luckperms.api.event.user.track;
 
 import net.luckperms.api.event.LuckPermsEvent;
-import net.luckperms.api.event.util.Param;
 import net.luckperms.api.event.type.Sourced;
+import net.luckperms.api.event.util.Param;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.track.Track;
 

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

@@ -23,10 +23,7 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.common.util;
-
-public interface ThrowingRunnable {
-
-    void run() throws Exception;
-
-}
+/**
+ * {@link net.luckperms.api.extension.Extension}s functionality.
+ */
+package net.luckperms.api.extension;

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

@@ -26,18 +26,25 @@
 package net.luckperms.api.model;
 
 import net.luckperms.api.cacheddata.CachedDataManager;
+import net.luckperms.api.context.ContextManager;
 import net.luckperms.api.model.data.DataType;
 import net.luckperms.api.model.data.NodeMap;
 import net.luckperms.api.model.group.Group;
 import net.luckperms.api.model.user.User;
 import net.luckperms.api.node.Node;
+import net.luckperms.api.node.NodeType;
+import net.luckperms.api.query.Flag;
 import net.luckperms.api.query.QueryOptions;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.Unmodifiable;
 
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.List;
 import java.util.SortedSet;
 import java.util.UUID;
+import java.util.stream.Collectors;
 
 /**
  * Generic superinterface for an object which holds permissions.
@@ -108,6 +115,24 @@ public interface PermissionHolder {
      */
     @NonNull String getFriendlyName();
 
+    /**
+     * Gets the most appropriate query options available at the time for the
+     * {@link PermissionHolder}.
+     *
+     * <p>For {@link User}s, the most appropriate query options will be their
+     * {@link ContextManager#getQueryOptions(User) current active query options} if the
+     * corresponding player is online, and otherwise, will fallback to
+     * {@link ContextManager#getStaticQueryOptions() the current static query options}
+     * if they are offline.</p>
+     *
+     * <p>For {@link Group}s, the most appropriate query options will always be
+     * {@link ContextManager#getStaticQueryOptions()} the current static query options.</p>
+     *
+     * @return query options
+     * @since 5.1
+     */
+    @NonNull QueryOptions getQueryOptions();
+
     /**
      * Gets the holders {@link CachedDataManager} cache.
      *
@@ -121,7 +146,7 @@ public interface PermissionHolder {
      * @param dataType the data type
      * @return the data
      */
-    NodeMap getData(@NonNull DataType dataType);
+    @NonNull NodeMap getData(@NonNull DataType dataType);
 
     /**
      * Gets the holders {@link DataType#NORMAL} data.
@@ -149,35 +174,60 @@ public interface PermissionHolder {
     @NonNull NodeMap transientData();
 
     /**
-     * Gets a flattened/squashed view of the holders permissions.
+     * Gets a flattened view of the holders own {@link Node}s.
      *
-     * <p>This list is constructed using the values
-     * of both the transient and enduring backing multimaps.</p>
+     * <p>This list is constructed using the values of both the {@link #data() normal}
+     * and {@link #transientData() transient} backing node maps.</p>
      *
-     * <p>This means that it <b>may contain</b> duplicate entries.</p>
-     *
-     * <p>Use {@link #getDistinctNodes()} for a view without duplicates.</p>
+     * <p>It <b>may contain</b> duplicate entries if the same node is added to both the normal
+     * and transient node maps. You can use {@link #getDistinctNodes()} for a view without
+     * duplicates.</p>
      *
      * <p>This method <b>does not</b> resolve inheritance rules.</p>
      *
-     * @return a list of the holders own nodes.
+     * @return a collection of the holders own nodes.
      */
-    @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<>();
+        nodes.addAll(data().toCollection());
+        nodes.addAll(transientData().toCollection());
+        return nodes;
+    }
 
     /**
-     * Gets a sorted set of all held nodes.
+     * Gets a flattened view of the holders own {@link Node}s of the given {@code type}.
+     *
+     * @param type the type of node to filter by
+     * @param <T> the node type
+     * @return a filtered collection of the holders own nodes
+     * @see #getNodes()
+     * @since 5.1
+     */
+    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()
+                .filter(type::matches)
+                .map(type::cast)
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * Gets a flattened and sorted view of the holders own distinct {@link Node}s.
      *
      * <p>Effectively a sorted version of {@link #getNodes()}, without duplicates. Use the
      * aforementioned method if you don't require either of these attributes.</p>
      *
      * <p>This method <b>does not</b> resolve inheritance rules.</p>
      *
-     * @return an immutable set of permissions in priority order
+     * @return a sorted set of the holders own distinct nodes
      */
-    @NonNull SortedSet<Node> getDistinctNodes();
+    @NonNull @Unmodifiable SortedSet<Node> getDistinctNodes();
 
     /**
-     * Recursively resolves this holders permissions.
+     * Gets a resolved view of the holders own and inherited {@link Node}s.
      *
      * <p>The returned list will contain every inherited
      * node the holder has, in the order that they were inherited in.</p>
@@ -189,21 +239,65 @@ public interface PermissionHolder {
      * with the entries from the end of the inheritance tree appearing last.</p>
      *
      * @param queryOptions the query options
-     * @return a list of nodes
+     * @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 mutable sorted set of the nodes that this object has and inherits, filtered by context
+     * Gets a resolved view of the holders own and inherited {@link Node}s of a given {@code type}.
      *
-     * <p>Nodes are sorted into priority order. The order of inheritance is only important during
-     * the process of flattening inherited entries.</p>
+     * @param type the type of node to filter by
+     * @param queryOptions the query options
+     * @param <T> the node type
+     * @return a filtered list of the holders inherited nodes
+     * @see #resolveInheritedNodes(QueryOptions)
+     * @since 5.1
+     */
+    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()
+                .filter(type::matches)
+                .map(type::cast)
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * Gets a resolved and sorted view of the holders own and inherited distinct {@link Node}s.
+     *
+     * <p>Effectively a sorted version of {@link #resolveInheritedNodes(QueryOptions)},
+     * without duplicates. Use the aforementioned method if you don't require either of these
+     * attributes.</p>
+     *
+     * <p>Inheritance is performed according to the platforms rules, and the order will vary
+     * depending on the accumulation order. By default, the holders own nodes are first in the list,
+     * with the entries from the end of the inheritance tree appearing last.</p>
      *
      * @param queryOptions the query options
-     * @return an immutable sorted set of permissions
-     * @throws NullPointerException if the context is null
+     * @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.
+     *
+     * <p>If {@link Flag#RESOLVE_INHERITANCE} is set, this will include holders inherited from both
+     * directly and indirectly (through directly inherited groups). It will effectively resolve the
+     * whole "inheritance tree".</p>
+     *
+     * <p>If {@link Flag#RESOLVE_INHERITANCE} is not set, then the traversal will only go one
+     * level up the inheritance tree, and return only directly inherited groups.</p>
+     *
+     * <p>The collection will be ordered according to the platforms inheritance rules. The groups
+     * which are inherited from first will appear earlier in the list.</p>
+     *
+     * <p>The list will not contain the holder.</p>
+     *
+     * @param queryOptions the query options
+     * @return a collection of the groups the holder inherits from
+     * @since 5.1
+     */
+    @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

@@ -26,11 +26,16 @@
 package net.luckperms.api.model.group;
 
 import net.luckperms.api.node.HeldNode;
+import net.luckperms.api.node.Node;
+import net.luckperms.api.node.matcher.NodeMatcher;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
+import java.util.Collection;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
@@ -98,6 +103,27 @@ public interface GroupManager {
      */
     @NonNull CompletableFuture<Void> deleteGroup(@NonNull Group group);
 
+    /**
+     * Loads (or creates) a group from the plugin's storage provider, applies the given
+     * {@code action}, then saves the group's data back to storage.
+     *
+     * <p>This method effectively calls {@link #createAndLoadGroup(String)}, followed by the
+     * {@code action}, then {@link #saveGroup(Group)}, and returns an encapsulation of the whole
+     * process as a {@link CompletableFuture}. </p>
+     *
+     * @param name the name of the group
+     * @param action the action to apply to the group
+     * @return a future to encapsulate the operation
+     * @since 5.1
+     */
+    default @NonNull CompletableFuture<Void> modifyGroup(@NonNull String name, @NonNull Consumer<? super Group> action) {
+        /* This default method is overridden in the implementation, and is just here
+           to demonstrate what this method does in the API sources. */
+        return createAndLoadGroup(name)
+                .thenApplyAsync(group -> { action.accept(group); return group; })
+                .thenCompose(this::saveGroup);
+    }
+
     /**
      * Loads all groups into memory.
      *
@@ -105,14 +131,26 @@ public interface GroupManager {
      */
     @NonNull CompletableFuture<Void> loadAllGroups();
 
+    /**
+     * Searches the {@link Group#data() normal node maps} of all known {@link Group}s for {@link Node}
+     * entries matching the given {@link NodeMatcher matcher}.
+     *
+     * @param matcher the matcher
+     * @return the entries which matched
+     * @since 5.1
+     */
+    <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.
      *
      * @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)} instead
      */
-    @NonNull CompletableFuture<List<HeldNode<String>>> getWithPermission(@NonNull String permission);
+    @Deprecated
+    @NonNull CompletableFuture<@Unmodifiable List<HeldNode<String>>> getWithPermission(@NonNull String permission);
 
     /**
      * Gets a loaded group.
@@ -128,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

@@ -27,11 +27,16 @@ package net.luckperms.api.model.user;
 
 import net.luckperms.api.model.PlayerSaveResult;
 import net.luckperms.api.node.HeldNode;
+import net.luckperms.api.node.Node;
+import net.luckperms.api.node.matcher.NodeMatcher;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
+import java.util.Collection;
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
@@ -59,7 +64,7 @@ public interface UserManager {
     /**
      * Loads a user from the plugin's storage provider into memory.
      *
-     * @param uniqueId     the uuid of the user
+     * @param uniqueId the uuid of the user
      * @param username the username, if known
      * @return the resultant user
      * @throws NullPointerException if the uuid is null
@@ -111,6 +116,27 @@ public interface UserManager {
      */
     @NonNull CompletableFuture<Void> saveUser(@NonNull User user);
 
+    /**
+     * Loads a user from the plugin's storage provider, applies the given {@code action},
+     * then saves the user's data back to storage.
+     *
+     * <p>This method effectively calls {@link #loadUser(UUID)}, followed by the {@code action},
+     * then {@link #saveUser(User)}, and returns an encapsulation of the whole process as a
+     * {@link CompletableFuture}. </p>
+     *
+     * @param uniqueId the uuid of the user
+     * @param action the action to apply to the user
+     * @return a future to encapsulate the operation
+     * @since 5.1
+     */
+    default @NonNull CompletableFuture<Void> modifyUser(@NonNull UUID uniqueId, @NonNull Consumer<? super User> action) {
+        /* This default method is overridden in the implementation, and is just here
+           to demonstrate what this method does in the API sources. */
+        return loadUser(uniqueId)
+                .thenApplyAsync(user -> { action.accept(user); return user; })
+                .thenCompose(this::saveUser);
+    }
+
     /**
      * Saves data about a player to the uuid caching system.
      *
@@ -122,6 +148,17 @@ public interface UserManager {
      */
     @NonNull CompletableFuture<PlayerSaveResult> savePlayerData(@NonNull UUID uniqueId, @NonNull String username);
 
+    /**
+     * Deletes any data about a given player from the uuid caching system.
+     *
+     * <p>Note that this method does not affect any saved user/permissions data.</p>
+     *
+     * @param uniqueId the users mojang unique id
+     * @return a future encapsulating the result of the operation
+     * @since 5.2
+     */
+    @NonNull CompletableFuture<Void> deletePlayerData(@NonNull UUID uniqueId);
+
     /**
      * Gets a set all "unique" user UUIDs.
      *
@@ -129,7 +166,17 @@ 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}
+     * entries matching the given {@link NodeMatcher matcher}.
+     *
+     * @param matcher the matcher
+     * @return the entries which matched
+     * @since 5.1
+     */
+    <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.
@@ -137,8 +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)} instead
      */
-    @NonNull CompletableFuture<List<HeldNode<UUID>>> getWithPermission(@NonNull String permission);
+    @Deprecated
+    @NonNull CompletableFuture<@Unmodifiable List<HeldNode<UUID>>> getWithPermission(@NonNull String permission);
 
     /**
      * Gets a loaded user.
@@ -163,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/DummyNodeEqualityPredicate.java

@@ -0,0 +1,54 @@
+/*
+ * 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.node;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Dummy implementation of {@link NodeEqualityPredicate}, used for the given constant
+ * implementations.
+ *
+ * <p>The implementation rule of not calling {@link Node#equals(Node, NodeEqualityPredicate)} is
+ * intentionally disregarded by this dummy implementation. The equals method has a special case for
+ * the dummy instances, preventing a stack overflow.</p>
+ */
+final class DummyNodeEqualityPredicate implements NodeEqualityPredicate {
+    private final String name;
+
+    DummyNodeEqualityPredicate(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public boolean areEqual(@NonNull Node o1, @NonNull Node o2) {
+        return o1.equals(o2, this);
+    }
+
+    @Override
+    public String toString() {
+        return "NodeEqualityPredicate#" + this.name;
+    }
+}

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

@@ -33,7 +33,9 @@ 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,7 +39,10 @@ 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;
 import java.util.Collection;
 import java.util.Optional;
@@ -63,15 +66,24 @@ import java.util.stream.Stream;
  * node, as well as methods to query and extract additional state and properties
  * from these settings.</p>
  *
- * <p>Nodes have the following attributes:</p>
+ * <p>Nodes have the following 4 key attributes:</p>
  * <p></p>
  * <ul>
  * <li>{@link #getKey() key} - the key of the node</li>
  * <li>{@link #getValue() value} - the value of the node (false for negated)</li>
- * <li>{@link #getContexts() context} - the contexts required for this node to apply </li>
+ * <li>{@link #getContexts() context} - the contexts required for this node to apply</li>
  * <li>{@link #getExpiry() expiry} - the time when this node should expire</li>
  * </ul>
  *
+ * <p>These are the key attributes which are considered when evaluating node
+ * {@link #equals(Object) equality}.</p>
+ *
+ * <p>Nodes can also optionally have {@link #metadata(NodeMetadataKey) metadata} attached to them,
+ * added during construction using {@link NodeBuilder#withMetadata(NodeMetadataKey, Object)}, and
+ * queried using {@link #metadata(NodeMetadataKey)} and {@link #getMetadata(NodeMetadataKey)}.
+ * Such metadata is never considered when evaluating {@link #equals(Object)} or
+ * {@link #equals(Node, NodeEqualityPredicate)} (any form of equality check).</p>
+ *
  * <p>There are a number of node types, all of which extend from this class:</p>
  * <p></p>
  * <ul>
@@ -87,6 +99,7 @@ import java.util.stream.Stream;
  *
  * <p>The core node state must be immutable in all implementations.</p>
  */
+@NonExtendable
 public interface Node {
 
     /**
@@ -95,7 +108,7 @@ public interface Node {
      * @param key the key
      * @return the node builder
      */
-    static @NonNull NodeBuilder builder(@NonNull String key) {
+    static @NonNull NodeBuilder<?, ?> builder(@NonNull String key) {
         return LuckPermsProvider.get().getNodeBuilderRegistry().forKey(key);
     }
 
@@ -141,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.
@@ -153,8 +166,8 @@ public interface Node {
     /**
      * Gets the time when this node will expire.
      *
-     * @return the {@link Instant} when this node will expire, or null if it
-     * doesn't have an expiry time
+     * @return the {@link Instant} when this node will expire, or
+     * {@code null} if it doesn't have an expiry time
      */
     @Nullable Instant getExpiry();
 
@@ -167,6 +180,17 @@ public interface Node {
      */
     boolean hasExpired();
 
+    /**
+     * Gets the time until this node will expire.
+     *
+     * <p>Returns {@code null} if the node doesn't have an expiry time,
+     * and a {@link Duration#isNegative() negative} duration if it has already expired.</p>
+     *
+     * @return the duration until the nodes expiry
+     * @since 5.1
+     */
+    @Nullable Duration getExpiryDuration();
+
     /**
      * Gets the contexts required for this node to apply.
      *

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

@@ -30,8 +30,11 @@ 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;
+import java.time.temporal.TemporalAmount;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
@@ -41,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>> {
 
     /**
@@ -85,7 +89,20 @@ public interface NodeBuilder<N extends ScopedNode<N, B>, B extends NodeBuilder<N
     /**
      * Sets the time when the node should expire.
      *
-     * <p>The expiry timestamp is calculated relative to the current
+     * <p>The expiry time is calculated relative to the current
+     * system time.</p>
+     *
+     * @param duration how long the node should be added for
+     * @return the builder
+     * @see Node#getExpiry()
+     * @since 5.1
+     */
+    @NonNull B expiry(@Nullable TemporalAmount duration);
+
+    /**
+     * Sets the time when the node should expire.
+     *
+     * <p>The expiry time is calculated relative to the current
      * system time.</p>
      *
      * @param duration how long the node should be added for
@@ -97,8 +114,7 @@ public interface NodeBuilder<N extends ScopedNode<N, B>, B extends NodeBuilder<N
             throw new IllegalArgumentException("duration must be positive");
         }
         long seconds = Objects.requireNonNull(unit, "unit").toSeconds(duration);
-        long timeNow = System.currentTimeMillis() / 1000L;
-        return expiry(timeNow + seconds);
+        return expiry(Duration.ofSeconds(seconds));
     }
 
     /**
@@ -147,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,74 +35,103 @@ 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)} method.</p>
+     *
      * @param key the key
      * @return the node builder
+     * @see Node#builder(String)
      */
     @NonNull NodeBuilder<?, ?> forKey(String key);
 
     /**
      * Gets a {@link NodeBuilder} for {@link PermissionNode}s.
      *
+     * <p>Prefer using the {@link PermissionNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see PermissionNode#builder()
      */
     PermissionNode.@NonNull Builder forPermission();
 
     /**
      * Gets a {@link NodeBuilder} for {@link RegexPermissionNode}s.
      *
+     * <p>Prefer using the {@link RegexPermissionNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see RegexPermissionNode#builder()
      */
     RegexPermissionNode.@NonNull Builder forRegexPermission();
 
     /**
      * Gets a {@link NodeBuilder} for {@link InheritanceNode}s.
      *
+     * <p>Prefer using the {@link InheritanceNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see InheritanceNode#builder()
      */
     InheritanceNode.@NonNull Builder forInheritance();
 
     /**
      * Gets a {@link NodeBuilder} for {@link PrefixNode}s.
      *
+     * <p>Prefer using the {@link PrefixNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see PrefixNode#builder()
      */
     PrefixNode.@NonNull Builder forPrefix();
 
     /**
      * Gets a {@link NodeBuilder} for {@link SuffixNode}s.
      *
+     * <p>Prefer using the {@link SuffixNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see SuffixNode#builder()
      */
     SuffixNode.@NonNull Builder forSuffix();
 
     /**
      * Gets a {@link NodeBuilder} for {@link MetaNode}s.
      *
+     * <p>Prefer using the {@link MetaNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see MetaNode#builder()
      */
     MetaNode.@NonNull Builder forMeta();
 
     /**
      * Gets a {@link NodeBuilder} for {@link WeightNode}s.
      *
+     * <p>Prefer using the {@link WeightNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see WeightNode#builder()
      */
     WeightNode.@NonNull Builder forWeight();
 
     /**
      * Gets a {@link NodeBuilder} for {@link DisplayNameNode}s.
      *
+     * <p>Prefer using the {@link DisplayNameNode#builder()} method.</p>
+     *
      * @return the node builder
+     * @see DisplayNameNode#builder()
      */
     DisplayNameNode.@NonNull Builder forDisplayName();
 

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

@@ -30,7 +30,18 @@ import org.checkerframework.checker.nullness.qual.NonNull;
 import java.util.function.Predicate;
 
 /**
- * A rule for determining if two nodes are equal.
+ * An equality test for determining if two nodes are to be considered equal.
+ *
+ * <p>Recall that {@link Node}s have 4 key attributes: key, value, context, expiry.</p>
+ *
+ * <p>In the default {@link Node#equals(Object)} implementation (equivalent to {@link #EXACT}),
+ * all 4 of these key attributes are considered. However, there are occasions where such strict
+ * equality checking is not desired, hence the use of this class.</p>
+ *
+ * <p>{@link NodeEqualityPredicate}s can either be used inline, by directly calling the
+ * {@link #areEqual(Node, Node)} method, or can be passed as a parameter to the
+ * {@link Node#equals(Node, NodeEqualityPredicate)} method. Either approach is valid, and both will
+ * result in the same result.</p>
  *
  * <p>Generally, implementations of this interface should fulfil the same
  * requirements as the {@link Object#equals(Object)} contract.</p>
@@ -61,60 +72,88 @@ public interface NodeEqualityPredicate {
         return other -> areEqual(node, other);
     }
 
-
-    /*
-     * Some 'default' implementations of NodeEqualityPredicate are provided below.
-     *
-     * These are implemented in the common code, by a special case in the
-     * implementation of Node#equals. As noted above, this should generally be
-     * avoided.
-     */
-
     /**
      * Represents an exact match.
      *
-     * <p>All attributes of the nodes must match for them to be considered
-     * equal.</p>
-     */
-    NodeEqualityPredicate EXACT = new NodeEqualityPredicate() {
-        @Override public boolean areEqual(@NonNull Node o1, @NonNull Node o2) { return o1.equals(o2, this); }
-    };
-
-    /**
-     * All attributes must match, except for
-     * {@link Node#getValue() value}, which is ignored.
-     */
-    NodeEqualityPredicate IGNORE_VALUE = new NodeEqualityPredicate() {
-        @Override public boolean areEqual(@NonNull Node o1, @NonNull Node o2) { return o1.equals(o2, this); }
-    };
-
-    /**
-     * All attributes must match, except for the
-     * {@link Node#getExpiry() expiry time}, which is ignored.
+     * <p>Returns true if: (and)</p>
+     * <p></p>
+     * <ul>
+     * <li>{@link Node#getKey() key} = key</li>
+     * <li>{@link Node#getValue() value} = value</li>
+     * <li>{@link Node#getContexts() context} = context</li>
+     * <li>{@link Node#getExpiry() expiry} = expiry</li>
+     * </ul>
      *
-     * <p>Note that with this setting, whether a node is temporary or not is
-     * still considered.</p>
+     * <p>All 4 attributes of the nodes must match to be considered equal.</p>
+     *
+     * <p>This is the default form of equality, used by {@link Node#equals(Object)}.</p>
      */
-    NodeEqualityPredicate IGNORE_EXPIRY_TIME = new NodeEqualityPredicate() {
-        @Override public boolean areEqual(@NonNull Node o1, @NonNull Node o2) { return o1.equals(o2, this); }
-    };
+    NodeEqualityPredicate EXACT = new DummyNodeEqualityPredicate("EXACT");
 
     /**
-     * All attributes must match, except for
-     * {@link Node#getValue() value} and the
+     * Only the {@link Node#getKey() key}s need match, all other attributes are ignored.
+     */
+    NodeEqualityPredicate ONLY_KEY = new DummyNodeEqualityPredicate("ONLY_KEY");
+
+    /**
+     * All attributes must match, except for {@link Node#getValue() value}, which is ignored.
+     *
+     * <p>Returns true if: (and)</p>
+     * <p></p>
+     * <ul>
+     * <li>{@link Node#getKey() key} = key</li>
+     * <li>{@link Node#getContexts() context} = context</li>
+     * <li>{@link Node#getExpiry() expiry} = expiry</li>
+     * </ul>
+     */
+    NodeEqualityPredicate IGNORE_VALUE = new DummyNodeEqualityPredicate("IGNORE_VALUE");
+
+    /**
+     * All attributes must match, except for the {@link Node#getExpiry() expiry time}, which is
+     * ignored.
+     *
+     * <p>Note that with this setting, whether a node has an expiry or not is still considered.</p>
+     *
+     * <p>Returns true if: (and)</p>
+     * <p></p>
+     * <ul>
+     * <li>{@link Node#getKey() key} = key</li>
+     * <li>{@link Node#getValue() value} = value</li>
+     * <li>{@link Node#getContexts() context} = context</li>
+     * <li>{@link Node#hasExpiry() has expiry} = has expiry</li>
+     * </ul>
+     */
+    NodeEqualityPredicate IGNORE_EXPIRY_TIME = new DummyNodeEqualityPredicate("IGNORE_EXPIRY_TIME");
+
+    /**
+     * All attributes must match, except for {@link Node#getValue() value} and the
      * {@link Node#getExpiry() expiry time}, which are ignored.
+     *
+     * <p>Note that with this setting, whether a node has an expiry or not is still considered.</p>
+     *
+     * <p>Returns true if: (and)</p>
+     * <p></p>
+     * <ul>
+     * <li>{@link Node#getKey() key} = key</li>
+     * <li>{@link Node#getContexts() context} = context</li>
+     * <li>{@link Node#hasExpiry() has expiry} = has expiry</li>
+     * </ul>
      */
-    NodeEqualityPredicate IGNORE_EXPIRY_TIME_AND_VALUE = new NodeEqualityPredicate() {
-        @Override public boolean areEqual(@NonNull Node o1, @NonNull Node o2) { return o1.equals(o2, this); }
-    };
+    NodeEqualityPredicate IGNORE_EXPIRY_TIME_AND_VALUE = new DummyNodeEqualityPredicate("IGNORE_EXPIRY_TIME_AND_VALUE");
 
     /**
-     * All attributes must match, except for
-     * {@link Node#getValue() value} and the if the node is
-     * {@link Node#hasExpiry() temporary}, which are ignored.
+     * All attributes must match, except for {@link Node#getValue() value} and the if the node
+     * {@link Node#hasExpiry() has an expiry}, which are ignored.
+     *
+     * <p>Effectively only considers the key and the context.</p>
+     *
+     * <p>Returns true if: (and)</p>
+     * <p></p>
+     * <ul>
+     * <li>{@link Node#getKey() key} = key</li>
+     * <li>{@link Node#getContexts() context} = context</li>
+     * </ul>
      */
-    NodeEqualityPredicate IGNORE_VALUE_OR_IF_TEMPORARY = new NodeEqualityPredicate() {
-        @Override public boolean areEqual(@NonNull Node o1, @NonNull Node o2) { return o1.equals(o2, this); }
-    };
+    NodeEqualityPredicate IGNORE_VALUE_OR_IF_TEMPORARY = new DummyNodeEqualityPredicate("IGNORE_VALUE_OR_IF_TEMPORARY");
 
 }

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

@@ -48,47 +48,47 @@ 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}.
      */
-    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}.

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

@@ -0,0 +1,149 @@
+/*
+ * 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.node.matcher;
+
+import net.luckperms.api.LuckPermsProvider;
+import net.luckperms.api.node.Node;
+import net.luckperms.api.node.NodeEqualityPredicate;
+import net.luckperms.api.node.NodeType;
+import net.luckperms.api.node.types.MetaNode;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.NonExtendable;
+
+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> {
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes with the same {@link Node#getKey() key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * @param key the key
+     * @return the matcher
+     */
+    static @NonNull NodeMatcher<Node> key(@NonNull String key) {
+        return LuckPermsProvider.get().getNodeMatcherFactory().key(key);
+    }
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes with the same {@link Node#getKey() key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * @param node the node to use for the key
+     * @param <T> the node type
+     * @return the matcher
+     */
+    static <T extends Node> @NonNull NodeMatcher<T> key(@NonNull T node) {
+        return LuckPermsProvider.get().getNodeMatcherFactory().key(node);
+    }
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes with a {@link Node#getKey() key} starting
+     * with the given string.
+     *
+     * @param startingWith the string to match
+     * @return the matcher
+     */
+    static @NonNull NodeMatcher<Node> keyStartsWith(@NonNull String startingWith) {
+        return LuckPermsProvider.get().getNodeMatcherFactory().keyStartsWith(startingWith);
+    }
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes which are
+     * {@link Node#equals(Node, NodeEqualityPredicate) equal to} the given {@code other} node
+     * according to the {@link NodeEqualityPredicate}.
+     *
+     * @param other the other node to test against
+     * @param equalityPredicate the equality predicate
+     * @param <T> the node type
+     * @return the matcher
+     */
+    static <T extends Node> @NonNull NodeMatcher<T> equals(@NonNull T other, @NonNull NodeEqualityPredicate equalityPredicate) {
+        return LuckPermsProvider.get().getNodeMatcherFactory().equals(other, equalityPredicate);
+    }
+
+    /**
+     * Gets a {@link NodeMatcher} which matches {@link MetaNode}s with the same
+     * {@link MetaNode#getMetaKey() meta key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * @param metaKey the meta key
+     * @return the matcher
+     */
+    static @NonNull NodeMatcher<MetaNode> metaKey(@NonNull String metaKey) {
+        return LuckPermsProvider.get().getNodeMatcherFactory().metaKey(metaKey);
+    }
+
+    /**
+     * Gets a {@link NodeMatcher} which matches {@link MetaNode}s with the same
+     * {@link MetaNode#getMetaKey() meta key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * @param metaNode the meta node to use for the meta key
+     * @return the matcher
+     */
+    static @NonNull NodeMatcher<MetaNode> metaKey(@NonNull MetaNode metaNode) {
+        return metaKey(metaNode.getMetaKey());
+    }
+
+    /**
+     * Gets a {@link NodeMatcher} which matches {@link Node}s with the same
+     * type as the given {@link NodeType}.
+     *
+     * <p>{@link NodeType#PERMISSION}, {@link NodeType#CHAT_META} and
+     * {@link NodeType#META_OR_CHAT_META} are not supported by this method.</p>
+     *
+     * @param type the node type
+     * @param <T> the node type
+     * @return the matcher
+     */
+    static <T extends Node> @NonNull NodeMatcher<T> type(NodeType<? extends T> type) {
+        return LuckPermsProvider.get().getNodeMatcherFactory().type(type);
+    }
+
+    /**
+     * Tests to see if the given {@link Node} matches.
+     *
+     * @param node the node to test
+     * @return true if the node matched
+     */
+    @Override
+    boolean test(@NonNull Node node);
+}

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

@@ -0,0 +1,122 @@
+/*
+ * 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.node.matcher;
+
+import net.luckperms.api.node.Node;
+import net.luckperms.api.node.NodeEqualityPredicate;
+import net.luckperms.api.node.NodeType;
+import net.luckperms.api.node.types.MetaNode;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.ApiStatus.Internal;
+
+/**
+ * A factory which creates {@link NodeMatcher}s.
+ *
+ * @since 5.1
+ */
+@Internal
+public interface NodeMatcherFactory {
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes with the same {@link Node#getKey() key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * <p>Prefer using the {@link NodeMatcher#key(String)} accessor.</p>
+     *
+     * @param key the key
+     * @return the matcher
+     */
+    @NonNull NodeMatcher<Node> key(@NonNull String key);
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes with the same {@link Node#getKey() key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * <p>Prefer using the {@link NodeMatcher#key(Node)} accessor.</p>
+     *
+     * @param node the node to use for the key
+     * @param <T> the node type
+     * @return the matcher
+     */
+    <T extends Node> @NonNull NodeMatcher<T> key(@NonNull T node);
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes with a {@link Node#getKey() key} starting
+     * with the given string.
+     *
+     * <p>Prefer using the {@link NodeMatcher#keyStartsWith(String)} accessor.</p>
+     *
+     * @param startingWith the string to match
+     * @return the matcher
+     */
+    @NonNull NodeMatcher<Node> keyStartsWith(@NonNull String startingWith);
+
+    /**
+     * Gets a {@link NodeMatcher} which matches nodes which are
+     * {@link Node#equals(Node, NodeEqualityPredicate) equal to} the given {@code other} node
+     * according to the {@link NodeEqualityPredicate}.
+     *
+     * <p>Prefer using the {@link NodeMatcher#equals(Node, NodeEqualityPredicate)} accessor.</p>
+     *
+     * @param other the other node to test against
+     * @param equalityPredicate the equality predicate
+     * @param <T> the node type
+     * @return the matcher
+     */
+    <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
+     * {@link MetaNode#getMetaKey() meta key}.
+     *
+     * <p>The {@link String#equalsIgnoreCase(String)} method is used to test key equality.</p>
+     *
+     * <p>Prefer using the {@link NodeMatcher#metaKey(String)} accessor.</p>
+     *
+     * @param metaKey the meta key
+     * @return the matcher
+     */
+    @NonNull NodeMatcher<MetaNode> metaKey(@NonNull String metaKey);
+
+    /**
+     * Gets a {@link NodeMatcher} which matches {@link Node}s with the same
+     * type as the given {@link NodeType}.
+     *
+     * <p>{@link NodeType#PERMISSION}, {@link NodeType#CHAT_META} and
+     * {@link NodeType#META_OR_CHAT_META} are not supported by this method.</p>
+     *
+     * <p>Prefer using the {@link NodeMatcher#type(NodeType)} accessor.</p>
+     *
+     * @param type the node type
+     * @param <T> the node type
+     * @return the matcher
+     */
+    <T extends Node> @NonNull NodeMatcher<T> type(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;