Release API 5.1

it was a firewall config error at my end after all lol woops

.github/FUNDING.yml

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

.gitignore

@@ -1,37 +1,77 @@
-# built application files
-*.jar
-
-# Java class files
-*.class
-
-# Local configuration file (sdk path, etc)
-logs/
-
-# Eclipse project files
-.classpath
-.project
-
-# Intellij project files
-*.iml
-*.ipr
-*.iws
-.idea/
-
-# Gradle
-.gradletasknamecache
+### Gradle & IntelliJ ###
 .gradle/
+/.idea/
 build/
-bin/
-gradle/
-gradlew*
+out/
+run/
+*.iml
+.idea_modules/
 
-# Maven
-target/
-pom.xml.tag
-pom.xml.releaseBackup
-pom.xml.versionsBackup
-pom.xml.next
-release.properties
-dependency-reduced-pom.xml
-buildNumber.properties
-.mvn/timing.properties
+
+### Eclipse ###
+.metadata
+bin/
+tmp/
+*.tmp
+*.bak
+*.swp
+*~.nib
+local.properties
+.settings/
+.loadpath
+.recommenders
+.externalToolBuilders/
+*.launch
+.factorypath
+.recommenders/
+.apt_generated/
+.project
+.classpath
+
+
+### Linux ###
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+
+
+### macOS ###
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+
+### NetBeans ###
+nbproject/private/
+build/
+nbbuild/
+dist/
+nbdist/
+.nb-gradle/
+
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.lnk

CONTRIBUTING.md

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

HEADER.txt

@@ -0,0 +1,22 @@
+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.

LICENSE.txt

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+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
@@ -18,4 +19,4 @@ 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.
+SOFTWARE.

README.md

@@ -1,254 +1,50 @@
-# LuckPerms [![Build Status](https://ci.lucko.me/job/LuckPerms/badge/icon)](https://ci.lucko.me/job/LuckPerms/)
-A permissions implementation for Bukkit/Spigot, BungeeCord and Sponge.
+![alt text](https://i.imgur.com/ToguFkQ.png "Banner")
+# LuckPerms
+[![Build Status](https://ci.lucko.me/job/LuckPerms/badge/icon)](https://ci.lucko.me/job/LuckPerms/)
+[![javadoc](https://javadoc.io/badge2/net.luckperms/api/javadoc.svg)](https://javadoc.io/doc/net.luckperms/api)
+[![Maven Central](https://img.shields.io/maven-metadata/v/https/repo1.maven.org/maven2/net/luckperms/api/maven-metadata.xml.svg?label=maven%20central&colorB=brightgreen)](https://search.maven.org/artifact/net.luckperms/api)
+[![Discord](https://img.shields.io/discord/241667244927483904.svg?logo=discord&label=)](https://discord.gg/luckperms)
 
-## Links
-* **Development Builds** - <https://ci.lucko.me/job/LuckPerms>
-* **Javadocs** - <https://jd.lucko.me/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.
 
-## Features
-* **Group inheritance** - users can be members of multiple groups, groups can inherit other groups
-* **Temporary permissions** - users/groups can be given permissions that expire after a given time
-* **Wildcard permissions** - users/groups can be given wildcard permissions (e.g. "minecraft.command.*"), even when plugins haven't implemented their own wildcards.
-* **Temporary groups** - users/groups can be added to/inherit other groups temporarily
-* **Multi-server support** - data is synced across all servers/platforms
-* **Full offline-mode/mixed-mode support** - player permissions are synced properly over offline-mode or mixed online/offline-mode networks.
-* **Per-server permissions/groups** - define user/group permissions that only apply on certain servers
-* **Per-world permissions/groups** - define user/group permissions that only apply on certain worlds (on BungeeCord, a connected Bukkit/Spigot instance is treated as a world)
-* **Tracks / paths / ladders** - users can be promoted/demoted along multiple group tracks
-* **Vault Support** - hooks into Vault to integrate with other plugins
-* **Developer API** - easily integrate LuckPerms into your own projects
-* **Advanced action logging** - keep track of permission changes over time
-* **Easily switch between storage systems** - export a log file from one datastore and import it into another
-* **Easy and simple setup and configuration using commands** - no editing yml files, yuck
-* **Negated permissions and groups** - define special rules for certain users/groups
-* **Regex permissions** - define special permissions using regex
-* **Shorthand nodes** - add nodes using the LuckPerms shorthand system
-* **Full support for UUIDs, even in Offline Mode** - users can change their usernames without losing permissions. In offline mode, a single user has the same internal UUID across a network.
-* **Permission data stored within MySQL in a json format** - easily integrate the LuckPerms backend into your other projects
-* **Well documented** - API methods have comprehensive Java docs, it's clear what each method does.
-* **Efficient/lightweight** - maybe? Who knows, it might be.
-* **Open Sourced, Free...** - you shouldn't have to pay $10+ for a "powerful" permissions plugin.
-* **BungeeCord compatible** - permissions, users and groups are synced across all LuckPerms instances
-* **Sponge compatible** - permissions, users and groups are synced across all LuckPerms instances (bukkit --> sponge, for example)
-* **Support for MySQL, MongoDB, SQLite, H2 & Flatfile (JSON)** - other storage methods coming soon (maybe)
+LuckPerms also includes an extensive API for developers, and support for a variety of Minecraft server software & data storage options.
 
-## Setup
-All configuration options are in the **config.yml/luckperms.conf** file, which is generated automagically when the plugin first starts.
+Still not convinced? More information can be found on the wiki, under: [Why LuckPerms?](https://github.com/lucko/LuckPerms/wiki/Why-LuckPerms)
 
-You can define the settings for per-server permissions, the storage method and credentials within this file.
+## Useful Links
 
-## Info
-### Permission Calculation
-#### Permissions are calculated based on a priority system as follows.
+The latest **downloads** can be found on the [project's homepage](https://luckperms.net/).
 
-* **Non wildcard/regex permissions will be overridden by normal permissions**
+More information about the project & how to use the plugin can be found in the [wiki](https://github.com/lucko/LuckPerms/wiki).
 
-Example: if a user has a true permission set for "luckperms.\*", and a false permission set for "luckperms.something", the non-wildcard permission will override the wildcard, and "luckperms.something" will be set to false, despite the wildcard.
+## Building
+LuckPerms uses Gradle to handle dependencies & building.
 
-* **More specific wildcards override less specific ones**
+#### Requirements
+* Java 8 JDK or newer
+* Git
 
-Example: if a user has "luckperms.\*" set to true, but "luckperms.user.\*" set to false, all of the user permissions will be set to false, despite the more generic wildcard for "luckperms.*".
-
-* **Temporary permissions will override non-temporary permissions.**
-
-Example: if a user has a false permission set for "test.node", and a temporary true permission set for "test.node", the temporary permission will override the permanent one, and the user will be granted the true node.
-
-* **World specific permissions will override generic permissions.**
-
-Example: if a user has a global "fly.use" permission, and then has a negated "fly.use" permission in the "world_nether" world, the world specific permission will override the globally defined one, and the user will be granted the negated node (provided they're in that world, of course.).
-
-* **Server specific permissions will override generic/global permissions.**
-
-Example: if a user has a global "fly.use" permission, and then has a negated "fly.use" permission on the "factions" server, the server specific permission will override the globally defined one, and the user will be granted the negated node (provided they're on that server).
-
-* **Inherited permissions will be overridden by an objects own permissions.**
-
-Example: A user is a member of the default group, which grants "some.thing.perm", but the users own permissions has "some.thing.perm" set to false. The inherited permission will be overridden by the users own permissions, and the user will be granted the negative node.
-
-### Temporary Permissions
-Temporary permissions are checked each time a user/group is loaded, and when the sync task runs. This means if you set a temporary permission to expire after 30 seconds, it won't actually be removed until the sync task runs.
-
-The only way around this is to decrease the sync interval.
-
-### Shorthand Permissions
-LuckPerms has it's own system (although it's quite similar to PermissionsEx :P) that allows you to set permissions in a shorthand format.
-
-Using the LuckPerms permission nodes as an example, say for instance, you wanted to let a user set and unset permissions for both groups and users.
-
-Without shorthand, you would have to apply 4 nodes.
-```
-luckperms.user.setpermission
-luckperms.user.unsetpermission
-luckperms.group.setpermission
-luckperms.group.unsetpermission
-```
-However, with shorthand, you can just apply the following node:
-
-`luckperms.(user|group).(setpermission|unsetpermission)`
-
-You use brackets to define part of a node as a shorthand group, and then use the vertical bar `|` to separate entries.
-
-There are some limitations, firstly, you cannot use shorthand in the first part of the node. (The "luckperms" part in the example above)
-
-Additionally, you cannot combine shorthand and normal text in the same part of the node.
-For example, `luckperms.(user|group).(set|unset)permission` would not work.
-
-### Regex
-LuckPerms has support for regex when defining permission nodes and server/world names.
-
-Whenever regex is used, it MUST be prefixed with "R=", so LuckPerms knows to treat it as regex, and not as a normal string.
-
-For example, if you wanted to give all members of the default group, the `essentials.fly` permission on all of your hub servers, where the hub server names are hub1, hub2, hub3, etc.
-You would use the command `/perms group default set essentials.fly true R=hub\d+`.
-
-You can also use regex in permission nodes.
-Once again using LuckPerms permissions as an example, if you wanted a user to be able to create both groups and tracks, you would normally just add the two permission nodes. However with regex, you can just add one. `luckperms\.create.*` Remember to escape any characters, specifically dots, as the entire node will be parsed.
-
-## API
-LuckPerms has an extensive API, allowing for easy integration with other projects. To use the Api, you need to obtain an instance of the `LuckPermsApi` interface. This can be done in a number of ways.
-
-```java
-// On all platforms (throws IllegalStateException if the API is not loaded)
-final LuckPermsApi api = LuckPerms.getApi();
-
-// Or with Optional
-Optional<LuckPermsApi> provider = LuckPerms.getApiSafe();
-if (provider.isPresent()) {
-    final LuckPermsApi api = provider.get();
-}
-
-// On Bukkit/Spigot
-ServicesManager manager = Bukkit.getServicesManager();
-if (manager.isProvidedFor(LuckPermsApi.class)) {
-    final LuckPermsApi api = manager.getRegistration(LuckPermsApi.class).getProvider();
-}
-
-// On Sponge
-Optional<LuckPermsApi> provider = Sponge.getServiceManager().provide(LuckPermsApi.class);
-if (provider.isPresent()) {
-    final LuckPermsApi api = provider.get();
-}
+#### Compiling from source
+```sh
+git clone https://github.com/lucko/LuckPerms.git
+cd LuckPerms/
+./gradlew build
 ```
 
-If you want to use LuckPerms in your onEnable method, you need to add the following to your plugins `plugin.yml`.
-```yml
-depend: [LuckPerms]
-```
-All of the available methods can be seen in the various interfaces in the `luckperms-api` module.
+You can find the output jars in the `build/libs` directories.
 
-You can add LuckPerms as a Maven dependency by adding the following to your projects `pom.xml`.
-````xml
-<repositories>
-    <repository>
-        <id>luck-repo</id>
-        <url>https://repo.lucko.me/</url>
-    </repository>
-</repositories>
+## Contributing
+#### Pull Requests
+If you make any changes or improvements to the plugin which you think would be beneficial to others, please consider making a pull request to merge your changes back into the upstream project. (especially if your changes are bug fixes!)
 
-<dependencies>
-    <dependency>
-        <groupId>me.lucko.luckperms</groupId>
-        <artifactId>luckperms-api</artifactId>
-        <version>2.3</version>
-    </dependency>
-</dependencies>
-````
+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. 
 
-## Versioning
-As of version 2.0, LuckPerms roughly follows the standards set out in Semantic Versioning.
+#### Project Layout
+The project is split up into a few separate modules.
 
-The only difference is that the patch number is not included anywhere within the pom, and is calculated each build, based upon how may commits have been made since the last tag. (A new tag is made every minor version)
-
-This means that API versions do not have a patch number (as no API changes are made in patches). API versions will be x.y, and each individual build of LuckPerms will follow x.y.z.
-
-## Commands
-Command usage is printed to the console/chat whenever invalid arguments are provided. Simply typing /perms will list all commands a user has permission to use.
-
-### Aliases
-| Bukkit           | Bungee           |
-|------------------|------------------|
-| /luckperms       | /luckpermsbungee |
-| /perms           | /bperms          |
-| /permissions     | /bpermissions    |
-| /lp              | /lpb             |
-| /perm            | /bperm           |
-
-Arguments: \<required\> [optional]
-
-Users with OP have access to all commands.
-
-Additionally, you can use wildcards to grant users access to a selection of commands.
-* **All commands** - luckperms.*
-* **All user commands** - luckperms.user.*
-* **All group commands** - luckperms.group.*
-* **All track commands** - luckperms.track.*
-* **All log commands** - luckperms.log.*
-
-### General
-*  /perms - n/a
-*  /perms sync - luckperms.sync
-*  /perms info - luckperms.info
-*  /perms debug - luckperms.debug
-*  /perms import \<file\> - luckperms.import
-*  /perms creategroup \<group\> - luckperms.creategroup
-*  /perms deletegroup \<group\> - luckperms.deletegroup
-*  /perms listgroups - luckperms.listgroups
-*  /perms createtrack \<track\> - luckperms.createtrack
-*  /perms deletetrack \<track\> - luckperms.deletetrack
-*  /perms listtracks - luckperms.listtracks
-
-### User
-*  /perms user \<user\> info - luckperms.user.info
-*  /perms user \<user\> getuuid - luckperms.user.getuuid
-*  /perms user \<user\> listnodes - luckperms.user.listnodes
-*  /perms user \<user\> haspermission \<node\> [server] [world] - luckperms.user.haspermission
-*  /perms user \<user\> inheritspermission \<node\> [server] [world] - luckperms.user.inheritspermission
-*  /perms user \<user\> set \<node\> \<true/false\> [server] [world] - luckperms.user.setpermission
-*  /perms user \<user\> unset \<node\> [server] [world] -  luckperms.user.unsetpermission
-*  /perms user \<user\> addgroup \<group\> [server] [world] - luckperms.user.addgroup
-*  /perms user \<user\> removegroup \<group\> [server] [world] - luckperms.user.removegroup
-*  /perms user \<user\> settemp \<node\> \<true/false\> \<duration\> [server] [world] - luckperms.user.settemppermission
-*  /perms user \<user\> unsettemp \<node\> [server] [world] - luckperms.user.unsettemppermission
-*  /perms user \<user\> addtempgroup \<group\> \<duration\> [server] [world] - luckperms.user.addtempgroup
-*  /perms user \<user\> removetempgroup \<group\> [server] [world] - luckperms.user.removetempgroup
-*  /perms user \<user\> setprimarygroup \<group\> - luckperms.user.setprimarygroup
-*  /perms user \<user\> showtracks - luckperms.user.showtracks
-*  /perms user \<user\> promote \<track\> - luckperms.user.promote
-*  /perms user \<user\> demote \<track\> - luckperms.user.demote
-*  /perms user \<user\> showpos \<track\> - luckperms.user.showpos
-*  /perms user \<user\> clear - luckperms.user.clear
-
-### Group
-*  /perms group \<group\> info - 	luckperms.group.info
-*  /perms group \<group\> listnodes - luckperms.group.listnodes
-*  /perms group \<group\> haspermission \<node\> [server] [world] - luckperms.group.haspermission
-*  /perms group \<group\> inheritspermission \<node\> [server] [world] - luckperms.group.inheritspermission
-*  /perms group \<group\> set \<node\> \<true/false\> [server] [world] - luckperms.group.setpermission
-*  /perms group \<group\> unset \<node\> [server] [world] - luckperms.group.unsetpermission
-*  /perms group \<group\> setinherit \<group\> [server] [world] - luckperms.group.setinherit
-*  /perms group \<group\> unsetinherit \<group\> [server] [world] - luckperms.group.unsetinherit
-*  /perms group \<group\> settemp \<node\> \<true/false\> \<duration\> [server] [world] - settemppermission
-*  /perms group \<group\> unsettemp \<node\> [server] [world] - luckperms.group.unsettemppermission
-*  /perms group \<group\> settempinherit \<group\> \<duration\> [server] [world] - luckperms.group.settempinherit
-*  /perms group \<group\> unsettempinherit \<group\> [server] [world] - luckperms.group.unsettempinherit
-*  /perms group \<group\> showtracks - luckperms.group.showtracks
-*  /perms group \<group\> clear - luckperms.group.clear
-
-### Track
-*  /perms track \<track\> info - luckperms.track.info
-*  /perms track \<track\> append \<group\> - luckperms.track.append
-*  /perms track \<track\> insert \<group\> \<position\> - luckperms.track.insert
-*  /perms track \<track\> remove \<group\> - luckperms.track.remove
-*  /perms track \<track\> clear - luckperms.track.clear
-
-### Log
-*  /perms log recent [user] [page] - luckperms.log.recent
-*  /perms log search \<query\> [page] - luckperms.log.search
-*  /perms log notify [on|off] - luckperms.log.notify
-*  /perms log export \<file\> - luckperms.log.export
-*  /perms log userhistory \<user\> [page] - luckperms.log.userhistory
-*  /perms log grouphistory \<group\> [page] - luckperms.log.grouphistory
-*  /perms log trackhistory \<track\> [page] - luckperms.log.trackhistory
+* **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.
 
 ## License
-See LICENSE.md.
+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

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

api/pom.xml

@@ -1,39 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <parent>
-        <artifactId>luckperms</artifactId>
-        <groupId>me.lucko.luckperms</groupId>
-        <version>2.4</version>
-    </parent>
-    <modelVersion>4.0.0</modelVersion>
-
-    <artifactId>luckperms-api</artifactId>
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.5.1</version>
-                <configuration>
-                    <source>1.8</source>
-                    <target>1.8</target>
-                </configuration>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-                <version>3.0.1</version>
-                <executions>
-                    <execution>
-                        <id>attach-sources</id>
-                        <goals>
-                            <goal>jar-no-fork</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-        </plugins>
-    </build>
-</project>

api/src/main/java/me/lucko/luckperms/api/Datastore.java

@@ -1,104 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import me.lucko.luckperms.api.data.Callback;
-
-import java.util.UUID;
-
-/**
- * Wrapper interface for the internal Datastore instance
- *
- * <p> The implementations of this interface limit access to the datastore and add parameter checks to further prevent
- * errors and ensure all API interactions to not damage the state of the plugin.
- */
-@SuppressWarnings("unused")
-public interface Datastore {
-
-    String getName();
-    boolean isAcceptingLogins();
-
-    Async async();
-    Sync sync();
-    Future future();
-
-    interface Async {
-        void logAction(LogEntry entry, Callback<Boolean> callback);
-        void getLog(Callback<Log> callback);
-        void loadOrCreateUser(UUID uuid, String username, Callback<Boolean> callback);
-        void loadUser(UUID uuid, Callback<Boolean> callback);
-        void saveUser(User user, Callback<Boolean> callback);
-        void createAndLoadGroup(String name, Callback<Boolean> callback);
-        void loadGroup(String name, Callback<Boolean> callback);
-        void loadAllGroups(Callback<Boolean> callback);
-        void saveGroup(Group group, Callback<Boolean> callback);
-        void deleteGroup(Group group, Callback<Boolean> callback);
-        void createAndLoadTrack(String name, Callback<Boolean> callback);
-        void loadTrack(String name, Callback<Boolean> callback);
-        void loadAllTracks(Callback<Boolean> callback);
-        void saveTrack(Track track, Callback<Boolean> callback);
-        void deleteTrack(Track track, Callback<Boolean> callback);
-        void saveUUIDData(String username, UUID uuid, Callback<Boolean> callback);
-        void getUUID(String username, Callback<UUID> callback);
-    }
-
-    interface Sync {
-        boolean logAction(LogEntry entry);
-        Log getLog();
-        boolean loadOrCreateUser(UUID uuid, String username);
-        boolean loadUser(UUID uuid);
-        boolean saveUser(User user);
-        boolean createAndLoadGroup(String name);
-        boolean loadGroup(String name);
-        boolean loadAllGroups();
-        boolean saveGroup(Group group);
-        boolean deleteGroup(Group group);
-        boolean createAndLoadTrack(String name);
-        boolean loadTrack(String name);
-        boolean loadAllTracks();
-        boolean saveTrack(Track track);
-        boolean deleteTrack(Track track);
-        boolean saveUUIDData(String username, UUID uuid);
-        UUID getUUID(String username);
-    }
-
-    interface Future {
-        java.util.concurrent.Future<Boolean> logAction(LogEntry entry);
-        java.util.concurrent.Future<Log> getLog();
-        java.util.concurrent.Future<Boolean> loadOrCreateUser(UUID uuid, String username);
-        java.util.concurrent.Future<Boolean> loadUser(UUID uuid);
-        java.util.concurrent.Future<Boolean> saveUser(User user);
-        java.util.concurrent.Future<Boolean> createAndLoadGroup(String name);
-        java.util.concurrent.Future<Boolean> loadGroup(String name);
-        java.util.concurrent.Future<Boolean> loadAllGroups();
-        java.util.concurrent.Future<Boolean> saveGroup(Group group);
-        java.util.concurrent.Future<Boolean> deleteGroup(Group group);
-        java.util.concurrent.Future<Boolean> createAndLoadTrack(String name);
-        java.util.concurrent.Future<Boolean> loadTrack(String name);
-        java.util.concurrent.Future<Boolean> loadAllTracks();
-        java.util.concurrent.Future<Boolean> saveTrack(Track track);
-        java.util.concurrent.Future<Boolean> deleteTrack(Track track);
-        java.util.concurrent.Future<Boolean> saveUUIDData(String username, UUID uuid);
-        java.util.concurrent.Future<UUID> getUUID(String username);
-    }
-}

api/src/main/java/me/lucko/luckperms/api/Group.java

@@ -1,195 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import me.lucko.luckperms.exceptions.ObjectAlreadyHasException;
-import me.lucko.luckperms.exceptions.ObjectLacksException;
-
-import java.util.List;
-
-/**
- * Wrapper interface for internal Group instances
- *
- * <p> The implementations of this interface limit access to the Group and add parameter checks to further prevent
- * errors and ensure all API interactions to not damage the state of the group.
- */
-@SuppressWarnings("unused")
-public interface Group extends PermissionHolder {
-
-    /**
-     * @return the name of the group
-     */
-    String getName();
-
-    /**
-     * check to see if a group inherits a group
-     * @param group The group to check membership of
-     * @return true if the user is a member of the group
-     */
-    boolean inheritsGroup(Group group);
-
-    /**
-     * check to see if the group inherits a group on a specific server
-     * @param group The group to check membership of
-     * @param server The server to check on
-     * @return true if the group inherits the group
-     */
-    boolean inheritsGroup(Group group, String server);
-
-    /**
-     * check to see if the group inherits a group on a specific server
-     * @param group The group to check membership of
-     * @param server The server to check on
-     * @param world The world to check on
-     * @return true if the group inherits the group
-     */
-    boolean inheritsGroup(Group group, String server, String world);
-
-    /**
-     * Make this group inherit another group
-     * @param group the group to be inherited
-     * @throws ObjectAlreadyHasException if the group already inherits the group
-     */
-    void setInheritGroup(Group group) throws ObjectAlreadyHasException;
-
-    /**
-     * Make this group inherit another group on a specific server
-     * @param group the group to be inherited
-     * @param server The server to add the group on
-     * @throws ObjectAlreadyHasException if the group already inherits the group on that server
-     */
-    void setInheritGroup(Group group, String server) throws ObjectAlreadyHasException;
-
-    /**
-     * Make this group inherit another group on a specific server
-     * @param group the group to be inherited
-     * @param server The server to add the group on
-     * @param world The world to add the group on
-     * @throws ObjectAlreadyHasException if the group already inherits the group on that server
-     */
-    void setInheritGroup(Group group, String server, String world) throws ObjectAlreadyHasException;
-
-    /**
-     * Make this group inherit another group on a specific server
-     * @param group the group to be inherited
-     * @param expireAt when the group should expire
-     * @throws ObjectAlreadyHasException if the group already inherits the group on that server
-     */
-    void setInheritGroup(Group group, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Make this group inherit another group on a specific server
-     * @param group the group to be inherited
-     * @param server The server to add the group on
-     * @param expireAt when the group should expire
-     * @throws ObjectAlreadyHasException if the group already inherits the group on that server
-     */
-    void setInheritGroup(Group group, String server, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Make this group inherit another group on a specific server
-     * @param group the group to be inherited
-     * @param server The server to add the group on
-     * @param world The world to add the group on
-     * @param expireAt when the group should expire
-     * @throws ObjectAlreadyHasException if the group already inherits the group on that server
-     */
-    void setInheritGroup(Group group, String server, String world, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Remove a previously set inheritance
-     * @param group the group to uninherit
-     * @throws ObjectLacksException if the group does not already inherit the group
-     */
-    void unsetInheritGroup(Group group) throws ObjectLacksException;
-
-    /**
-     * Remove a previously set inheritance
-     * @param group the group to uninherit
-     * @param temporary if the group being removed is temporary
-     * @throws ObjectLacksException if the group does not already inherit the group
-     */
-    void unsetInheritGroup(Group group, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Remove a previously set inheritance
-     * @param group the group to uninherit
-     * @param server The server to remove the group on
-     * @throws ObjectLacksException if the group does not already inherit the group
-     */
-    void unsetInheritGroup(Group group, String server) throws ObjectLacksException;
-
-    /**
-     * Remove a previously set inheritance
-     * @param group the group to uninherit
-     * @param server The server to remove the group on
-     * @param world The world to remove the group on
-     * @throws ObjectLacksException if the group does not already inherit the group
-     */
-    void unsetInheritGroup(Group group, String server, String world) throws ObjectLacksException;
-
-    /**
-     * Remove a previously set inheritance
-     * @param group the group to uninherit
-     * @param server The server to remove the group on
-     * @param temporary if the group being removed is temporary
-     * @throws ObjectLacksException if the group does not already inherit the group
-     */
-    void unsetInheritGroup(Group group, String server, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Remove a previously set inheritance
-     * @param group the group to uninherit
-     * @param server The server to remove the group on
-     * @param world The world to remove the group on
-     * @param temporary if the group being removed is temporary
-     * @throws ObjectLacksException if the group does not already inherit the group
-     */
-    void unsetInheritGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Clear all of the groups permission nodes
-     */
-    void clearNodes();
-
-    /**
-     * Get a {@link List} of all of the groups the group inherits, on all servers
-     * @return a {@link List} of group names
-     */
-    List<String> getGroupNames();
-
-    /**
-     * Get a {@link List} of the groups the group inherits on a specific server
-     * @param server the server to check
-     * @param world the world to check
-     * @return a {@link List} of group names
-     */
-    List<String> getLocalGroups(String server, String world);
-
-    /**
-     * Get a {@link List} of the groups the group inherits on a specific server
-     * @param server the server to check
-     * @return a {@link List} of group names
-     */
-    List<String> getLocalGroups(String server);
-}

api/src/main/java/me/lucko/luckperms/api/LPConfiguration.java

@@ -1,96 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import me.lucko.luckperms.api.data.DatastoreConfiguration;
-import me.lucko.luckperms.api.data.MySQLConfiguration;
-
-/**
- * A wrapper interface for the internal LuckPerms configuration, providing read only access.
- */
-public interface LPConfiguration {
-
-    /**
-     * @return the name of this server
-     */
-    String getServer();
-
-    /**
-     * @return how often a sync task will run in minutes
-     */
-    int getSyncTime();
-
-    /**
-     * @return the default group, in a node representation
-     */
-    String getDefaultGroupNode();
-
-    /**
-     * @return the name of the default group
-     */
-    String getDefaultGroupName();
-
-    /**
-     * @return if the users on this server will have their global permissions applied
-     */
-    boolean getIncludeGlobalPerms();
-
-    /**
-     * @return the online mode setting in the config
-     */
-    boolean getOnlineMode();
-
-    /**
-     * @return if LuckPerms is applying wildcard permissions
-     */
-    boolean getApplyWildcards();
-
-    /**
-     * @return if LuckPerms is resolving and applying regex permissions
-     */
-    boolean getApplyRegex();
-
-    /**
-     * @return if LuckPerms is expanding shorthand permissions
-     */
-    boolean getApplyShorthand();
-
-    /**
-     * @return the database values set in the configuration
-     * @deprecated use {@link #getDatastoreConfig()}
-     */
-    @SuppressWarnings("deprecation")
-    @Deprecated
-    MySQLConfiguration getDatabaseValues();
-
-    /**
-     * @return the values set for data storage in the configuration
-     */
-    DatastoreConfiguration getDatastoreConfig();
-
-    /**
-     * @return the storage method string from the configuration
-     */
-    String getStorageMethod();
-
-}

api/src/main/java/me/lucko/luckperms/api/Log.java

@@ -1,64 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import java.util.SortedMap;
-import java.util.SortedSet;
-import java.util.UUID;
-
-/**
- * Represents the internal LuckPerms log.
- * All content is immutable. You can add to the log using the {@link Datastore}, and then request an updated copy.
- */
-@SuppressWarnings("unused")
-public interface Log {
-
-    /**
-     * @return a {@link SortedSet} of all of the {@link LogEntry} objects in this {@link Log}
-     */
-    SortedSet<LogEntry> getContent();
-
-    SortedSet<LogEntry> getRecent();
-    SortedMap<Integer, LogEntry> getRecent(int pageNo);
-    int getRecentMaxPages();
-
-    SortedSet<LogEntry> getRecent(UUID actor);
-    SortedMap<Integer, LogEntry> getRecent(int pageNo, UUID actor);
-    int getRecentMaxPages(UUID actor);
-
-    SortedSet<LogEntry> getUserHistory(UUID uuid);
-    SortedMap<Integer, LogEntry> getUserHistory(int pageNo, UUID uuid);
-    int getUserHistoryMaxPages(UUID uuid);
-
-    SortedSet<LogEntry> getGroupHistory(String name);
-    SortedMap<Integer, LogEntry> getGroupHistory(int pageNo, String name);
-    int getGroupHistoryMaxPages(String name);
-
-    SortedSet<LogEntry> getTrackHistory(String name);
-    SortedMap<Integer, LogEntry> getTrackHistory(int pageNo, String name);
-    int getTrackHistoryMaxPages(String name);
-
-    SortedSet<LogEntry> getSearch(String query);
-    SortedMap<Integer, LogEntry> getSearch(int pageNo, String query);
-    int getSearchMaxPages(String query);
-}

api/src/main/java/me/lucko/luckperms/api/LogEntry.java

@@ -1,315 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import java.util.UUID;
-
-public class LogEntry implements Comparable<LogEntry> {
-    public static LogEntryBuilder builder() {
-        return new LogEntryBuilder();
-    }
-
-    private static final String FORMAT = "&8(&e%s&8) [&a%s&8] (&b%s&8) &7--> &f%s";
-
-    private long timestamp;
-    private UUID actor;
-    private String actorName;
-    private char type;
-    private UUID acted;
-    private String actedName;
-    private String action;
-
-    public LogEntry(long timestamp, UUID actor, String actorName, char type, UUID acted, String actedName, String action) {
-        if (actor == null) {
-            throw new NullPointerException("actor");
-        }
-        if (actorName == null) {
-            throw new NullPointerException("actorName");
-        }
-        if (actedName == null) {
-            throw new NullPointerException("actedName");
-        }
-        if (action == null) {
-            throw new NullPointerException("action");
-        }
-
-        this.timestamp = timestamp;
-        this.actor = actor;
-        this.actorName = actorName;
-        this.type = type;
-        this.acted = acted;
-        this.actedName = actedName;
-        this.action = action;
-    }
-
-    protected LogEntry() {
-        this.timestamp = 0L;
-        this.actor = null;
-        this.actorName = null;
-        this.type = Character.MIN_VALUE;
-        this.acted = null;
-        this.actedName = null;
-        this.action = null;
-    }
-
-    @Override
-    public int compareTo(LogEntry o) {
-        return equals(o) ? 0 : (Long.compare(timestamp, o.getTimestamp()) == 0 ? 1 : Long.compare(timestamp, o.getTimestamp()));
-    }
-
-    public boolean matchesSearch(String query) {
-        query = query.toLowerCase();
-        return actorName.toLowerCase().contains(query) || actedName.toLowerCase().contains(query)
-                || action.toLowerCase().contains(query);
-    }
-
-    public String getFormatted() {
-        return String.format(FORMAT,
-                actorName,
-                Character.toString(type),
-                actedName,
-                action
-        );
-    }
-
-    public long getTimestamp() {
-        return timestamp;
-    }
-
-    public UUID getActor() {
-        return actor;
-    }
-
-    public String getActorName() {
-        return actorName;
-    }
-
-    public char getType() {
-        return type;
-    }
-
-    public UUID getActed() {
-        return acted;
-    }
-
-    public String getActedName() {
-        return actedName;
-    }
-
-    public String getAction() {
-        return action;
-    }
-
-    void setTimestamp(long timestamp) {
-        this.timestamp = timestamp;
-    }
-
-    void setActor(UUID actor) {
-        this.actor = actor;
-    }
-
-    void setActorName(String actorName) {
-        this.actorName = actorName;
-    }
-
-    void setType(char type) {
-        this.type = type;
-    }
-
-    void setActed(UUID acted) {
-        this.acted = acted;
-    }
-
-    void setActedName(String actedName) {
-        this.actedName = actedName;
-    }
-
-    void setAction(String action) {
-        this.action = action;
-    }
-
-    @Override
-    public String toString() {
-        return "LogEntry(timestamp=" + this.getTimestamp() + ", actor=" + this.getActor() + ", actorName=" +
-                this.getActorName() + ", type=" + this.getType() + ", acted=" + this.getActed() + ", actedName=" +
-                this.getActedName() + ", action=" + this.getAction() + ")";
-    }
-
-    @Override
-    public boolean equals(Object o) {
-        if (o == this) return true;
-        if (!(o instanceof LogEntry)) return false;
-        final LogEntry other = (LogEntry) o;
-        if (this.getTimestamp() != other.getTimestamp()) return false;
-        final Object this$actor = this.getActor();
-        final Object other$actor = other.getActor();
-        if (this$actor == null ? other$actor != null : !this$actor.equals(other$actor)) return false;
-        final Object this$actorName = this.getActorName();
-        final Object other$actorName = other.getActorName();
-        if (this$actorName == null ? other$actorName != null : !this$actorName.equals(other$actorName)) return false;
-        if (this.getType() != other.getType()) return false;
-        final Object this$acted = this.getActed();
-        final Object other$acted = other.getActed();
-        if (this$acted == null ? other$acted != null : !this$acted.equals(other$acted)) return false;
-        final Object this$actedName = this.getActedName();
-        final Object other$actedName = other.getActedName();
-        if (this$actedName == null ? other$actedName != null : !this$actedName.equals(other$actedName)) return false;
-        final Object this$action = this.getAction();
-        final Object other$action = other.getAction();
-        return this$action == null ? other$action == null : this$action.equals(other$action);
-    }
-
-    @Override
-    public int hashCode() {
-        final int PRIME = 59;
-        int result = 1;
-        final long $timestamp = this.getTimestamp();
-        result = result * PRIME + (int) ($timestamp >>> 32 ^ $timestamp);
-        final Object $actor = this.getActor();
-        result = result * PRIME + ($actor == null ? 43 : $actor.hashCode());
-        final Object $actorName = this.getActorName();
-        result = result * PRIME + ($actorName == null ? 43 : $actorName.hashCode());
-        result = result * PRIME + this.getType();
-        final Object $acted = this.getActed();
-        result = result * PRIME + ($acted == null ? 43 : $acted.hashCode());
-        final Object $actedName = this.getActedName();
-        result = result * PRIME + ($actedName == null ? 43 : $actedName.hashCode());
-        final Object $action = this.getAction();
-        result = result * PRIME + ($action == null ? 43 : $action.hashCode());
-        return result;
-    }
-
-    public static class LogEntryBuilder extends AbstractLogEntryBuilder<LogEntry, LogEntry.LogEntryBuilder> {
-
-        @Override
-        protected LogEntry createObj() {
-            return new LogEntry();
-        }
-
-        @Override
-        protected LogEntryBuilder getThis() {
-            return this;
-        }
-    }
-
-    public static abstract class AbstractLogEntryBuilder<T extends LogEntry, B extends AbstractLogEntryBuilder<T, B>> {
-        private T obj;
-        private B thisObj;
-
-        public AbstractLogEntryBuilder() {
-            obj = createObj();
-            thisObj = getThis();
-        }
-
-        protected abstract T createObj();
-        protected abstract B getThis();
-
-        public long getTimestamp() {
-            return obj.getTimestamp();
-        }
-
-        public UUID getActor() {
-            return obj.getActor();
-        }
-
-        public String getActorName() {
-            return obj.getActorName();
-        }
-
-        public char getType() {
-            return obj.getType();
-        }
-
-        public UUID getActed() {
-            return obj.getActed();
-        }
-
-        public String getActedName() {
-            return obj.getActedName();
-        }
-
-        public String getAction() {
-            return obj.getAction();
-        }
-
-        public B timestamp(long timestamp) {
-            obj.setTimestamp(timestamp);
-            return thisObj;
-        }
-
-        public B actor(UUID actor) {
-            obj.setActor(actor);
-            return thisObj;
-        }
-
-        public B actorName(String actorName) {
-            obj.setActorName(actorName);
-            return thisObj;
-        }
-
-        public B type(char type) {
-            obj.setType(type);
-            return thisObj;
-        }
-
-        public B acted(UUID acted) {
-            obj.setActed(acted);
-            return thisObj;
-        }
-
-        public B actedName(String actedName) {
-            obj.setActedName(actedName);
-            return thisObj;
-        }
-
-        public B action(String action) {
-            obj.setAction(action);
-            return thisObj;
-        }
-
-        public T build() {
-            if (getActor() == null) {
-                throw new NullPointerException("actor");
-            }
-            if (getActorName() == null) {
-                throw new NullPointerException("actorName");
-            }
-            if (getActedName() == null) {
-                throw new NullPointerException("actedName");
-            }
-            if (getAction() == null) {
-                throw new NullPointerException("action");
-            }
-
-            return obj;
-        }
-
-        @Override
-        public String toString() {
-            return "LogEntry.LogEntryBuilder(timestamp=" + getTimestamp() + ", actor=" + getActor() + ", actorName=" +
-                    getActorName() + ", type=" + getType() + ", acted=" + getActed() + ", actedName=" + getActedName() +
-                    ", action=" + getAction() + ")";
-        }
-    }
-
-}

api/src/main/java/me/lucko/luckperms/api/LuckPermsApi.java

@@ -1,164 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import java.util.Optional;
-import java.util.Set;
-import java.util.UUID;
-
-/**
- * The root Api interface in LuckPerms
- */
-@SuppressWarnings("unused")
-public interface LuckPermsApi {
-
-    /**
-     * Schedules an update task to run
-     */
-    void runUpdateTask();
-
-    /**
-     * @return the version of the plugin running on the platform
-     */
-    String getVersion();
-
-    /**
-     * Gets a wrapped {@link LPConfiguration} instance, with read only access
-     * @return a configuration instance
-     */
-    LPConfiguration getConfiguration();
-
-    /**
-     * Gets a wrapped {@link Datastore} instance, with somewhat limited access
-     * @return a datastore instance
-     */
-    Datastore getDatastore();
-
-    /**
-     * Gets the {@link Logger} wrapping used by the platform
-     * @return the logger instance
-     */
-    Logger getLogger();
-
-    /**
-     * Gets a wrapped {@link UuidCache} instance, providing read access to the LuckPerms internal uuid caching system
-     * @return a uuidcache instance
-     */
-    UuidCache getUuidCache();
-
-    /**
-     * Gets a wrapped user object from the user storage
-     * @param uuid the uuid of the user to get
-     * @return a {@link User} object, if one matching the uuid is loaded, or null if not
-     */
-    User getUser(UUID uuid);
-
-    /**
-     * Gets a wrapped user object from the user storage. This method does not return null, unlike {@link #getUser(UUID)}
-     * @param uuid the uuid of the user to get
-     * @return an optional {@link User} object
-     */
-    Optional<User> getUserSafe(UUID uuid);
-
-    /**
-     * Gets a wrapped user object from the user storage
-     * @param name the username of the user to get
-     * @return a {@link User} object, if one matching the uuid is loaded, or null if not
-     */
-    User getUser(String name);
-
-    /**
-     * Gets a wrapped user object from the user storage. This method does not return null, unlike {@link #getUser(String)}
-     * @param name the username of the user to get
-     * @return an optional {@link User} object
-     */
-    Optional<User> getUserSafe(String name);
-
-    /**
-     * Gets a set of all loaded users.
-     * @return a {@link Set} of {@link User} objects
-     */
-    Set<User> getUsers();
-
-    /**
-     * Check if a user is loaded in memory
-     * @param uuid the uuid to check for
-     * @return true if the user is loaded
-     */
-    boolean isUserLoaded(UUID uuid);
-
-    /**
-     * Gets a wrapped group object from the group storage
-     * @param name the name of the group to get
-     * @return a {@link Group} object, if one matching the name exists, or null if not
-     */
-    Group getGroup(String name);
-
-    /**
-     * Gets a wrapped group object from the group storage. This method does not return null, unlike {@link #getGroup}
-     * @param name the name of the group to get
-     * @return an optional {@link Group} object
-     */
-    Optional<Group> getGroupSafe(String name);
-
-    /**
-     * Gets a set of all loaded groups.
-     * @return a {@link Set} of {@link Group} objects
-     */
-    Set<Group> getGroups();
-
-    /**
-     * Check if a group is loaded in memory
-     * @param name the name to check for
-     * @return true if the group is loaded
-     */
-    boolean isGroupLoaded(String name);
-
-    /**
-     * Gets a wrapped track object from the track storage
-     * @param name the name of the track to get
-     * @return a {@link Track} object, if one matching the name exists, or null if not
-     */
-    Track getTrack(String name);
-
-    /**
-     * Gets a wrapped tracj object from the track storage. This method does not return null, unlike {@link #getTrack}
-     * @param name the name of the track to get
-     * @return an optional {@link Track} object
-     */
-    Optional<Track> getTrackSafe(String name);
-
-    /**
-     * Gets a set of all loaded tracks.
-     * @return a {@link Set} of {@link Track} objects
-     */
-    Set<Track> getTracks();
-
-    /**
-     * Check if a track is loaded in memory
-     * @param name the name to check for
-     * @return true if the track is loaded
-     */
-    boolean isTrackLoaded(String name);
-
-}

api/src/main/java/me/lucko/luckperms/api/PermissionHolder.java

@@ -1,319 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import me.lucko.luckperms.exceptions.ObjectAlreadyHasException;
-import me.lucko.luckperms.exceptions.ObjectLacksException;
-
-import java.util.List;
-import java.util.Map;
-
-/**
- * Wrapper interface for internal PermissionHolder (user/group) instances
- *
- * <p> The implementations of this interface limit access to the object and add parameter checks to further prevent
- * errors and ensure all API interactions to not damage the state of the object.
- */
-@SuppressWarnings("unused")
-public interface PermissionHolder {
-
-    String getObjectName();
-
-    Map<String, Boolean> getNodes();
-
-    /**
-     * Checks to see if the object has a certain permission
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @return true if the user has the permission
-     */
-    boolean hasPermission(String node, boolean b);
-
-    /**
-     * Checks to see the the object has a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server
-     * @return true if the user has the permission
-     */
-    boolean hasPermission(String node, boolean b, String server);
-
-    /**
-     * Checks to see the the object has a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server
-     * @param world The world
-     * @return true if the user has the permission
-     */
-    boolean hasPermission(String node, boolean b, String server, String world);
-
-    /**
-     * Checks to see the the object has a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param temporary if the permission is temporary
-     * @return true if the user has the permission
-     */
-    boolean hasPermission(String node, boolean b, boolean temporary);
-
-    /**
-     * Checks to see the the object has a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server to check on
-     * @param temporary if the permission is temporary
-     * @return true if the user has the permission
-     */
-    boolean hasPermission(String node, boolean b, String server, boolean temporary);
-
-    /**
-     * Checks to see the the object has a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server to check on
-     * @param world The world to check on
-     * @param temporary if the permission is temporary
-     * @return true if the user has the permission
-     */
-    boolean hasPermission(String node, boolean b, String server, String world, boolean temporary);
-
-    /**
-     * Checks to see if the object inherits a certain permission
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @return true if the user inherits the permission
-     */
-    boolean inheritsPermission(String node, boolean b);
-
-    /**
-     * Checks to see the the object inherits a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server
-     * @return true if the user inherits the permission
-     */
-    boolean inheritsPermission(String node, boolean b, String server);
-
-    /**
-     * Checks to see the the object inherits a permission on a certain server
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server
-     * @param world The world
-     * @return true if the user inherits the permission
-     */
-    boolean inheritsPermission(String node, boolean b, String server, String world);
-
-    /**
-     * Checks to see if the object inherits a certain permission
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param temporary if the permission is temporary
-     * @return true if the user inherits the permission
-     */
-    boolean inheritsPermission(String node, boolean b, boolean temporary);
-
-    /**
-     * Checks to see if the object inherits a certain permission
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server
-     * @param temporary if the permission is temporary
-     * @return true if the user inherits the permission
-     */
-    boolean inheritsPermission(String node, boolean b, String server, boolean temporary);
-
-    /**
-     * Checks to see if the object inherits a certain permission
-     * @param node The permission node
-     * @param b If the node is true/false(negated)
-     * @param server The server
-     * @param world The world
-     * @param temporary if the permission is temporary
-     * @return true if the user inherits the permission
-     */
-    boolean inheritsPermission(String node, boolean b, String server, String world, boolean temporary);
-
-    /**
-     * Sets a permission for the object
-     * @param node The node to be set
-     * @param value What to set the node to - true/false(negated)
-     * @throws ObjectAlreadyHasException if the object already has the permission
-     */
-    void setPermission(String node, boolean value) throws ObjectAlreadyHasException;
-
-    /**
-     * Sets a permission for the object
-     * @param node The node to set
-     * @param value What to set the node to - true/false(negated)
-     * @param server The server to set the permission on
-     * @throws ObjectAlreadyHasException if the object already has the permission
-     */
-    void setPermission(String node, boolean value, String server) throws ObjectAlreadyHasException;
-
-    /**
-     * Sets a permission for the object
-     * @param node The node to set
-     * @param value What to set the node to - true/false(negated)
-     * @param server The server to set the permission on
-     * @param world The world to set the permission on
-     * @throws ObjectAlreadyHasException if the object already has the permission
-     */
-    void setPermission(String node, boolean value, String server, String world) throws ObjectAlreadyHasException;
-
-    /**
-     * Sets a permission for the object
-     * @param node The node to set
-     * @param value What to set the node to - true/false(negated)
-     * @param expireAt The time in unixtime when the permission will expire
-     * @throws ObjectAlreadyHasException if the object already has the permission
-     */
-    void setPermission(String node, boolean value, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Sets a permission for the object
-     * @param node The node to set
-     * @param value What to set the node to - true/false(negated)
-     * @param server The server to set the permission on
-     * @param expireAt The time in unixtime when the permission will expire
-     * @throws ObjectAlreadyHasException if the object already has the permission
-     */
-    void setPermission(String node, boolean value, String server, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Sets a permission for the object
-     * @param node The node to set
-     * @param value What to set the node to - true/false(negated)
-     * @param server The server to set the permission on
-     * @param world The world to set the permission on
-     * @param expireAt The time in unixtime when the permission will expire
-     * @throws ObjectAlreadyHasException if the object already has the permission
-     */
-    void setPermission(String node, boolean value, String server, String world, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Unsets a permission for the object
-     * @param node The node to be unset
-     * @param temporary if the permission being removed is temporary
-     * @throws ObjectLacksException if the node wasn't already set
-     */
-    void unsetPermission(String node, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Unsets a permission for the object
-     * @param node The node to be unset
-     * @throws ObjectLacksException if the node wasn't already set
-     */
-    void unsetPermission(String node) throws ObjectLacksException;
-
-    /**
-     * Unsets a permission for the object
-     * @param node The node to be unset
-     * @param server The server to unset the node on
-     * @throws ObjectLacksException if the node wasn't already set
-     */
-    void unsetPermission(String node, String server) throws ObjectLacksException;
-
-    /**
-     * Unsets a permission for the object
-     * @param node The node to be unset
-     * @param server The server to unset the node on
-     * @param world The world to unset the node on
-     * @throws ObjectLacksException if the node wasn't already set
-     */
-    void unsetPermission(String node, String server, String world) throws ObjectLacksException;
-
-    /**
-     * Unsets a permission for the object
-     * @param node The node to be unset
-     * @param server The server to unset the node on
-     * @param temporary if the permission being unset is temporary
-     * @throws ObjectLacksException if the node wasn't already set
-     */
-    void unsetPermission(String node, String server, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Unsets a permission for the object
-     * @param node The node to be unset
-     * @param server The server to unset the node on
-     * @param world The world to unset the node on
-     * @param temporary if the permission being unset is temporary
-     * @throws ObjectLacksException if the node wasn't already set
-     */
-    void unsetPermission(String node, String server, String world, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Gets the permissions and inherited permissions that apply to a specific server
-     * @param server The server to get nodes for
-     * @param world The world to get nodes for
-     * @param excludedGroups Groups that shouldn't be inherited (to prevent circular inheritance issues)
-     * @param possibleNodes A list of possible permission nodes for wildcard permission handling
-     * @return a {@link Map} of the permissions
-     */
-    Map<String, Boolean> getLocalPermissions(String server, String world, List<String> excludedGroups, List<String> possibleNodes);
-
-    /**
-     * Gets the permissions and inherited permissions that apply to a specific server
-     * @param server The server to get nodes for
-     * @param world The world to get nodes for
-     * @param excludedGroups Groups that shouldn't be inherited (to prevent circular inheritance issues)
-     * @return a {@link Map} of the permissions
-     */
-    Map<String, Boolean> getLocalPermissions(String server, String world, List<String> excludedGroups);
-
-    /**
-     * Gets the permissions and inherited permissions that apply to a specific server
-     * @param server The server to get nodes for
-     * @param excludedGroups Groups that shouldn't be inherited (to prevent circular inheritance issues)
-     * @param possibleNodes A list of possible permission nodes for wildcard permission handling
-     * @return a {@link Map} of the permissions
-     */
-    Map<String, Boolean> getLocalPermissions(String server, List<String> excludedGroups, List<String> possibleNodes);
-
-    /**
-     * Gets the permissions and inherited permissions that apply to a specific server
-     * @param server The server to get nodes for
-     * @param excludedGroups Groups that shouldn't be inherited (to prevent circular inheritance issues)
-     * @return a {@link Map} of the permissions
-     */
-    Map<String, Boolean> getLocalPermissions(String server, List<String> excludedGroups);
-
-    /**
-     * Processes the objects and returns the temporary ones.
-     * @return a map of temporary nodes
-     */
-    Map<Map.Entry<String, Boolean>, Long> getTemporaryNodes();
-
-    /**
-     * Processes the objects and returns the non-temporary ones.
-     * @return a map of permanent nodes
-     */
-    Map<String, Boolean> getPermanentNodes();
-
-    /**
-     * Removes temporary permissions that have expired
-     */
-    void auditTemporaryPermissions();
-
-}

api/src/main/java/me/lucko/luckperms/api/Track.java

@@ -1,118 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import me.lucko.luckperms.exceptions.ObjectAlreadyHasException;
-import me.lucko.luckperms.exceptions.ObjectLacksException;
-
-import java.util.List;
-
-/**
- * Wrapper interface for internal Track instances
- *
- * <p> The implementations of this interface limit access to the Track and add parameter checks to further prevent
- * errors and ensure all API interactions to not damage the state of the track.
- */
-@SuppressWarnings("unused")
-public interface Track {
-
-    String getName();
-
-    /**
-     * Gets an ordered list of the groups on this track
-     * @return am ordered {@link List} of the groups on this track
-     */
-    List<String> getGroups();
-
-    /**
-     * Gets the number of groups on this track
-     * @return the number of groups on this track
-     */
-    int getSize();
-
-    /**
-     * Gets the next group on the track, after the one provided
-     * @param current the group before the group being requested
-     * @return the group name, or null if the end of the track has been reached
-     * @throws ObjectLacksException if the track does not contain the group given
-     */
-    String getNext(Group current) throws ObjectLacksException;
-
-    /**
-     * Gets the group before the group provided
-     * @param current the group after the group being requested
-     * @return the group name, or null if the start of the track has been reached
-     * @throws ObjectLacksException if the track does not contain the group given
-     */
-    String getPrevious(Group current) throws ObjectLacksException;
-
-    /**
-     * Appends a group to the end of this track
-     * @param group the group to append
-     * @throws ObjectAlreadyHasException if the group is already on this track somewhere
-     */
-    void appendGroup(Group group) throws ObjectAlreadyHasException;
-
-    /**
-     * Inserts a group at a certain position on this track
-     * @param group the group to be inserted
-     * @param position the index position (a value of 0 inserts at the start)
-     * @throws ObjectAlreadyHasException if the group is already on this track somewhere
-     * @throws IndexOutOfBoundsException if the position is less than 0 or greater than the size of the track
-     */
-    void insertGroup(Group group, int position) throws ObjectAlreadyHasException, IndexOutOfBoundsException;
-
-    /**
-     * Removes a group from this track
-     * @param group the group to remove
-     * @throws ObjectLacksException if the group is not on this track
-     */
-    void removeGroup(Group group) throws ObjectLacksException;
-
-    /**
-     * Removes a group from this track
-     * @param group the group to remove
-     * @throws ObjectLacksException if the group is not on this track
-     */
-    void removeGroup(String group) throws ObjectLacksException;
-
-    /**
-     * Checks if a group features on this track
-     * @param group the group to check
-     * @return true if the group is on this track
-     */
-    boolean containsGroup(Group group);
-
-    /**
-     * Checks if a group features on this track
-     * @param group the group to check
-     * @return true if the group is on this track
-     */
-    boolean containsGroup(String group);
-
-    /**
-     * Clear all of the groups within this track
-     */
-    void clearGroups();
-
-}

api/src/main/java/me/lucko/luckperms/api/User.java

@@ -1,220 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import me.lucko.luckperms.exceptions.ObjectAlreadyHasException;
-import me.lucko.luckperms.exceptions.ObjectLacksException;
-
-import java.util.List;
-import java.util.UUID;
-
-/**
- * Wrapper interface for internal User instances
- *
- * <p> The implementations of this interface limit access to the User and add parameter checks to further prevent
- * errors and ensure all API interactions to not damage the state of the user.
- */
-@SuppressWarnings("unused")
-public interface User extends PermissionHolder {
-
-    /**
-     * @return the users Mojang assigned unique id
-     */
-    UUID getUuid();
-
-    /**
-     * @return the Users Username
-     */
-    String getName();
-
-    /**
-     * Gets the users primary group
-     * @return the users primary group
-     */
-    String getPrimaryGroup();
-
-    /**
-     * Sets a users primary group
-     * @param s the new primary group
-     * @throws ObjectAlreadyHasException if the user already has this set as their primary group
-     */
-    void setPrimaryGroup(String s) throws ObjectAlreadyHasException;
-
-    /**
-     * Refresh and re-assign the users permissions
-     */
-    void refreshPermissions();
-
-    /**
-     * Check to see if the user is a member of a group
-     * @param group The group to check membership of
-     * @return true if the user is a member of the group
-     */
-    boolean isInGroup(Group group);
-
-    /**
-     * Check to see if a user is a member of a group on a specific server
-     * @param group The group to check membership of
-     * @param server The server to check on
-     * @return true if the user is a member of the group
-     */
-    boolean isInGroup(Group group, String server);
-
-    /**
-     * Check to see if a user is a member of a group on a specific server
-     * @param group The group to check membership of
-     * @param server The server to check on
-     * @param world The world to check on
-     * @return true if the user is a member of the group
-     */
-    boolean isInGroup(Group group, String server, String world);
-
-    /**
-     * Add a user to a group
-     * @param group The group to add the user to
-     * @throws ObjectAlreadyHasException if the user is already a member of the group
-     */
-    void addGroup(Group group) throws ObjectAlreadyHasException;
-
-    /**
-     * Add a user to a group on a specific server
-     * @param group The group to add the user to
-     * @param server The server to add the group on
-     * @throws ObjectAlreadyHasException if the user is already a member of the group on that server
-     */
-    void addGroup(Group group, String server) throws ObjectAlreadyHasException;
-
-    /**
-     * Add a user to a group on a specific server
-     * @param group The group to add the user to
-     * @param server The server to add the group on
-     * @param world The world to add the group on
-     * @throws ObjectAlreadyHasException if the user is already a member of the group on that server
-     */
-    void addGroup(Group group, String server, String world) throws ObjectAlreadyHasException;
-
-    /**
-     * Add a user to a group on a specific server
-     * @param group The group to add the user to
-     * @param expireAt when the group should expire
-     * @throws ObjectAlreadyHasException if the user is already a member of the group on that server
-     */
-    void addGroup(Group group, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Add a user to a group on a specific server
-     * @param group The group to add the user to
-     * @param server The server to add the group on
-     * @param expireAt when the group should expire
-     * @throws ObjectAlreadyHasException if the user is already a member of the group on that server
-     */
-    void addGroup(Group group, String server, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Add a user to a group on a specific server
-     * @param group The group to add the user to
-     * @param server The server to add the group on
-     * @param world The world to add the group on
-     * @param expireAt when the group should expire
-     * @throws ObjectAlreadyHasException if the user is already a member of the group on that server
-     */
-    void addGroup(Group group, String server, String world, long expireAt) throws ObjectAlreadyHasException;
-
-    /**
-     * Remove the user from a group
-     * @param group the group to remove the user from
-     * @throws ObjectLacksException if the user isn't a member of the group
-     */
-    void removeGroup(Group group) throws ObjectLacksException;
-
-    /**
-     * Remove the user from a group
-     * @param group the group to remove the user from
-     * @param temporary if the group being removed is temporary
-     * @throws ObjectLacksException if the user isn't a member of the group
-     */
-    void removeGroup(Group group, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Remove the user from a group
-     * @param group The group to remove the user from
-     * @param server The server to remove the group on
-     * @throws ObjectLacksException if the user isn't a member of the group
-     */
-    void removeGroup(Group group, String server) throws ObjectLacksException;
-
-    /**
-     * Remove the user from a group
-     * @param group The group to remove the user from
-     * @param server The server to remove the group on
-     * @param world The world to remove the group on
-     * @throws ObjectLacksException if the user isn't a member of the group
-     */
-    void removeGroup(Group group, String server, String world) throws ObjectLacksException;
-
-    /**
-     * Remove the user from a group
-     * @param group The group to remove the user from
-     * @param server The server to remove the group on
-     * @param temporary if the group being removed is temporary
-     * @throws ObjectLacksException if the user isn't a member of the group
-     */
-    void removeGroup(Group group, String server, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Remove the user from a group
-     * @param group The group to remove the user from
-     * @param server The server to remove the group on
-     * @param world The world to remove the group on
-     * @param temporary if the group being removed is temporary
-     * @throws ObjectLacksException if the user isn't a member of the group
-     */
-    void removeGroup(Group group, String server, String world, boolean temporary) throws ObjectLacksException;
-
-    /**
-     * Clear all of the users permission nodes
-     */
-    void clearNodes();
-
-    /**
-     * Get a {@link List} of all of the groups the user is a member of, on all servers
-     * @return a {@link List} of group names
-     */
-    List<String> getGroupNames();
-
-    /**
-     * Get a {@link List} of the groups the user is a member of on a specific server
-     * @param server the server to check
-     * @param world the world to check
-     * @return a {@link List} of group names
-     */
-    List<String> getLocalGroups(String server, String world);
-
-    /**
-     * Get a {@link List} of the groups the user is a member of on a specific server
-     * @param server the server to check
-     * @return a {@link List} of group names
-     */
-    List<String> getLocalGroups(String server);
-
-}

api/src/main/java/me/lucko/luckperms/api/UuidCache.java

@@ -1,54 +0,0 @@
-/*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
- *
- *  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 me.lucko.luckperms.api;
-
-import java.util.UUID;
-
-/**
- * This UuidCache is a means of allowing users to have the same internal UUID across a network of offline mode servers
- * or mixed offline mode and online mode servers. Platforms running in offline mode generate a random UUID for a user when
- * they first join the server, but this UUID will then not be consistent across the network. LuckPerms will instead check
- * the datastore cache, to get a UUID for a user that is consistent across an entire network.
- *
- * <p> If you want to get a user object from the datastore using the api on a server in offline mode, you will need to use this cache,
- * OR use Datastore#getUUID, for users that are not online.
- *
- * <p> WARNING: THIS IS ONLY EFFECTIVE FOR ONLINE PLAYERS. USE THE DATASTORE METHODS FOR OFFLINE PLAYERS.
- */
-public interface UuidCache {
-
-    /**
-     * Gets a users internal "LuckPerms" UUID, from the one given by the server.
-     * @param external the UUID assigned by the server, through Player#getUniqueId or ProxiedPlayer#getUniqueId
-     * @return the corresponding internal UUID
-     */
-    UUID getUUID(UUID external);
-
-    /**
-     * Gets a users external, server assigned or Mojang assigned unique id, from the internal one used within LuckPerms.
-     * @param internal the UUID used within LuckPerms, through User#getUuid
-     * @return the corresponding external UUID
-     */
-    UUID getExternalUUID(UUID internal);
-
-}

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

@@ -0,0 +1,254 @@
+/*
+ * 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;
+
+import net.luckperms.api.actionlog.ActionLogger;
+import net.luckperms.api.context.ContextCalculator;
+import net.luckperms.api.context.ContextManager;
+import net.luckperms.api.event.EventBus;
+import net.luckperms.api.messaging.MessagingService;
+import net.luckperms.api.messenger.MessengerProvider;
+import net.luckperms.api.metastacking.MetaStackDefinition;
+import net.luckperms.api.metastacking.MetaStackElement;
+import net.luckperms.api.metastacking.MetaStackFactory;
+import net.luckperms.api.model.group.Group;
+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 java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * The LuckPerms API.
+ *
+ * <p>The API allows other plugins on the server to read and modify LuckPerms
+ * data, change behaviour of the plugin, listen to certain events, and integrate
+ * LuckPerms into other plugins and systems.</p>
+ *
+ * <p>This interface represents the base of the API package. All functions are
+ * accessed via this interface.</p>
+ *
+ * <p>To start using the API, you need to obtain an instance of this interface.
+ * These are registered by the LuckPerms plugin to the platforms Services
+ * Manager. This is the preferred method for obtaining an instance.</p>
+ *
+ * <p>For ease of use, and for platforms without a Service Manager, an instance
+ * can also be obtained from the static singleton accessor in
+ * {@link LuckPermsProvider}.</p>
+ */
+public interface LuckPerms {
+
+    /**
+     * Gets the name of this server.
+     *
+     * <p>This is defined in the LuckPerms configuration file, and is used for
+     * server specific permission handling.</p>
+     *
+     * <p>The default server name is "global".</p>
+     *
+     * @return the server name
+     */
+    @NonNull String getServerName();
+
+    /**
+     * Gets the {@link UserManager}, responsible for managing
+     * {@link User} instances.
+     *
+     * <p>This manager can be used to retrieve instances of {@link User} by uuid
+     * or name, or query all loaded users.</p>
+     *
+     * @return the user manager
+     */
+    @NonNull UserManager getUserManager();
+
+    /**
+     * Gets the {@link GroupManager}, responsible for managing
+     * {@link Group} instances.
+     *
+     * <p>This manager can be used to retrieve instances of {@link Group} by
+     * name, or query all loaded groups.</p>
+     *
+     * @return the group manager
+     */
+    @NonNull GroupManager getGroupManager();
+
+    /**
+     * Gets the {@link TrackManager}, responsible for managing
+     * {@link Track} instances.
+     *
+     * <p>This manager can be used to retrieve instances of {@link Track} by
+     * name, or query all loaded tracks.</p>
+     *
+     * @return the track manager
+     */
+    @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 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.
+     *
+     * @return the platform
+     */
+    @NonNull Platform getPlatform();
+
+    /**
+     * Gets the {@link PluginMetadata}, responsible for providing metadata about
+     * the LuckPerms plugin currently running.
+     *
+     * @return the plugin metadata
+     */
+    @NonNull PluginMetadata getPluginMetadata();
+
+    /**
+     * Gets the {@link EventBus}, used for subscribing to internal LuckPerms
+     * events.
+     *
+     * @return the event bus
+     */
+    @NonNull EventBus getEventBus();
+
+    /**
+     * Gets the {@link MessagingService}, used to dispatch updates throughout a
+     * network of servers running the plugin.
+     *
+     * <p>Not all instances of LuckPerms will have a messaging service setup and
+     * configured.</p>
+     *
+     * @return the messaging service instance, if present.
+     */
+    @NonNull Optional<MessagingService> getMessagingService();
+
+    /**
+     * Gets the {@link ActionLogger}, responsible for saving and broadcasting
+     * defined actions occurring on the platform.
+     *
+     * @return the action logger
+     */
+    @NonNull ActionLogger getActionLogger();
+
+    /**
+     * Gets the {@link ContextManager}, responsible for managing
+     * {@link ContextCalculator}s, and calculating applicable contexts.
+     *
+     * @return the context manager
+     */
+    @NonNull ContextManager getContextManager();
+
+    /**
+     * Gets the {@link NodeBuilderRegistry}.
+     *
+     * @return the node builder registry
+     */
+    @NonNull NodeBuilderRegistry getNodeBuilderRegistry();
+
+    /**
+     * Gets the {@link QueryOptionsRegistry}.
+     *
+     * @return the query options registry
+     * @since 5.1
+     */
+    @NonNull QueryOptionsRegistry getQueryOptionsRegistry();
+
+    /**
+     * Gets the {@link MetaStackFactory}.
+     *
+     * <p>The metastack factory provides methods for retrieving
+     * {@link MetaStackElement}s and constructing
+     * {@link MetaStackDefinition}s.</p>
+     *
+     * @return the meta stack factory
+     */
+    @NonNull MetaStackFactory getMetaStackFactory();
+
+    /**
+     * Gets the {@link NodeMatcherFactory}.
+     *
+     * @return the node matcher factory
+     * @since 5.1
+     */
+    @NonNull NodeMatcherFactory getNodeMatcherFactory();
+
+    /**
+     * Schedules the execution of an update task, and returns an encapsulation
+     * of the task as a {@link CompletableFuture}.
+     *
+     * <p>The exact actions performed in an update task remains an
+     * implementation detail of the plugin, however, as a minimum, it is
+     * expected to perform a full reload of user, group and track data, and
+     * ensure that any changes are fully applied and propagated.</p>
+     *
+     * @return a future
+     */
+    @NonNull CompletableFuture<Void> runUpdateTask();
+
+    /**
+     * Registers a {@link MessengerProvider} for use by the platform.
+     *
+     * <p>Note that the mere action of registering a provider doesn't
+     * necessarily mean that it will be used.</p>
+     *
+     * @param messengerProvider the messenger provider.
+     */
+    void registerMessengerProvider(@NonNull MessengerProvider messengerProvider);
+
+}

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

@@ -1,5 +1,8 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+ * 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
@@ -20,48 +23,44 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms;
+package net.luckperms.api;
 
-import me.lucko.luckperms.api.LuckPermsApi;
-
-import java.util.Optional;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * Static access to LuckPerms
+ * Provides static access to the {@link LuckPerms} service.
+ *
+ * <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>
  */
-public final class LuckPerms {
-    private static LuckPermsApi api = null;
+public final class LuckPermsProvider {
+    private static LuckPerms instance = null;
 
     /**
-     * Gets an instance of {@link LuckPermsApi}
+     * Gets an instance of the {@link LuckPerms} service,
+     * throwing {@link IllegalStateException} if an instance is not yet loaded.
+     *
+     * <p>Will never return null.</p>
+     *
      * @return an api instance
      * @throws IllegalStateException if the api is not loaded
      */
-    public static LuckPermsApi getApi() {
-        if (api == null) {
-            throw new IllegalStateException("API is not loaded.");
+    public static @NonNull LuckPerms get() {
+        if (instance == null) {
+            throw new IllegalStateException("The LuckPerms API is not loaded.");
         }
-        return api;
+        return instance;
     }
 
-    /**
-     * Gets an instance of {@link LuckPermsApi} safely. Unlike {@link LuckPerms#getApi}, this method will not throw an
-     * {@link IllegalStateException} if the api is not loaded, rather return an empty {@link Optional}.
-     * @return an optional api instance
-     */
-    public static Optional<LuckPermsApi> getApiSafe() {
-        return Optional.ofNullable(api);
+    static void register(LuckPerms instance) {
+        LuckPermsProvider.instance = instance;
     }
 
-    static void registerProvider(LuckPermsApi luckPermsApi) {
-        api = luckPermsApi;
+    static void unregister() {
+        LuckPermsProvider.instance = null;
     }
 
-    static void unregisterProvider() {
-        api = null;
-    }
-
-    private LuckPerms() {
+    private LuckPermsProvider() {
         throw new UnsupportedOperationException("This class cannot be instantiated.");
     }
 

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

@@ -0,0 +1,208 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.actionlog;
+
+import net.luckperms.api.LuckPermsProvider;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.time.Instant;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Represents a logged action.
+ */
+public interface Action extends Comparable<Action> {
+
+    /**
+     * Gets a {@link Action.Builder}
+     *
+     * @return a new builder
+     */
+    static @NonNull Builder builder() {
+        return LuckPermsProvider.get().getActionLogger().actionBuilder();
+    }
+
+    /**
+     * Gets the time when the action occurred.
+     *
+     * @return the timestamp
+     */
+    @NonNull Instant getTimestamp();
+
+    /**
+     * Gets the source of the action.
+     *
+     * @return the source
+     */
+    @NonNull Source getSource();
+
+    /**
+     * Gets the target of the action.
+     *
+     * @return the target
+     */
+    @NonNull Target getTarget();
+
+    /**
+     * Returns a string describing the action which took place.
+     *
+     * <p>In most instances, this returns a variation of the command string which caused
+     * the change.</p>
+     *
+     * @return the action
+     */
+    @NonNull String getDescription();
+
+    /**
+     * Represents the source of an action.
+     */
+    interface Source {
+
+        /**
+         * Gets the source unique id.
+         *
+         * @return the source unique id
+         */
+        @NonNull UUID getUniqueId();
+
+        /**
+         * Gets the source name.
+         *
+         * @return the source name
+         */
+        @NonNull String getName();
+
+    }
+
+    /**
+     * Represents the target of an action.
+     */
+    interface Target {
+
+        /**
+         * Gets the target unique id.
+         *
+         * @return the target unique id
+         */
+        @NonNull Optional<UUID> getUniqueId();
+
+        /**
+         * Gets the target name.
+         *
+         * @return the target name
+         */
+        @NonNull String getName();
+
+        /**
+         * Gets the target type.
+         *
+         * @return the target type
+         */
+        @NonNull Type getType();
+
+        /**
+         * Represents the type of a {@link Target}.
+         */
+        enum Type {
+            USER, GROUP, TRACK
+        }
+    }
+
+    /**
+     * Builds an {@link Action} instance
+     */
+    interface Builder {
+
+        /**
+         * Sets the timestamp of the entry.
+         *
+         * @param timestamp the timestamp
+         * @return the builder
+         * @see Action#getTimestamp()
+         */
+        @NonNull Builder timestamp(@NonNull Instant timestamp);
+
+        /**
+         * Sets the actor of the entry.
+         *
+         * @param actor the actor
+         * @return the builder
+         */
+        @NonNull Builder source(@NonNull UUID actor);
+
+        /**
+         * Sets the actor name of the entry.
+         *
+         * @param actorName the actor name
+         * @return the builder
+         */
+        @NonNull Builder sourceName(@NonNull String actorName);
+
+        /**
+         * Sets the type of the entry.
+         *
+         * @param type the type
+         * @return the builder
+         */
+        @NonNull Builder targetType(Action.Target.Type type);
+
+        /**
+         * Sets the acted object for the entry.
+         *
+         * @param acted the acted object
+         * @return the builder
+         */
+        @NonNull Builder target(@Nullable UUID acted);
+
+        /**
+         * Sets the acted name for the entry.
+         *
+         * @param actedName the acted name
+         * @return the builder
+         */
+        @NonNull Builder targetName(@NonNull String actedName);
+
+        /**
+         * Sets the action of the entry.
+         *
+         * @param action the action
+         * @return the builder
+         */
+        @NonNull Builder description(@NonNull String action);
+
+        /**
+         * Creates a {@link Action} instance from the builder.
+         *
+         * @return a new log entry instance
+         */
+        @NonNull Action build();
+
+    }
+
+}

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

@@ -0,0 +1,84 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.actionlog;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.SortedSet;
+import java.util.UUID;
+
+/**
+ * Represents the internal LuckPerms log.
+ *
+ * <p>The returned instance provides a copy of the data at the time of retrieval.</p>
+ *
+ * <p>Any changes made to log entries will only apply to this instance of the log.
+ * You can add to the log using the {@link ActionLogger}, and then request an updated copy.</p>
+ *
+ * <p>All methods are thread safe, and return immutable and thread safe collections.</p>
+ */
+public interface ActionLog {
+
+    /**
+     * Gets the {@link Action}s that make up this log.
+     *
+     * @return the content
+     */
+    @NonNull SortedSet<Action> getContent();
+
+    /**
+     * Gets the entries in the log performed by the given actor.
+     *
+     * @param actor the uuid of the actor to filter by
+     * @return the content for the given actor
+     */
+    @NonNull SortedSet<Action> getContent(@NonNull UUID actor);
+
+    /**
+     * Gets the log content for a given user
+     *
+     * @param uniqueId the uuid to filter by
+     * @return all content in this log where the user = uuid
+     */
+    @NonNull SortedSet<Action> getUserHistory(@NonNull UUID uniqueId);
+
+    /**
+     * Gets the log content for a given group
+     *
+     * @param name the name to filter by
+     * @return all content in this log where the group = name
+     */
+    @NonNull SortedSet<Action> getGroupHistory(@NonNull String name);
+
+    /**
+     * Gets the log content for a given track
+     *
+     * @param name the name to filter by
+     * @return all content in this log where the track = name
+     */
+    @NonNull SortedSet<Action> getTrackHistory(@NonNull String name);
+
+}

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

@@ -0,0 +1,90 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.actionlog;
+
+import net.luckperms.api.messaging.MessagingService;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Represents the object responsible for handling action logging.
+ */
+public interface ActionLogger {
+
+    /**
+     * Returns a new {@link Action.Builder} instance
+     *
+     * @return a new builder
+     */
+    Action.@NonNull Builder actionBuilder();
+
+    /**
+     * Gets a {@link ActionLog} instance from the plugin storage.
+     *
+     * @return a log instance
+     */
+    @NonNull CompletableFuture<ActionLog> getLog();
+
+    /**
+     * Submits a log entry to the plugin to be handled.
+     *
+     * <p>This method submits the log to the storage provider and broadcasts
+     * it.</p>
+     *
+     * <p>It is therefore roughly equivalent to calling
+     * {@link #submitToStorage(Action)} and {@link #broadcastAction(Action)},
+     * however, using this method is preferred to making the calls individually.</p>
+     *
+     * <p>If you want to submit a log entry but don't know which method to pick,
+     * use this one.</p>
+     *
+     * @param entry the entry to submit
+     * @return a future which will complete when the action is done
+     */
+    @NonNull CompletableFuture<Void> submit(@NonNull Action entry);
+
+    /**
+     * Submits a log entry to the plugins storage handler.
+     *
+     * @param entry the entry to submit
+     * @return a future which will complete when the action is done
+     */
+    @NonNull CompletableFuture<Void> submitToStorage(@NonNull Action entry);
+
+    /**
+     * Submits a log entry to the plugins log broadcasting handler.
+     *
+     * <p>If enabled, this method will also dispatch the log entry via the
+     * plugins {@link MessagingService}.</p>
+     *
+     * @param entry the entry to submit
+     * @return a future which will complete when the action is done
+     */
+    @NonNull CompletableFuture<Void> broadcastAction(@NonNull Action entry);
+
+}

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

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

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

@@ -0,0 +1,250 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.cacheddata;
+
+import net.luckperms.api.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;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Holds cached permission and meta lookup data for a {@link PermissionHolder}.
+ *
+ * <p>All calls will account for inheritance, as well as any default data
+ * provided by the platform. This calls are heavily cached and are therefore
+ * fast.</p>
+ */
+public interface CachedDataManager {
+
+    /**
+     * Gets the manager for {@link CachedPermissionData}.
+     *
+     * @return the permission data manager
+     */
+    @NonNull Container<CachedPermissionData> permissionData();
+
+    /**
+     * Gets the manager for {@link CachedMetaData}.
+     *
+     * @return the meta data manager
+     */
+    @NonNull Container<CachedMetaData> metaData();
+
+    /**
+     * Gets PermissionData from the cache, using the given query options.
+     *
+     * @param queryOptions the query options
+     * @return a permission data instance
+     */
+    @NonNull CachedPermissionData getPermissionData(@NonNull QueryOptions queryOptions);
+
+    /**
+     * Gets MetaData from the cache, using the given query options.
+     *
+     * @param queryOptions the query options
+     * @return a meta data instance
+     */
+    @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.
+     */
+    void invalidate();
+
+    /**
+     * Invalidates all of the underlying Permission calculators.
+     *
+     * <p>Can be called to allow for an update in defaults.</p>
+     */
+    void invalidatePermissionCalculators();
+
+    /**
+     * Manages a specific type of {@link CachedData cached data} within
+     * a {@link CachedDataManager} instance.
+     *
+     * @param <T> the data type
+     */
+    interface Container<T extends CachedData> {
+
+        /**
+         * Gets {@link T data} from the cache.
+         *
+         * @param queryOptions the query options
+         * @return a data instance
+         * @throws NullPointerException if contexts is null
+         */
+        @NonNull T get(@NonNull QueryOptions queryOptions);
+
+        /**
+         * Calculates {@link T data}, bypassing the cache.
+         *
+         * <p>The result of this operation is calculated each time the method is called.
+         * The result is not added to the internal cache.</p>
+         *
+         * <p>It is therefore highly recommended to use {@link #get(QueryOptions)} instead.</p>
+         *
+         * <p>The use cases of this method are more around constructing one-time
+         * instances of {@link T data}, without adding the result to the cache.</p>
+         *
+         * @param queryOptions the query options
+         * @return a data instance
+         * @throws NullPointerException if contexts is null
+         */
+        @NonNull T calculate(@NonNull QueryOptions queryOptions);
+
+        /**
+         * (Re)calculates data for a given context.
+         *
+         * <p>This method returns immediately in all cases. The (re)calculation is
+         * performed asynchronously and applied to the cache in the background.</p>
+         *
+         * <p>If there was a previous data instance associated with
+         * the given {@link QueryOptions}, then that instance will continue to be returned by
+         * {@link #get(QueryOptions)} until the recalculation is completed.</p>
+         *
+         * <p>If there was no value calculated and cached prior to the call of this
+         * method, then one will be calculated.</p>
+         *
+         * @param queryOptions the query options
+         * @throws NullPointerException if contexts is null
+         */
+        void recalculate(@NonNull QueryOptions queryOptions);
+
+        /**
+         * (Re)loads permission data for a given context.
+         *
+         * <p>Unlike {@link #recalculate(QueryOptions)}, this method immediately
+         * invalidates any previous data values contained within the cache,
+         * and then schedules a task to reload a new data instance to
+         * replace the one which was invalidated.</p>
+         *
+         * <p>The invalidation happens immediately during the execution of this method.
+         * The result of the re-computation encapsulated by the future.</p>
+         *
+         * <p>Subsequent calls to {@link #get(QueryOptions)} will block until
+         * the result of this operation is complete.</p>
+         *
+         * <p>If there was no value calculated and cached prior to the call of this
+         * method, then one will be calculated.</p>
+         *
+         * <p>This method returns a Future so users can optionally choose to wait
+         * until the recalculation has been performed.</p>
+         *
+         * @param queryOptions the query options.
+         * @return a future
+         * @throws NullPointerException if contexts is null
+         */
+        @NonNull CompletableFuture<? extends T> reload(@NonNull QueryOptions queryOptions);
+
+        /**
+         * Recalculates data for all known contexts.
+         *
+         * <p>This method returns immediately. The recalculation is performed
+         * asynchronously and applied to the cache in the background.</p>
+         *
+         * <p>The previous data instances will continue to be returned
+         * by {@link #get(QueryOptions)} until the recalculation is completed.</p>
+         */
+        void recalculate();
+
+        /**
+         * Reloads permission data for all known contexts.
+         *
+         * <p>Unlike {@link #recalculate()}, this method immediately
+         * invalidates all previous data values contained within the cache,
+         * and then schedules a task to reload new data instances to
+         * replace the ones which were invalidated.</p>
+         *
+         * <p>The invalidation happens immediately during the execution of this method.
+         * The result of the re-computation encapsulated by the future.</p>
+         *
+         * <p>Subsequent calls to {@link #get(QueryOptions)} will block until
+         * the result of this operation is complete.</p>
+         *
+         * <p>This method returns a Future so users can optionally choose to wait
+         * until the recalculation has been performed.</p>
+         *
+         * @return a future
+         */
+        @NonNull CompletableFuture<Void> reload();
+
+        /**
+         * Invalidates any cached data instances mapped to the given context.
+         *
+         * @param queryOptions the queryOptions to invalidate for
+         */
+        void invalidate(@NonNull QueryOptions queryOptions);
+
+        /**
+         * Invalidates all cached data instances.
+         */
+        void invalidate();
+    }
+
+}

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

@@ -0,0 +1,111 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.cacheddata;
+
+import net.luckperms.api.metastacking.MetaStackDefinition;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.List;
+import java.util.Map;
+import java.util.SortedMap;
+
+/**
+ * Holds cached meta lookup data for a specific set of contexts.
+ */
+public interface CachedMetaData extends CachedData {
+
+    /**
+     * Gets a value for the given meta key.
+     *
+     * @param key the key
+     * @return the value
+     */
+    @Nullable String getMetaValue(String key);
+
+    /**
+     * 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 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 holder has.
+     *
+     * @return an immutable map of meta
+     */
+    @NonNull Map<String, List<String>> getMeta();
+
+    /**
+     * 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();
+
+    /**
+     * 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();
+
+    /**
+     * 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
+     *
+     * @return the definition used for the prefix stack
+     */
+    @NonNull MetaStackDefinition getPrefixStackDefinition();
+
+    /**
+     * Gets the definition used for the suffix stack
+     *
+     * @return the definition used for the suffix stack
+     */
+    @NonNull MetaStackDefinition getSuffixStackDefinition();
+
+}

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

@@ -0,0 +1,62 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.cacheddata;
+
+import net.luckperms.api.util.Tristate;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Map;
+
+/**
+ * Holds cached permission lookup data for a specific set of contexts.
+ */
+public interface CachedPermissionData extends CachedData {
+
+    /**
+     * Gets a permission check result for the given permission node.
+     *
+     * @param permission the permission node
+     * @return a tristate result
+     * @throws NullPointerException if permission is null
+     */
+    @NonNull Tristate checkPermission(@NonNull String permission);
+
+    /**
+     * Invalidates the underlying permission calculator cache.
+     *
+     * <p>Can be called to allow for an update in defaults.</p>
+     */
+    void invalidateCache();
+
+    /**
+     * Gets an immutable copy of the permission map backing the permission calculator
+     *
+     * @return an immutable set of permissions
+     */
+    @NonNull Map<String, Boolean> getPermissionMap();
+
+}

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

@@ -0,0 +1,99 @@
+/*
+ * 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 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>
+ */
+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.
+     *
+     * @return the key
+     */
+    @NonNull String getKey();
+
+    /**
+     * Gets the context value
+     *
+     * @return the value
+     */
+    @NonNull String getValue();
+
+}

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

@@ -0,0 +1,110 @@
+/*
+ * 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 org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Objects;
+import java.util.function.Function;
+
+/**
+ * Calculates the contexts applicable for a contextual subject.
+ *
+ * <p>Implementations of this interface should satisfy the following
+ * requirements:</p>
+ * <ul>
+ *     <li>Context lookups should be <i>fast</i>: lookup methods are likely to
+ *     be invoked frequently, and should therefore be fast to execute. If
+ *     determining the current contexts involves a particularly time consuming
+ *     lookup (database queries, network requests, etc), then such results
+ *     should be cached ahead of time.</li>
+ *
+ *     <li>Context lookups should be <i>thread-safe</i>: lookups will sometimes
+ *     be performed from "async" threads, and therefore should not access any
+ *     part of the server only safe for access from a sync context. If
+ *     necessary, such results should be determined ahead of time and stored in
+ *     a thread-safe collection for retrieval later.</li>
+ *
+ *     <li>Context lookups should <i>not query active contexts</i>: doing so is
+ *     likely to result in a stack overflow, or thread deadlock. Care should be
+ *     taken to avoid (indirect) calls to the same calculator.</li>
+ * </ul>
+ * <p></p>
+ *
+ * <p>Calculators should be registered using
+ * {@link ContextManager#registerCalculator(ContextCalculator)}.</p>
+ */
+@FunctionalInterface
+public interface ContextCalculator<T> {
+
+    /**
+     * Creates a new {@link ContextCalculator} that provides a single context.
+     *
+     * @param key the key of the context provided by the calculator
+     * @param valueFunction the function used to compute the corresponding value
+     *                      for each query. A context will not be "accumulated"
+     *                      if the value returned is null.
+     * @param <T> the contextual type
+     * @return the resultant calculator
+     */
+    static <T> @NonNull ContextCalculator<T> forSingleContext(@NonNull String key, @NonNull Function<T, String> valueFunction) {
+        Objects.requireNonNull(key, "key");
+        Objects.requireNonNull(valueFunction, "valueFunction");
+        return (target, consumer) -> {
+            String value = valueFunction.apply(target);
+            if (value != null) {
+                consumer.accept(key, value);
+            }
+        };
+    }
+
+    /**
+     * Submits any contexts this calculator determines to be applicable to
+     * the {@code target} contextual subject.
+     *
+     * <p>Care should be taken to ensure implementations of this method meet the
+     * general requirements for {@link ContextCalculator}, defined in the class
+     * doc.</p>
+     *
+     * @param target the target contextual subject for this operation
+     * @param consumer the {@link ContextConsumer} to submit contexts to
+     */
+    void calculate(@NonNull T target, @NonNull ContextConsumer consumer);
+
+    /**
+     * Gets a {@link ContextSet}, containing some/all of the contexts this
+     * calculator could potentially submit.
+     *
+     * <p>The result of this call is primarily intended on providing
+     * suggestions to end users when defining permissions.</p>
+     *
+     * @return a set of potential contexts
+     */
+    default ContextSet estimatePotentialContexts() {
+        return ImmutableContextSet.empty();
+    }
+
+}

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

@@ -1,5 +1,8 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+ * 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
@@ -20,38 +23,42 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.tracks;
+package net.luckperms.api.context;
 
-import me.lucko.luckperms.utils.AbstractManager;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import java.util.Set;
-import java.util.stream.Collectors;
-
-public class TrackManager extends AbstractManager<String, Track> {
+/**
+ * Functional interface that accepts context key value pairs.
+ */
+@FunctionalInterface
+public interface ContextConsumer {
 
     /**
-     * Returns a set of tracks that contain at least one of the groups from the Set provided
-     * @param group the group to filter by
-     * @return a set of tracks that the groups could be a member of
+     * Accepts a context pair.
+     *
+     * @param key the key
+     * @param value the value
      */
-    public Set<Track> getApplicableTracks(String group) {
-        return objects.values().stream()
-                .filter(t -> t.containsGroup(group))
-                .collect(Collectors.toSet());
-    }
+    void accept(@NonNull String key, @NonNull String value);
 
-    @Override
-    protected void copy(Track from, Track to) {
-        to.setGroups(from.getGroups());
+    /**
+     * Accepts a context pair.
+     *
+     * @param context the context
+     */
+    default void accept(@NonNull Context context) {
+        accept(context.getKey(), context.getValue());
     }
 
     /**
-     * Makes a new track object
-     * @param name The name of the track
-     * @return a new {@link Track} object
+     * Accepts a context set.
+     *
+     * @param contextSet the context set
      */
-    @Override
-    public Track make(String name) {
-        return new Track(name);
+    default void accept(@NonNull ContextSet contextSet) {
+        for (Context entry : contextSet) {
+            accept(entry);
+        }
     }
+
 }

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

@@ -0,0 +1,156 @@
+/*
+ * 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.model.user.User;
+import net.luckperms.api.query.QueryMode;
+import net.luckperms.api.query.QueryOptions;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Optional;
+
+/**
+ * Manages {@link ContextCalculator}s, and calculates applicable contexts for a
+ * given type.
+ *
+ * <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.</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.service.permission.Subject}</li>
+ * <li>{@code cn.nukkit.Player}</li>
+ * <li>{@code com.velocitypowered.api.proxy.Player}</li>
+ * </ul>
+ */
+public interface ContextManager {
+
+    /**
+     * Queries the ContextManager for current context values for the subject.
+     *
+     * @param subject the subject
+     * @return the applicable context for the subject
+     */
+    @NonNull ImmutableContextSet getContext(@NonNull Object subject);
+
+    /**
+     * Queries the ContextManager for current context values for the given User.
+     *
+     * <p>This will only return a value if the player corresponding to the
+     * {@link User} is online.</p>
+     *
+     * <p>If you need to obtain a {@link ImmutableContextSet} instance
+     * regardless, you should initially try this method, and then fallback on
+     * {@link #getStaticContext()}.</p>
+     *
+     * @param user the user
+     * @return the applicable context for the subject
+     */
+    @NonNull Optional<ImmutableContextSet> getContext(@NonNull User user);
+
+    /**
+     * Gets the contexts from the static calculators in this manager.
+     *
+     * <p>Static calculators provide the same context for all subjects, and are
+     * marked as such when registered.</p>
+     *
+     * @return the current active static contexts
+     */
+    @NonNull ImmutableContextSet getStaticContext();
+
+    /**
+     * Creates a new {@link QueryOptions.Builder}.
+     *
+     * @param mode the mode
+     * @return a new query options builder
+     */
+    QueryOptions.@NonNull Builder queryOptionsBuilder(@NonNull QueryMode mode);
+
+    /**
+     * Obtains current {@link QueryOptions} for the subject.
+     *
+     * @param subject the subject
+     * @return the query options for the subject
+     */
+    @NonNull QueryOptions getQueryOptions(@NonNull Object subject);
+
+    /**
+     * Obtains current {@link QueryOptions} for the given User.
+     *
+     * <p>This will only return a value if the player corresponding to the
+     * {@link User} is online.</p>
+     *
+     * <p>If you need to obtain a {@link QueryOptions} instance regardless, you should
+     * initially try this method, and then fallback on {@link #getStaticQueryOptions()}.</p>
+     *
+     * @param user the user
+     * @return the query options for the subject
+     */
+    @NonNull Optional<QueryOptions> getQueryOptions(@NonNull User user);
+
+    /**
+     * Gets the static query options, using the registered static context calculators.
+     *
+     * @return the current static query options
+     */
+    @NonNull QueryOptions getStaticQueryOptions();
+
+    /**
+     * Registers a context calculator with the manager.
+     *
+     * @param calculator the calculator
+     */
+    void registerCalculator(@NonNull ContextCalculator<?> calculator);
+
+    /**
+     * Unregisters a context calculator with the manager.
+     *
+     * @param calculator the calculator
+     */
+    void unregisterCalculator(@NonNull ContextCalculator<?> calculator);
+
+    /**
+     * Gets the {@link ContextSetFactory}, responsible for creating
+     * {@link ContextSet} instances.
+     *
+     * @return the context set factory
+     */
+    @NonNull ContextSetFactory getContextSetFactory();
+
+    /**
+     * Invalidates the lookup cache for a given subject
+     *
+     * @param subject the subject
+     */
+    void invalidateCache(@NonNull Object subject);
+
+}

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

@@ -0,0 +1,226 @@
+/*
+ * 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 org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+
+/**
+ * A set of contexts.
+ *
+ * <p>Context in the most basic sense simply means the circumstances where
+ * 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>
+ *
+ * <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>
+ */
+public interface ContextSet extends Iterable<Context> {
+
+    /**
+     * Gets if this {@link ContextSet} is immutable.
+     *
+     * <p>The state of immutable instances will never change.</p>
+     *
+     * @return true if the set is immutable
+     */
+    boolean isImmutable();
+
+    /**
+     * Returns an immutable representation of this {@link ContextSet}.
+     *
+     * <p>If the set is already immutable, the same object will be returned.
+     * If the set is mutable, an immutable copy will be made.</p>
+     *
+     * @return an immutable representation of this set
+     */
+    @NonNull ImmutableContextSet immutableCopy();
+
+    /**
+     * Creates a mutable copy of this {@link ContextSet}.
+     *
+     * <p>A new copy is returned regardless of the
+     * {@link #isImmutable() mutability} of this set.</p>
+     *
+     * @return a mutable ContextSet
+     */
+    @NonNull MutableContextSet mutableCopy();
+
+    /**
+     * Returns a {@link Set} of {@link Context}s representing the current
+     * state of this {@link ContextSet}.
+     *
+     * <p>The returned set is immutable, and is a copy of the current set.
+     * (will not update live)</p>
+     *
+     * @return an immutable set
+     */
+    @NonNull Set<Context> toSet();
+
+    /**
+     * Returns a {@link Map} representing the current state of this
+     * {@link ContextSet}.
+     *
+     * <p>The returned set is immutable, and is a copy of the current set.
+     * (will not update live)</p>
+     *
+     * @return a map
+     */
+    @NonNull Map<String, Set<String>> toMap();
+
+    /**
+     * Returns a {@link Map} <b>loosely</b> representing the current state of
+     * this {@link ContextSet}.
+     *
+     * <p>The returned map is immutable, and is a copy of the current set.
+     * (will not update live)</p>
+     *
+     * <p>As a single context key can be mapped to multiple values, this method
+     * 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
+    @NonNull Map<String, String> toFlattenedMap();
+
+    /**
+     * Returns an {@link Iterator} over each of the context pairs in this set.
+     *
+     * <p>The returned iterator represents the state of the set at the time of creation. It is not
+     * updated as the set changes.</p>
+     *
+     * <p>The iterator does not support {@link Iterator#remove()} calls.</p>
+     *
+     * @return an iterator
+     */
+    @Override
+    @NonNull Iterator<Context> iterator();
+
+    /**
+     * Returns if the {@link ContextSet} contains at least one value for the
+     * given key.
+     *
+     * @param key the key to check for
+     * @return true if the set contains a value for the key
+     * @throws NullPointerException if the key is null
+     */
+    boolean containsKey(@NonNull String key);
+
+    /**
+     * Returns a {@link Set} of the values mapped to the given key.
+     *
+     * <p>The returned set is immutable, and only represents the current state
+     * of the {@link ContextSet}. (will not update live)</p>
+     *
+     * @param key the key to get values for
+     * @return a set of values
+     * @throws NullPointerException if the key is null
+     */
+    @NonNull Set<String> getValues(@NonNull String key);
+
+    /**
+     * Returns any value from this {@link ContextSet} matching the key, if present.
+     *
+     * <p>Note that context keys can be mapped to multiple values.
+     * Use {@link #getValues(String)} to retrieve all associated values.</p>
+     *
+     * @param key the key to find values for
+     * @return an optional containing any match
+     */
+    default @NonNull Optional<String> getAnyValue(@NonNull String key) {
+        return getValues(key).stream().findAny();
+    }
+
+    /**
+     * Returns if the {@link ContextSet} contains a given context pairing.
+     *
+     * @param key   the key to look for
+     * @param value the value to look for
+     * @return true if the set contains the context pair
+     * @throws NullPointerException if the key or value is null
+     */
+    boolean contains(@NonNull String key, @NonNull String value);
+
+    /**
+     * Returns if the {@link ContextSet} contains a given context pairing.
+     *
+     * @param entry the entry to look for
+     * @return true if the set contains the context pair
+     * @throws NullPointerException if the key or value is null
+     */
+    default boolean contains(@NonNull Context entry) {
+        Objects.requireNonNull(entry, "entry");
+        return contains(entry.getKey(), entry.getValue());
+    }
+
+    /**
+     * Returns if this {@link ContextSet} is fully "satisfied" by another set.
+     *
+     * <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
+     */
+    boolean isSatisfiedBy(@NonNull ContextSet other);
+
+    /**
+     * Returns if the {@link ContextSet} is empty.
+     *
+     * @return true if the set is empty
+     */
+    boolean isEmpty();
+
+    /**
+     * Gets the number of context pairs in the {@link ContextSet}.
+     *
+     * @return the size of the set
+     */
+    int size();
+
+}

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

@@ -0,0 +1,43 @@
+/*
+ * 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 org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * A factory for creating {@link ContextSet}s.
+ */
+public interface ContextSetFactory {
+
+    ImmutableContextSet.@NonNull Builder immutableBuilder();
+
+    @NonNull ImmutableContextSet immutableOf(@NonNull String key, @NonNull String value);
+
+    @NonNull ImmutableContextSet immutableEmpty();
+
+    @NonNull MutableContextSet mutable();
+
+}

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

@@ -0,0 +1,46 @@
+/*
+ * 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;
+
+/**
+ * Some default context keys used by the plugin.
+ */
+public final class DefaultContextKeys {
+    private DefaultContextKeys() {
+        throw new AssertionError();
+    }
+
+    /**
+     * The context key used to denote the subjects server.
+     */
+    public static final String SERVER_KEY = "server";
+
+    /**
+     * The context key used to denote the subjects world.
+     */
+    public static final String WORLD_KEY = "world";
+
+}

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

@@ -0,0 +1,139 @@
+/*
+ * 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.LuckPermsProvider;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Objects;
+
+/**
+ * An immutable implementation of {@link ContextSet}.
+ */
+public interface ImmutableContextSet extends ContextSet {
+
+    /**
+     * Creates an {@link ImmutableContextSet.Builder}.
+     *
+     * @return a new ImmutableContextSet builder
+     */
+    static @NonNull Builder builder() {
+        return LuckPermsProvider.get().getContextManager().getContextSetFactory().immutableBuilder();
+    }
+
+    /**
+     * Returns an empty {@link ImmutableContextSet}.
+     *
+     * @return an empty ImmutableContextSet
+     */
+    static @NonNull ImmutableContextSet empty() {
+        return LuckPermsProvider.get().getContextManager().getContextSetFactory().immutableEmpty();
+    }
+
+    /**
+     * Creates an {@link ImmutableContextSet} from a context pair.
+     *
+     * @param key   the key
+     * @param value the value
+     * @return a new ImmutableContextSet containing one context pair
+     * @throws NullPointerException if key or value is null
+     */
+    static @NonNull ImmutableContextSet of(@NonNull String key, @NonNull String value) {
+        return LuckPermsProvider.get().getContextManager().getContextSetFactory().immutableOf(key, value);
+    }
+
+    /**
+     * @deprecated Already immutable!
+     */
+    @Override
+    @Deprecated
+    @NonNull ImmutableContextSet immutableCopy();
+
+    /**
+     * A builder for {@link ImmutableContextSet}.
+     */
+    interface Builder {
+
+        /**
+         * Adds a context to the set.
+         *
+         * @param key   the key to add
+         * @param value the value to add
+         * @return the builder
+         * @throws NullPointerException if the key or value is null
+         * @see MutableContextSet#add(String, String)
+         */
+        @NonNull Builder add(@NonNull String key, @NonNull String value);
+
+        /**
+         * Adds a context to the set.
+         *
+         * @param entry the entry to add
+         * @return the builder
+         * @throws NullPointerException if the entry is null
+         * @see MutableContextSet#add(Context)
+         */
+        default @NonNull Builder add(@NonNull Context entry) {
+            Objects.requireNonNull(entry, "entry");
+            add(entry.getKey(), entry.getValue());
+            return this;
+        }
+
+        /**
+         * Adds the contexts contained in the given {@link Iterable} to the set.
+         *
+         * @param iterable an iterable of key value context pairs
+         * @return the builder
+         * @throws NullPointerException if iterable is null
+         * @see MutableContextSet#addAll(Iterable)
+         */
+        default @NonNull Builder addAll(@NonNull Iterable<Context> iterable) {
+            for (Context e : Objects.requireNonNull(iterable, "iterable")) {
+                add(e);
+            }
+            return this;
+        }
+
+        /**
+         * Adds of of the contexts in another {@link ContextSet} to the set.
+         *
+         * @param contextSet the set to add from
+         * @return the builder
+         * @throws NullPointerException if the contextSet is null
+         * @see MutableContextSet#addAll(ContextSet)
+         */
+        @NonNull Builder addAll(@NonNull ContextSet contextSet);
+
+        /**
+         * Creates a {@link ImmutableContextSet} from the values previously
+         * added to the builder.
+         *
+         * @return an {@link ImmutableContextSet} from the builder
+         */
+        @NonNull ImmutableContextSet build();
+    }
+}

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

@@ -0,0 +1,126 @@
+/*
+ * 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.LuckPermsProvider;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Objects;
+
+/**
+ * A mutable implementation of {@link ContextSet}.
+ */
+public interface MutableContextSet extends ContextSet {
+
+    /**
+     * Creates a new empty MutableContextSet.
+     *
+     * @return a new MutableContextSet
+     */
+    static @NonNull MutableContextSet create() {
+        return LuckPermsProvider.get().getContextManager().getContextSetFactory().mutable();
+    }
+
+    /**
+     * Creates a {@link MutableContextSet} from a context pair.
+     *
+     * @param key   the key
+     * @param value the value
+     * @return a new MutableContextSet containing one context pair
+     * @throws NullPointerException if key or value is null
+     */
+    static @NonNull MutableContextSet of(@NonNull String key, @NonNull String value) {
+        Objects.requireNonNull(key, "key");
+        Objects.requireNonNull(value, "value");
+        MutableContextSet set = create();
+        set.add(key, value);
+        return set;
+    }
+
+    /**
+     * Adds a context to this set.
+     *
+     * @param key   the key to add
+     * @param value the value to add
+     * @throws NullPointerException if the key or value is null
+     */
+    void add(@NonNull String key, @NonNull String value);
+
+    /**
+     * Adds a context to this set.
+     *
+     * @param entry the entry to add
+     * @throws NullPointerException if the entry is null
+     */
+    default void add(@NonNull Context entry) {
+        Objects.requireNonNull(entry, "entry");
+        add(entry.getKey(), entry.getValue());
+    }
+
+    /**
+     * Adds the contexts contained in the given {@link Iterable} to this set.
+     *
+     * @param iterable an iterable of key value context pairs
+     * @throws NullPointerException if iterable is null
+     */
+    default void addAll(@NonNull Iterable<Context> iterable) {
+        for (Context e : Objects.requireNonNull(iterable, "iterable")) {
+            add(e);
+        }
+    }
+
+    /**
+     * Adds of of the contexts in another {@link ContextSet} to this set.
+     *
+     * @param contextSet the set to add from
+     * @throws NullPointerException if the contextSet is null
+     */
+    void addAll(@NonNull ContextSet contextSet);
+
+    /**
+     * Removes a context from this set.
+     *
+     * @param key   the key to remove
+     * @param value the value to remove
+     * @throws NullPointerException if the key or value is null
+     */
+    void remove(@NonNull String key, @NonNull String value);
+
+    /**
+     * Removes all contexts from this set with the given key.
+     *
+     * @param key the key to remove
+     * @throws NullPointerException if the key is null
+     */
+    void removeAll(@NonNull String key);
+
+    /**
+     * Removes all contexts from the set.
+     */
+    void clear();
+
+}

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

@@ -0,0 +1,75 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.context;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Objects;
+import java.util.function.Supplier;
+
+/**
+ * Extension of {@link ContextCalculator} which provides the same context
+ * regardless of the subject.
+ */
+@FunctionalInterface
+public interface StaticContextCalculator extends ContextCalculator<Object> {
+
+    /**
+     * Creates a new {@link StaticContextCalculator} that provides a single context.
+     *
+     * @param key the key of the context provided by the calculator
+     * @param valueFunction the function used to compute the corresponding value
+     *                      for each query. A context will not be "accumulated"
+     *                      if the value returned is null.
+     * @return the resultant calculator
+     */
+    static StaticContextCalculator forSingleContext(String key, Supplier<String> valueFunction) {
+        Objects.requireNonNull(key, "key");
+        Objects.requireNonNull(valueFunction, "valueFunction");
+        return consumer -> {
+            String value = valueFunction.get();
+            if (value != null) {
+                consumer.accept(key, value);
+            }
+        };
+    }
+
+    /**
+     * Submits any contexts this calculator determines to be applicable.
+     *
+     * <p>Care should be taken to ensure implementations of this method meet the
+     * general requirements for {@link ContextCalculator}, defined in the class
+     * doc.</p>
+     *
+     * @param consumer the {@link ContextConsumer} to submit contexts to
+     */
+    void calculate(@NonNull ContextConsumer consumer);
+
+    @Override
+    default void calculate(@NonNull Object target, @NonNull ContextConsumer consumer) {
+        calculate(consumer);
+    }
+}

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

@@ -0,0 +1,83 @@
+/*
+ * 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;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Set;
+import java.util.function.Consumer;
+
+/**
+ * The LuckPerms event bus.
+ *
+ * <p>Used to subscribe (or "listen") to LuckPerms events.</p>
+ */
+public interface EventBus {
+
+    /**
+     * Registers a new subscription to the given event.
+     *
+     * <p>The returned {@link EventSubscription} instance encapsulates the subscription state. It has
+     * methods which can be used to terminate the subscription, or view stats about the nature of
+     * the subscription.</p>
+     *
+     * @param eventClass the event class
+     * @param handler    the event handler
+     * @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);
+
+    /**
+     * Registers a new subscription to the given event.
+     *
+     * <p>The returned {@link EventSubscription} instance encapsulates the subscription state. It has
+     * methods which can be used to terminate the subscription, or view stats about the nature of
+     * the subscription.</p>
+     *
+     * <p>Unlike {@link #subscribe(Class, Consumer)}, this method accepts an additional parameter
+     * for {@code plugin}. This object must be a "plugin" instance on the platform, and is used to
+     * automatically {@link EventSubscription#close() unregister} the subscription when the
+     * corresponding plugin is disabled.</p>
+     *
+     * @param <T>        the event class
+     * @param plugin     a plugin instance to bind the subscription to.
+     * @param eventClass the event class
+     * @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);
+
+    /**
+     * Gets a set of all registered handlers for a given event.
+     *
+     * @param eventClass the event to find handlers for
+     * @param <T>        the event class
+     * @return an immutable set of event handlers
+     */
+    @NonNull <T extends LuckPermsEvent> Set<EventSubscription<T>> getSubscriptions(@NonNull Class<T> eventClass);
+
+}

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

@@ -0,0 +1,65 @@
+/*
+ * 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;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.function.Consumer;
+
+/**
+ * Represents a subscription to a {@link LuckPermsEvent}.
+ *
+ * @param <T> the event class
+ */
+public interface EventSubscription<T extends LuckPermsEvent> extends AutoCloseable {
+
+    /**
+     * Gets the class this handler is listening to
+     *
+     * @return the event class
+     */
+    @NonNull Class<T> getEventClass();
+
+    /**
+     * Returns true if this handler is active
+     *
+     * @return true if this handler is still active
+     */
+    boolean isActive();
+
+    /**
+     * Unregisters this handler from the event bus.
+     */
+    @Override
+    void close();
+
+    /**
+     * Gets the event consumer responsible for handling the event
+     *
+     * @return the event consumer
+     */
+    @NonNull Consumer<? super T> getHandler();
+}

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

@@ -0,0 +1,51 @@
+/*
+ * 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;
+
+import net.luckperms.api.LuckPerms;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * A superinterface for all LuckPerms events.
+ */
+public interface LuckPermsEvent {
+
+    /**
+     * Get the API instance this event was dispatched from
+     *
+     * @return the api instance
+     */
+    @NonNull LuckPerms getLuckPerms();
+
+    /**
+     * Gets the type of the event.
+     *
+     * @return the type of the event
+     */
+    @NonNull Class<? extends LuckPermsEvent> getEventType();
+
+}

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

@@ -0,0 +1,53 @@
+/*
+ * 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.cause;
+
+/**
+ * The cause of a group/track creation
+ */
+public enum CreationCause {
+
+    /**
+     * The creation was caused by a command
+     */
+    COMMAND,
+
+    /**
+     * The creation was caused by the web editor
+     */
+    WEB_EDITOR,
+
+    /**
+     * The creation was caused by an API call
+     */
+    API,
+
+    /**
+     * The creation was caused by a LuckPerms internal
+     */
+    INTERNAL
+
+}

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

@@ -0,0 +1,48 @@
+/*
+ * 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.cause;
+
+/**
+ * The cause of a group/track deletion
+ */
+public enum DeletionCause {
+
+    /**
+     * The deletion was caused by a command
+     */
+    COMMAND,
+
+    /**
+     * The deletion was caused by an API call
+     */
+    API,
+
+    /**
+     * The deletion was caused by a LuckPerms internal
+     */
+    INTERNAL
+
+}

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

@@ -0,0 +1,47 @@
+/*
+ * 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.extension;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.extension.Extension;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when an {@link Extension} is loaded.
+ */
+public interface ExtensionLoadEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the extension that was loaded.
+     *
+     * @return the extension
+     */
+    @Param(0)
+    @NonNull Extension getExtension();
+
+}

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

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

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

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

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

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

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

@@ -0,0 +1,66 @@
+/*
+ * 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.group;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.cause.DeletionCause;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.node.Node;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Set;
+
+/**
+ * Called when a group is deleted
+ */
+public interface GroupDeleteEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the name of the deleted group
+     *
+     * @return the name of the deleted group
+     */
+    @Param(0)
+    @NonNull String getGroupName();
+
+    /**
+     * Gets an immutable copy of the groups existing data
+     *
+     * @return a copy of the groups existing data
+     */
+    @Param(1)
+    @NonNull Set<Node> getExistingData();
+
+    /**
+     * Gets the cause of the deletion
+     *
+     * @return the cause of the deletion
+     */
+    @Param(2)
+    @NonNull DeletionCause getCause();
+
+}

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

@@ -0,0 +1,37 @@
+/*
+ * 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.group;
+
+import net.luckperms.api.event.LuckPermsEvent;
+
+/**
+ * Called when all groups have been loaded in from storage.
+ *
+ * <p>Usually only called on startup and in sync tasks.</p>
+ */
+public interface GroupLoadAllEvent extends LuckPermsEvent {
+
+}

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

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

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

@@ -0,0 +1,77 @@
+/*
+ * 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.log;
+
+import net.luckperms.api.actionlog.Action;
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
+import net.luckperms.api.event.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a log entry is about to be sent to notifiable players on the platform
+ */
+public interface LogBroadcastEvent extends LuckPermsEvent, Cancellable {
+
+    /**
+     * Gets the log entry to be broadcasted
+     *
+     * @return the log entry to be broadcasted
+     */
+    @Param(0)
+    @NonNull Action getEntry();
+
+    /**
+     * Gets where the log entry originated from.
+     *
+     * @return the origin of the log
+     */
+    @Param(1)
+    @NonNull Origin getOrigin();
+
+    /**
+     * Represents where a log entry is from
+     */
+    enum Origin {
+
+        /**
+         * Marks a log entry which originated from the current server instance
+         */
+        LOCAL,
+
+        /**
+         * Marks a log entry which originated from an API call on the current server instance
+         */
+        LOCAL_API,
+
+        /**
+         * Marks a log entry which was sent to this server via the messaging service
+         */
+        REMOTE
+    }
+
+}

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

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

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

@@ -0,0 +1,91 @@
+/*
+ * 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.log;
+
+import net.luckperms.api.actionlog.Action;
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.platform.PlatformEntity;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a log entry is about to be sent to specific notifiable object on
+ * the platform.
+ *
+ * <p>This event is not called for players without the notify permission,
+ * but is called for objects which are ignoring log notifications (called with
+ * the cancelled flag set to true).</p>
+ */
+public interface LogNotifyEvent extends LuckPermsEvent, Cancellable {
+
+    /**
+     * Gets the log entry to be sent
+     *
+     * @return the log entry to be sent
+     */
+    @Param(0)
+    @NonNull Action getEntry();
+
+    /**
+     * Gets where the log entry originated from.
+     *
+     * @return the origin of the log
+     */
+    @Param(1)
+    @NonNull Origin getOrigin();
+
+    /**
+     * Gets the object to be notified.
+     *
+     * @return the object to notify
+     */
+    @Param(2)
+    @NonNull PlatformEntity getNotifiable();
+
+    /**
+     * Represents where a log entry is from
+     */
+    enum Origin {
+
+        /**
+         * Marks a log entry which originated from the current server instance
+         */
+        LOCAL,
+
+        /**
+         * Marks a log entry which originated from an API call on the current server instance
+         */
+        LOCAL_API,
+
+        /**
+         * Marks a log entry which was sent to this server via the messaging service
+         */
+        REMOTE
+    }
+
+}

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

@@ -0,0 +1,48 @@
+/*
+ * 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.log;
+
+import net.luckperms.api.actionlog.Action;
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
+import net.luckperms.api.event.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a log is about to be published to the storage file/table
+ */
+public interface LogPublishEvent extends LuckPermsEvent, Cancellable {
+
+    /**
+     * Gets the log entry to be published
+     *
+     * @return the log entry to be published
+     */
+    @Param(0)
+    @NonNull Action getEntry();
+
+}

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

@@ -0,0 +1,57 @@
+/*
+ * 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.log;
+
+import net.luckperms.api.actionlog.Action;
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.UUID;
+
+/**
+ * Called when a log entry is received via the MessagingService
+ */
+public interface LogReceiveEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the ID of the log entry being received
+     *
+     * @return the id of the log entry being received
+     */
+    @Param(0)
+    @NonNull UUID getLogId();
+
+    /**
+     * Gets the log entry being received
+     *
+     * @return the log entry being received
+     */
+    @Param(1)
+    @NonNull Action getEntry();
+
+}

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

@@ -0,0 +1,46 @@
+/*
+ * 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.node;
+
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.node.Node;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a node is added to a holder
+ */
+public interface NodeAddEvent extends NodeMutateEvent {
+
+    /**
+     * Gets the node that was added
+     *
+     * @return the node that was added
+     */
+    @Param(4)
+    @NonNull Node getNode();
+
+}

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

@@ -1,5 +1,8 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+ * 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
@@ -20,11 +23,11 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.exceptions;
+package net.luckperms.api.event.node;
 
 /**
- * Thrown when a permission holding object already has a permission, is already a member of a group, or when a track
- * already contains a group.
+ * Called when a holder has their nodes cleared
  */
-public class ObjectAlreadyHasException extends Exception {
+public interface NodeClearEvent extends NodeMutateEvent {
+
 }

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

@@ -0,0 +1,99 @@
+/*
+ * 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.node;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.model.PermissionHolder;
+import net.luckperms.api.model.data.DataType;
+import net.luckperms.api.model.group.Group;
+import net.luckperms.api.model.user.User;
+import net.luckperms.api.node.Node;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Set;
+
+/**
+ * Called when a node is added to/removed from a user/group
+ */
+public interface NodeMutateEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the target of the event
+     *
+     * @return the event target
+     */
+    @Param(0)
+    @NonNull PermissionHolder getTarget();
+
+    /**
+     * Gets the data type that was mutated.
+     *
+     * @return the data type
+     */
+    @Param(1)
+    @NonNull DataType getDataType();
+
+    /**
+     * Gets an immutable copy of the holders data before the change
+     *
+     * @return the data before the change
+     */
+    @Param(2)
+    @NonNull 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();
+
+    /**
+     * Gets whether the target of this event is a {@link User}
+     *
+     * <p>This is equivalent to checking if getTarget() instanceof User</p>
+     *
+     * @return if the event is targeting a user
+     */
+    default boolean isUser() {
+        return getTarget() instanceof User;
+    }
+
+    /**
+     * Gets whether the target of this event is a {@link Group}
+     *
+     * <p>This is equivalent to checking if getTarget() instanceof Group</p>
+     *
+     * @return if the event is targeting a group
+     */
+    default boolean isGroup() {
+        return getTarget() instanceof Group;
+    }
+
+}

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

@@ -0,0 +1,46 @@
+/*
+ * 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.node;
+
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.node.Node;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a node is removed from a holder
+ */
+public interface NodeRemoveEvent extends NodeMutateEvent {
+
+    /**
+     * Gets the node that was removed
+     *
+     * @return the node that was removed
+     */
+    @Param(4)
+    @NonNull Node getNode();
+
+}

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

@@ -0,0 +1,68 @@
+/*
+ * 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;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.model.PlayerSaveResult;
+import net.luckperms.api.model.user.UserManager;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.UUID;
+
+/**
+ * Called when player data is saved to the storage.
+ *
+ * <p>Data can be saved using {@link UserManager#savePlayerData(UUID, String)}.</p>
+ */
+public interface PlayerDataSaveEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the unique ID that was saved.
+     *
+     * @return the uuid
+     */
+    @Param(0)
+    @NonNull UUID getUniqueId();
+
+    /**
+     * Gets the username that was saved.
+     *
+     * @return the username
+     */
+    @Param(1)
+    @NonNull String getUsername();
+
+    /**
+     * Gets the result of the operation.
+     *
+     * @return the result
+     */
+    @Param(2)
+    @NonNull PlayerSaveResult getResult();
+
+}

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

@@ -0,0 +1,93 @@
+/*
+ * 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;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.model.user.User;
+import net.luckperms.api.util.Result;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.UUID;
+
+/**
+ * Called when LuckPerms has finished processing a Player's initial connection.
+ *
+ * <p>This event will always execute during the platforms async connection
+ * event. The LuckPerms platform listener processing the connection will block
+ * while this event is posted.</p>
+ *
+ * <p>This, among other things, allows you to wait until permission data is
+ * loaded for a User during the BungeeCord 'LoginEvent', as event priorities are
+ * ignored by the current implementation.</p>
+ *
+ * <p>The implementation will make an attempt to ensure this event is called
+ * for all connections, even if the operation to load User data was not
+ * successful. Note that LuckPerms will usually cancel the platform connection
+ * event if data could not be loaded.</p>
+ */
+public interface PlayerLoginProcessEvent extends LuckPermsEvent, Result {
+
+    /**
+     * Gets the UUID of the connection which was processed
+     *
+     * @return the uuid of the connection which was processed
+     */
+    @Param(0)
+    @NonNull UUID getUniqueId();
+
+    /**
+     * Gets the username of the connection which was processed
+     *
+     * @return the username of the connection which was processed
+     */
+    @Param(1)
+    @NonNull String getUsername();
+
+    /**
+     * Gets if the login was processed successfully.
+     *
+     * @return true if the login was successful
+     */
+    @Override
+    default boolean wasSuccessful() {
+        return getUser() != null;
+    }
+
+    /**
+     * Gets the resultant User instance which was loaded.
+     *
+     * <p>Returns {@code null} if the login was not processed
+     * {@link #wasSuccessful() successfully.}</p>
+     *
+     * @return the user instance
+     */
+    @Param(2)
+    @Nullable User getUser();
+
+}

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

@@ -0,0 +1,44 @@
+/*
+ * 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.source;
+
+import net.luckperms.api.platform.PlatformEntity;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents an {@link PlatformEntity} which was the {@link Source} of something.
+ */
+public interface EntitySource extends Source {
+
+    /**
+     * Gets the entity.
+     *
+     * @return the entity
+     */
+    @NonNull PlatformEntity getEntity();
+
+}

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

@@ -0,0 +1,64 @@
+/*
+ * 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.source;
+
+import net.luckperms.api.platform.PlatformEntity;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents the source of an event.
+ *
+ * <p>Could also be described as the "thing" that caused an event to occur.</p>
+ */
+public interface Source {
+
+    /**
+     * Gets the source type
+     *
+     * @return the type
+     */
+    @NonNull Type getType();
+
+    /**
+     * Represents a type of source
+     */
+    enum Type {
+
+        /**
+         * Represents an {@link PlatformEntity} source
+         *
+         * @see EntitySource
+         */
+        ENTITY,
+
+        /**
+         * Represents an unknown source
+         */
+        UNKNOWN
+    }
+
+}

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

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

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

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

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

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

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

@@ -1,5 +1,8 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+ * 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
@@ -20,18 +23,14 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.api;
+package net.luckperms.api.event.sync;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
 
 /**
- * A wrapper class for platform logger instances.
- *
- * <p> Bukkit/Bungee both use java.util.logging, and Sponge uses org.slf4j. This class wraps those classes so the commons
- * module can access a logger.
+ * Called before a sync task runs
  */
-public interface Logger {
-
-    void info(String s);
-    void warn(String s);
-    void severe(String s);
+public interface PreSyncEvent extends LuckPermsEvent, Cancellable {
 
 }

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

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

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

@@ -0,0 +1,65 @@
+/*
+ * 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.track;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.cause.DeletionCause;
+import net.luckperms.api.event.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.List;
+
+/**
+ * Called when a track is deleted
+ */
+public interface TrackDeleteEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the name of the deleted track
+     *
+     * @return the name of the deleted track
+     */
+    @Param(0)
+    @NonNull String getTrackName();
+
+    /**
+     * Gets an immutable copy of the tracks existing data
+     *
+     * @return a copy of the tracks existing data
+     */
+    @Param(1)
+    @NonNull List<String> getExistingData();
+
+    /**
+     * Gets the cause of the deletion
+     *
+     * @return the cause of the deletion
+     */
+    @Param(2)
+    @NonNull DeletionCause getCause();
+
+}

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

@@ -0,0 +1,37 @@
+/*
+ * 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.track;
+
+import net.luckperms.api.event.LuckPermsEvent;
+
+/**
+ * Called when all tracks have been loaded in from storage.
+ *
+ * <p>Usually only called on startup and in sync tasks.</p>
+ */
+public interface TrackLoadAllEvent extends LuckPermsEvent {
+
+}

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

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

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

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

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

@@ -1,5 +1,8 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+ * 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
@@ -20,11 +23,11 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.exceptions;
+package net.luckperms.api.event.track.mutate;
 
 /**
- * Thrown when a permission holding object does not already have a permission, is not already a member of a group,
- * or when a track doesn't contain a group.
+ * Called when a track is cleared
  */
-public class ObjectLacksException extends Exception {
+public interface TrackClearEvent extends TrackMutateEvent {
+
 }

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

@@ -0,0 +1,65 @@
+/*
+ * 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.track.mutate;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.track.Track;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.List;
+
+/**
+ * Called when a track is changed
+ */
+public interface TrackMutateEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the track that was mutated
+     *
+     * @return the track that was mutated
+     */
+    @Param(0)
+    @NonNull Track getTrack();
+
+    /**
+     * Gets an immutable copy of the tracks data before the change
+     *
+     * @return the data before the change
+     */
+    @Param(1)
+    @NonNull List<String> getStateBefore();
+
+    /**
+     * Gets an immutable copy of the tracks data after the change
+     *
+     * @return the data after the change
+     */
+    @Param(2)
+    @NonNull List<String> getStateAfter();
+
+}

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

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

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

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

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

@@ -0,0 +1,48 @@
+/*
+ * 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.source.Source;
+import net.luckperms.api.event.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents an event with a {@link Source}.
+ */
+public interface Sourced {
+
+    /**
+     * Gets the events source.
+     *
+     * <p>Never returns null. In situations where the source is unknown, a
+     * {@link Source} with type {@link Source.Type#UNKNOWN} is returned.</p>
+     *
+     * @return the source
+     */
+    @NonNull @Param(-1) Source getSource();
+
+}

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

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

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

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

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

@@ -0,0 +1,64 @@
+/*
+ * 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.util.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.UUID;
+
+/**
+ * Called when the user logs into the network for the first time.
+ *
+ * <p>Particularly useful for networks with multiple
+ * lobbies, who want to welcome a user when they join for the first time.</p>
+ *
+ * <p>This event is fired before the player has actually joined the game on the async login / auth event. If you want to
+ * do something with the user, store the UUID in a set, and then check the set in the PlayerJoinEvent o.e.</p>
+ *
+ * <p>The users data will not be loaded when this event is called.</p>
+ */
+public interface UserFirstLoginEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the UUID of the user
+     *
+     * @return the uuid of the user
+     */
+    @Param(0)
+    @NonNull UUID getUniqueId();
+
+    /**
+     * Gets the username of the user
+     *
+     * @return the username of the user
+     */
+    @Param(1)
+    @NonNull String getUsername();
+
+}

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

@@ -0,0 +1,47 @@
+/*
+ * 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.util.Param;
+import net.luckperms.api.model.user.User;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a user is loaded into memory from the storage.
+ */
+public interface UserLoadEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the user that was loaded
+     *
+     * @return the user that was loaded
+     */
+    @Param(0)
+    @NonNull User getUser();
+
+}

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

@@ -0,0 +1,43 @@
+/*
+ * 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.track;
+
+/**
+ * Represents the type of action performed in a {@link UserTrackEvent}
+ */
+public enum TrackAction {
+
+    /**
+     * The user was promoted up a track
+     */
+    PROMOTION,
+
+    /**
+     * The user was demoted down a track
+     */
+    DEMOTION
+
+}

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

@@ -0,0 +1,41 @@
+/*
+ * 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.track;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a user is demoted down a track.
+ *
+ * <p>{@link #getAction()} is always {@link TrackAction#DEMOTION}</p>
+ */
+public interface UserDemoteEvent extends UserTrackEvent {
+
+    @Override
+    default @NonNull TrackAction getAction() {
+        return TrackAction.DEMOTION;
+    }
+}

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

@@ -0,0 +1,41 @@
+/*
+ * 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.track;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Called when a user is promoted up a track.
+ *
+ * <p>{@link #getAction()} is always {@link TrackAction#PROMOTION}</p>
+ */
+public interface UserPromoteEvent extends UserTrackEvent {
+
+    @Override
+    default @NonNull TrackAction getAction() {
+        return TrackAction.PROMOTION;
+    }
+}

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

@@ -0,0 +1,84 @@
+/*
+ * 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.track;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Sourced;
+import net.luckperms.api.event.util.Param;
+import net.luckperms.api.model.user.User;
+import net.luckperms.api.track.Track;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Optional;
+
+/**
+ * Called when a user interacts with a track through a promotion or demotion
+ */
+public interface UserTrackEvent extends LuckPermsEvent, Sourced {
+
+    /**
+     * Gets the track involved in the event
+     *
+     * @return the track involved in the event
+     */
+    @Param(0)
+    @NonNull Track getTrack();
+
+    /**
+     * Gets the user who was promoted or demoted
+     *
+     * @return the user involved in the event
+     */
+    @Param(1)
+    @NonNull User getUser();
+
+    /**
+     * Gets the action performed
+     *
+     * @return the action performed
+     */
+    @NonNull TrackAction getAction();
+
+    /**
+     * Gets the group the user was promoted/demoted from.
+     *
+     * <p>May be {@link Optional#empty()} if the user wasn't already placed on the track.</p>
+     *
+     * @return the group the user was promoted/demoted from
+     */
+    @Param(2)
+    @NonNull Optional<String> getGroupFrom();
+
+    /**
+     * Gets the group the user was promoted/demoted to
+     *
+     * @return the group the user was promoted/demoted to
+     */
+    @Param(3)
+    @NonNull Optional<String> getGroupTo();
+
+}

api/src/main/java/net/luckperms/api/event/util/Param.java

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

api/src/main/java/net/luckperms/api/extension/Extension.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.extension;
+
+import net.luckperms.api.LuckPerms;
+
+/**
+ * Represents a simple extension "plugin" for LuckPerms.
+ *
+ * <p>Yes, that's right. A plugin for a plugin.</p>
+ *
+ * <p>Extensions should either declare a no-arg constructor, or a constructor
+ * that accepts a single {@link LuckPerms} parameter as it's only argument.</p>
+ */
+public interface Extension {
+
+    /**
+     * Loads the extension.
+     */
+    void load();
+
+    /**
+     * Unloads the extension.
+     */
+    void unload();
+
+}

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

@@ -0,0 +1,62 @@
+/*
+ * 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.extension;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.Collection;
+
+/**
+ * Manages extensions.
+ */
+public interface ExtensionManager {
+
+    /**
+     * Loads the given extension.
+     *
+     * @param extension the extension to load
+     */
+    void loadExtension(Extension extension);
+
+    /**
+     * Loads the extension at the given path.
+     *
+     * @param path the path to the extension
+     * @return the extension
+     * @throws IOException if the extension could not be loaded
+     */
+    @NonNull Extension loadExtension(Path path) throws IOException;
+
+    /**
+     * Gets a collection of all loaded extensions.
+     *
+     * @return the loaded extensions
+     */
+    @NonNull Collection<Extension> getLoadedExtensions();
+
+}

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

@@ -0,0 +1,75 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.messaging;
+
+import net.luckperms.api.LuckPerms;
+import net.luckperms.api.model.user.User;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * A means to push changes to other servers using the platforms networking
+ */
+public interface MessagingService {
+
+    /**
+     * Gets the name of this messaging service
+     *
+     * @return the name of this messaging service
+     */
+    String getName();
+
+    /**
+     * Uses the messaging service to inform other servers about a general
+     * change.
+     *
+     * <p>The standard response by other servers will be to execute a overall
+     * sync of all live data, equivalent to calling
+     * {@link LuckPerms#runUpdateTask()}.</p>
+     *
+     * <p>This will push the update asynchronously, and this method will return
+     * immediately. Note that this method will not cause an update to be
+     * processed on the local server.</p>
+     */
+    void pushUpdate();
+
+    /**
+     * Uses the messaging service to inform other servers about a change to a
+     * specific user.
+     *
+     * <p>The standard response by other servers is undefined, however the
+     * current implementation will reload the corresponding users data if they
+     * are online.</p>
+     *
+     * <p>This will push the update asynchronously, and this method will return
+     * immediately. Note that this method will not cause an update to be
+     * processed on the local server.</p>
+     *
+     * @param user the user to push the update for
+     */
+    void pushUserUpdate(@NonNull User user);
+
+}

api/src/main/java/net/luckperms/api/messenger/IncomingMessageConsumer.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.messenger;
+
+import net.luckperms.api.messenger.message.Message;
+import net.luckperms.api.messenger.message.OutgoingMessage;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Encapsulates the LuckPerms system which accepts incoming {@link Message}s
+ * from implementations of {@link Messenger}.
+ */
+public interface IncomingMessageConsumer {
+
+    /**
+     * Consumes a message instance.
+     *
+     * <p>The boolean returned from this method indicates whether or not the
+     * platform accepted the message. Some implementations which have multiple
+     * distribution channels may wish to use this result to dispatch the same
+     * message back to additional receivers.</p>
+     *
+     * <p>The implementation will usually return <code>false</code> if a message
+     * with the same ping id has already been processed.</p>
+     *
+     * @param message the message
+     * @return true if the message was accepted by the plugin
+     */
+    boolean consumeIncomingMessage(@NonNull Message message);
+
+    /**
+     * Consumes a message in an encoded string format.
+     *
+     * <p>This method will decode strings obtained by calling
+     * {@link OutgoingMessage#asEncodedString()}. This means that basic
+     * implementations can successfully implement {@link Messenger} without
+     * providing their own serialisation.</p>
+     *
+     * <p>The boolean returned from this method indicates whether or not the
+     * platform accepted the message. Some implementations which have multiple
+     * distribution channels may wish to use this result to dispatch the same
+     * message back to additional receivers.</p>
+     *
+     * <p>The implementation will usually return <code>false</code> if a message
+     * with the same ping id has already been processed.</p>
+     *
+     * @param encodedString the encoded string
+     * @return true if the message was accepted by the plugin
+     */
+    boolean consumeIncomingMessageAsString(@NonNull String encodedString);
+
+}

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

@@ -0,0 +1,62 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.messenger;
+
+import net.luckperms.api.messenger.message.Message;
+import net.luckperms.api.messenger.message.OutgoingMessage;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents an object which dispatches {@link OutgoingMessage}s.
+ */
+public interface Messenger extends AutoCloseable {
+
+    /**
+     * Performs the necessary action to dispatch the message using the means
+     * of the messenger.
+     *
+     * <p>The outgoing message instance is guaranteed to be an instance of one
+     * of the interfaces extending {@link Message} in the
+     * 'api.messenger.message.type' package.</p>
+     *
+     * <p>3rd party implementations are encouraged to implement this method with consideration
+     * that new types may be added in the future.</p>
+     *
+     * <p>This call is always made async.</p>
+     *
+     * @param outgoingMessage the outgoing message
+     */
+    void sendOutgoingMessage(@NonNull OutgoingMessage outgoingMessage);
+
+    /**
+     * Performs the necessary action to gracefully shutdown the messenger.
+     */
+    @Override
+    default void close() {
+
+    }
+}

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

@@ -0,0 +1,62 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.messenger;
+
+import net.luckperms.api.LuckPerms;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents a provider for {@link Messenger} instances.
+ *
+ * <p>Users wishing to provide their own implementation for the plugins
+ * "Messaging Service" should implement and register this interface.</p>
+ *
+ * @see LuckPerms#registerMessengerProvider(MessengerProvider)
+ */
+public interface MessengerProvider {
+
+    /**
+     * Gets the name of this provider.
+     *
+     * @return the provider name
+     */
+    @NonNull String getName();
+
+    /**
+     * Creates and returns a new {@link Messenger} instance, which passes
+     * incoming messages to the provided {@link IncomingMessageConsumer}.
+     *
+     * <p>As the agent should pass incoming messages to the given consumer,
+     * this method should always return a new object.</p>
+     *
+     * @param incomingMessageConsumer the consumer the new instance should pass
+     *                                incoming messages to
+     * @return a new messenger agent instance
+     */
+    @NonNull Messenger obtain(@NonNull IncomingMessageConsumer incomingMessageConsumer);
+
+}

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

@@ -1,5 +1,8 @@
 /*
- * Copyright (c) 2016 Lucko (Luck) <luck@lucko.me>
+ * 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
@@ -20,29 +23,27 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.constants;
+package net.luckperms.api.messenger.message;
 
-import lombok.Getter;
-import lombok.experimental.UtilityClass;
+import net.luckperms.api.messenger.Messenger;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;
 
-@UtilityClass
-public class Constants {
+/**
+ * Represents a message sent received via a {@link Messenger}.
+ */
+public interface Message {
 
-    @Getter
-    private static final UUID consoleUUID = UUID.fromString("00000000-0000-0000-0000-000000000000");
-
-    @Getter
-    private static final String consoleName = "Console";
-
-    @Getter
-    private static final UUID importerUUID = UUID.fromString("11111111-1111-1111-1111-111111111111");
-
-    @Getter
-    private static final String importerName = "Import";
-
-    @Getter
-    private static final String logFormat = "&8(&e%s&8)  [&a%s&8] (&b%s&8) &7--> &f%s";
+    /**
+     * Gets the unique id associated with this message.
+     *
+     * <p>This ID is used to ensure a single server instance doesn't process
+     * the same message twice.</p>
+     *
+     * @return the id of the message
+     */
+    @NonNull UUID getId();
 
 }

api/src/main/java/net/luckperms/api/messenger/message/OutgoingMessage.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.messenger.message;
+
+import net.luckperms.api.messenger.IncomingMessageConsumer;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Represents an outgoing {@link Message}.
+ *
+ * <p>Outgoing messages are ones which have been generated by this instance.
+ * (in other words, they are implemented by LuckPerms)</p>
+ *
+ * <p>Note that all implementations of this interface are guaranteed to be an
+ * instance of one of the interfaces extending {@link Message} in the
+ * 'api.messenger.message.type' package.</p>
+ */
+public interface OutgoingMessage extends Message {
+
+    /**
+     * Gets an encoded string form of this message.
+     *
+     * <p>The format of this string is likely to change between versions and
+     * should not be depended on.</p>
+     *
+     * <p>Implementations which want to use a standard method of serialisation
+     * can send outgoing messages using the string returned by this method, and
+     * pass on the message on the "other side" using
+     * {@link IncomingMessageConsumer#consumeIncomingMessageAsString(String)}.</p>
+     *
+     * @return an encoded string form of the message
+     */
+    @NonNull String asEncodedString();
+
+}

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

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

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

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

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

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

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

@@ -0,0 +1,109 @@
+/*
+ * 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.metastacking;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.ListIterator;
+import java.util.Set;
+
+/**
+ * Functional interface which removes duplicate entries from a list.
+ *
+ * <p>Used by LuckPerms to remove duplicate entries from a MetaStack.</p>
+ */
+public interface DuplicateRemovalFunction {
+
+    /**
+     * Removes duplicates from the given list, according to the behaviour
+     * of the function.
+     *
+     * @param list the entries
+     * @param <T> the type of entries
+     */
+    <T> void processDuplicates(@NonNull List<T> list);
+
+    /**
+     * A {@link DuplicateRemovalFunction} that does not remove duplicates.
+     */
+    DuplicateRemovalFunction RETAIN_ALL = new DuplicateRemovalFunction() {
+        @Override
+        public <T> void processDuplicates(@NonNull List<T> list) {
+
+        }
+
+        @Override
+        public String toString() {
+            return "DuplicateRemovalFunction#RETAIN_ALL";
+        }
+    };
+
+    /**
+     * A {@link DuplicateRemovalFunction} that retains only the first occurrence.
+     */
+    DuplicateRemovalFunction FIRST_ONLY = new DuplicateRemovalFunction() {
+        @SuppressWarnings("Java8CollectionRemoveIf")
+        @Override
+        public <T> void processDuplicates(@NonNull List<T> list) {
+            Set<T> seen = new HashSet<>(list.size());
+            for (ListIterator<T> it = list.listIterator(); it.hasNext(); ) {
+                T next = it.next();
+                if (!seen.add(next)) {
+                    it.remove();
+                }
+            }
+        }
+
+        @Override
+        public String toString() {
+            return "DuplicateRemovalFunction#FIRST_ONLY";
+        }
+    };
+
+    /**
+     * A {@link DuplicateRemovalFunction} that retains only the last occurrence.
+     */
+    DuplicateRemovalFunction LAST_ONLY = new DuplicateRemovalFunction() {
+        @Override
+        public <T> void processDuplicates(@NonNull List<T> list) {
+            Set<T> seen = new HashSet<>(list.size());
+            for (ListIterator<T> it = list.listIterator(list.size()); it.hasPrevious(); ) {
+                T next = it.previous();
+                if (!seen.add(next)) {
+                    it.remove();
+                }
+            }
+        }
+
+        @Override
+        public String toString() {
+            return "DuplicateRemovalFunction#LAST_ONLY";
+        }
+    };
+
+}

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

@@ -0,0 +1,91 @@
+/*
+ * 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.metastacking;
+
+import net.luckperms.api.query.OptionKey;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.List;
+
+/**
+ * Represents a meta stack model, consisting of a chain of elements, separated by spacers.
+ *
+ * <p>The resultant string is constructed as:
+ * [start spacer] [element] [middle spacer] [element] [middle spacer] [element] [end spacer]</p>
+ *
+ * <p>Definitions can be passed to a users UserData instance using MetaContexts, and the result of this stack can be
+ * retrieved from the returned MetaData instance.</p>
+ */
+public interface MetaStackDefinition {
+
+    /**
+     * The {@link OptionKey} for the prefix {@link MetaStackDefinition}.
+     */
+    OptionKey<MetaStackDefinition> PREFIX_STACK_KEY = OptionKey.of("prefixstack", MetaStackDefinition.class);
+
+    /**
+     * The {@link OptionKey} for the suffix {@link MetaStackDefinition}.
+     */
+    OptionKey<MetaStackDefinition> SUFFIX_STACK_KEY = OptionKey.of("suffixstack", MetaStackDefinition.class);
+
+    /**
+     * Gets an immutable list of the elements in this stack definition
+     *
+     * @return the elements in this stack
+     */
+    @NonNull List<MetaStackElement> getElements();
+
+    /**
+     * Gets the duplicate removal function, applied to the entries before
+     * formatting takes place.
+     *
+     * @return the duplicate removal function
+     */
+    @NonNull DuplicateRemovalFunction getDuplicateRemovalFunction();
+
+    /**
+     * Gets the spacer string added before any stack elements
+     *
+     * @return the start spacer
+     */
+    @NonNull String getStartSpacer();
+
+    /**
+     * Gets the spacer added between stack elements
+     *
+     * @return the middle spacer
+     */
+    @NonNull String getMiddleSpacer();
+
+    /**
+     * Gets the spacer added after any stack elements
+     *
+     * @return the end spacer
+     */
+    @NonNull String getEndSpacer();
+
+}

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

@@ -0,0 +1,51 @@
+/*
+ * 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.metastacking;
+
+import net.luckperms.api.node.ChatMetaType;
+import net.luckperms.api.node.types.ChatMetaNode;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * Represents an element within a {@link MetaStackDefinition}.
+ *
+ * <p>The element itself does not contain any mutable state.</p>
+ */
+public interface MetaStackElement {
+
+    /**
+     * Returns if the given node should be accumulated onto the stack.
+     *
+     * @param type    the type of entry being accumulated
+     * @param node    the node being considered
+     * @param current the current value being used. If this returns true, the current value will be replaced by this entry
+     * @return true if the node should be accumulated into this element, replacing the current value
+     */
+    boolean shouldAccumulate(@NonNull ChatMetaType type, @NonNull ChatMetaNode<?, ?> node, @Nullable ChatMetaNode<?, ?> current);
+
+}

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

@@ -0,0 +1,69 @@
+/*
+ * 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.metastacking;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Factory to create meta stack elements and definitions.
+ */
+public interface MetaStackFactory {
+
+    /**
+     * Parses a standard {@link MetaStackElement} from string, using the pre-defined elements in the plugin.
+     *
+     * @param definition the definition
+     * @return the parsed element, if present
+     */
+    @NonNull Optional<MetaStackElement> fromString(@NonNull String definition);
+
+    /**
+     * Parses a list of {@link MetaStackElement}s from string, using the pre-defined elements in the plugin.
+     *
+     * <p>If an element cannot be parsed, it will not be included in the resultant list.</p>
+     *
+     * @param definitions the definition strings
+     * @return a list of parsed elements
+     */
+    @NonNull List<MetaStackElement> fromStrings(@NonNull List<String> definitions);
+
+    /**
+     * Creates a new {@link MetaStackDefinition} with the given properties.
+     *
+     * @param elements                 the elements to be included in the stack.
+     * @param duplicateRemovalFunction the duplicate removal function
+     * @param startSpacer              the spacer to be included at the start of the stacks output
+     * @param middleSpacer             the spacer to be included between stack elements
+     * @param endSpacer                the spacer to be included at the end of the stacks output
+     * @return the new stack definition instance
+     */
+    @NonNull MetaStackDefinition createDefinition(@NonNull List<MetaStackElement> elements, @NonNull DuplicateRemovalFunction duplicateRemovalFunction, @NonNull String startSpacer, @NonNull String middleSpacer, @NonNull String endSpacer);
+
+
+}