# Home

This section contains documentation about the new 2.0 release of PermissionsEx. Keep in mind that this documentation is *still heavily WIP*, so some sections may be unclear or incomplete.

Just getting started? You'll want to work through the [tutorial](/tutorial).

Coming from PermissionsEx v1? Take a look at the list of [changes in v2](/learning-v2-from-other-plugins-and-v1/changes-in-2.0), and the [new commands](/command).

Take a look at the contents in sidebar for more information!


# Getting Started

While PermissionsEx (PEX) is quite powerful, its flexibility means that for a beginner there isn't an obvious path to go down. This document aims to provide that path to a basic permissions configuration that most servers can work with or build on further. This guide is primarily targeted towards users new to PEX, and somewhat towards users only new to 2.0. More advanced users may want to navigate directly towards feature-specific information pages.

## Installation

Downloads of dev builds are available from [the CI server](https://jenkins.addstar.com.au/view/PermissionsEx/job/PermissionsEx/). There have not yet been any releases of the 2.x branch as several major features present in 1.x are still in development, so it is important to keep up to date with dev builds. On Sponge, the downloaded jar goes into the `mods/` folder, and on Spigot into the `plugins/` folder. On first launch, configurations will be created in the `config/permissionsex` folder for Sponge, Fabric, and Velocity, and `plugins/PermissionsEx` for Paper/Spigot/Bukkit and Bungee. 1.x configurations *will* be automatically converted on first run, and users will be converted to UUID.

## First Run

On PEX's first run, the necessary configuration files will be created. By default, no permissions are explicitly assigned to anybody. However, the default configuration gives all permissions to users connecting from the same host as the server (so if you're running a local server you'll automatically be able to run anything from ingame). On Sponge, PEX replaces the op system entirely, so setting op beforehand will not have any effect on permissions once PEX is installed.

Currently, the default [data store](/components-in-detail/data-stores) is the file backend, to be changed to H2 in the future once such a database is available. While the permissions database is human-readable, it is recommended to edit the PEX configuration using in-game commands. The SQL backend for MySQL and PostgreSQL is also available (**TODO document this**) for more complex server configurations.

## Creating an admin group

Subjects in PEX are automatically created as soon as data is assigned to them. Because of that, any command that edits a group will create a group if no such group is present, so no command to explicitly create a group exists.

The feature we're going to use for creating an admin group is *permission defaults*. This sets the permission result that will be given when any permission that has not otherwise been specified is checked. This means, that for an admin group, unless a plugin or the user explicitly forbids a permission any user in the group will have the permission. The resulting group will have all permissions, and users can be added. **WARNING** Don't set the permission default to false on the global default subject (default:default). This will override subject-specific options, including the console, in effect locking the console out of commands, which is often not the desired behavior.

Currently, a user must have joined and left the server at least once to have identification information stored for PEX to use. However, once that has happened, the following commands (run from the console or ingame with appropriate permissions) will create an admin group, creatively named `admin` in this case, though any name is possible as long as it's used consistently.

```
/pex group admin def true
/pex user <name> parent add group admin
```

Note that the admin group has not been added to any inheritance hierarchies. The admin group does not need any extra permissions, so having it be part of an inheritance hierarchy opens up the possibility for problematic overrides happening. From now on, any permissions changes can be done from ingame if desired.

## Creating general user groups

Beyond the admin group, there are almost as many possibilities for configuring ranks as there are individual servers. For the purposes of this tutorial, we'll create a default group and several inheriting groups as a useful starting point. For any individual server, it may make sense to add or remove groups as necessary. This configuration has the groups connected both by inheritance and in a rank ladder. A rank ladder is used only for the `/promote` and `/demote` commands, while inheritance is only used for permissions and options calculations. Again, because groups are only created when relevant data is present, these commands are just about configuring inheritance.

Our configuration will consist of 3 groups: default, a group users are assigned to on joining the server, member, and VIP. (All group names are case-sensitive, so make sure you keep that consistent, or use tab completion to verify)

First off, we add the default group:

```
/pex default user parent add group default
/pex rank default add group default
```

Then we add the Members group:

```
/pex rank default add group member
```

Note that we aren't adding the Default group as a parent here. This is because in PEX 2.0, the default group is automatically inserted as a parent in every permissions query, meaning that adding it as a parent to *any* group would be redundant.

And now the VIP group:

```
/pex group VIP parent add group member
/pex rank default add group VIP
```

The VIP rank is now created, at the top of the default rank ladder and inheriting data from the Member and Default groups.

This sequence can be repeated to add further groups to the sequence. At any time, to add a user to a specific group it is possible to do so:

```
/pex user <name> parent add group <group>
```

or to remove a user from a group:

```
/pex user <name> parent remove group <group>
```

However, these groups don't do much. To fix that, we need to set some permissions and options!

## Adding Permissions and options

This is what PEX is all about: permissions. Now that we have a structure, we can add permissions to each group. Because each plugin has its own set of checked permissions and options, the exact permissions added may vary a lot. However, any permissions changes follow the same structure.

First, let's add prefixes to each group. **Note that PEX does not handle prefixes or suffixes itself.** PEX is purely a data provider plugin, so a separate chat plugin is required for prefixes or suffixes to have any effect. Usually these plugins will use the `prefix` and `suffix` options for prefix and suffix respectively. These are generic options -- PEX doesn't perform any special handling for them, so any chat plugin can choose to do things differently. These options can be set (as one example) like so:

```
/pex group default option prefix "[<color name='grey'>Guest</color>]"
/pex group member option prefix "[<color name='purple'>Member</color>]"
/pex group VIP option prefix "[<color name='gold'>VIP</color>]"
```

Now, add permissions to individual groups. For example, allow VIPs to use the `/jumpto` command and tool, give the following permission:

```
/pex group VIP permission worldedit.navigation.jumpto true
```

This can be repeated for any other permission as necessary. Permissions can even be grouped together, like such:

```
/pex group VIP permission featherchat.channel.{add,remove} true
```

This would give both the permissions featherchat.channel.add and featherchat.channel.remove to the group VIP.

Wildcards are another supported permission resolution shortcut. Giving a permission `a` will give any permission that is a subnode of `a` (split by the `.` character), for example `a.b`, `a.c`, or `a.b.d`. Resolution is performed with priority as higher weight overrides lower weight, and at the same weight more specific overrides less specific, and at the same specificity and weight closer in inheritance overrides farther in inheritance.

## Further reading

* Rank Ladders
* Timed Permissions
* Contexts


# Commands

PermissionsEx can be configured in-game using its set of commands:

## Argument types

* *subject type*: a type of subject
* *subject*: A compound argument of subject type and identifier
* *context*: A `<context-type>=<context-value>`&#x20;
* *rank-ladder*: The name of a currently existing rank ladder
* *permission*: A permission string
* *option*: An option string
* *permission value*: a number, boolean, or `none`, `null`, or `unset`

## Common flags

These flags can be specified after any permissions modification command to control the specific areas permissions are updated in:

* `--transient`: If the data should be stored transiently (i.e. only for the current session)
* `--context <context>`: A context to restrict a permission to, such as a world

## The actual commands

### `/pex|permissionsex`

**Description:** Provides simple information about PermissionsEx.

### `/pex|permissionsex help [command]`

**Description:** Provide help about PermissionsEx commands

**Permission:** `permissionsex.help`

Provides an in-game help viewer for information on PermissionsEx commands

### `/pex|permissionsex debug|d [filter]`

**Description:** Toggle whether all permissions checks are logged to console

**Permission:** `permissionsex.debug`

When enabled, any check executed through PermissionsEx will be logged to console. If the `filter` regular expression is provided, only permissions, objects, and parent names that match the pattern will be logged.

### `/pex|permissionsex import [source data store]`

**Description:** Import data from another data store

**Permission:** `permissionsex.import`

Import permissions data from a configured backend, or automatically configured conversion provider. If no data store is specified, a list of available sources will be provided.

This import will fully replace any subject in the active data store that is also present in the source data store

### `/pex|permissionsex ranking|rank [ladder]`

**Description:** Print the contents of a rank ladder

**Permission:** `permissionsex.rank.view.<ladder>`

Clickable buttons are added to ease working with rank ladders.

### `/pex|permissionsex ranking|rank <ladder> add|+ <subject> [position] [-r|--relative]`

**Description:** Add a subject to the rank ladder

**Permission:** `permissionsex.rank.add.<ladder>`

Adds a subject to the rank ladder, by default at the end of the ladder. If a position is specified, the rank will be inserted at that position. If the rank is already on the ladder and the `--relative` flag is provided, the rank will be moved by the specified number of positions.

### `/pex|permissionsex ranking|rank <ladder> remove|rem|- <subject>`

**Description:** Remove a subject from a rank ladder.

**Permission:** `permissionsex.rank.remove.<ladder>`

Remove a subject from a rank ladder.

### `/pex|permissionsex reload|rel`

**Description:** Reload all PermissionsEx configuration

**Permission:** `permissionsex.reload`

Reloads all permissions data. The reload is performed asynchronously, and new data will only be applied if the reload is successful.

### `/pex|permissionsex version [--verbose|-v]`

**Description**: Provide information on the current PermissionsEx version.

**Permission:** `permissionsex.version`

Print detailed information on the version of PermissionsEx that is currently running. If the `verbose` option is provided, more detailed information on base directories will be printed.

### `/pex|permissions <type> list`

**Description:** List all subjects of a certain type

**Permission:** `permissionsex.list.<type>`

### `/pex|permissionsex <type> <subject> delete [--transient|-t]`

**Description:**: Delete all data for a subject

**Permission:** `permissionsex.delete.<type>.<subject>`

### `/pex|permissionsex <type> <subject> info`

**Description:**: Print all known information for a certain subject.

**Permission:** `permissionsex.info.<type>.<subject>`

All information will be printed for the subject

### `/pex|permissionsex <type> <subject> option|options|opt|o|meta <key> [value] [--transient|-t] [--context key=value]`

**Description:**: Sets or unsets an option for the subject

**Permission:** `permissionsex.option.set.<type>.<subject>`

Sets (if `value` is provided) or unset (if not provided) a certain option on the subject.

### `/pex|permissionsex <type> <subject> parents|parent|par|p add|a|+ <type> <subject> [--transient|t] [--context key=value]`

**Description:**: Adds a parent to the subject

**Permission:** `permissionsex.parent.add.<type>.<subject>`

The parent will be added at the first position to the subject, meaning it will take priority over other parents.

### `/pex|permissionsex <type> <subject> parents|parent|par|p remove|rem|delete|del|- <type> <subject> [--transient|t] [--context key=value]`

**Description:**: Adds a parent to the subject

**Permission:** `permissionsex.parent.remove.<type>.<subject>`

Remove the specified parent from the subject.

### `/pex|permissionsex <type> <subject> parents|parent|par|p remove|rem|delete|del|- <type> <subject> [--transient|t] [--context key=value...]`

**Description:**: Replace all parents of the subject with one parent.

**Permission:** `permissionsex.parent.set.<type>.<subject>`

Remove all parents from the subject and replace them with the one provided subject.

### `/pex|permissionsex <type> <subject> permission|permissions|perm|perms|p <permission> <value> [--transient|t] [--context key=value...]`

**Description:**: Set the permission for a subject

**Permission:** `permissionsex.permission.set.<type>.<subject>`

Set a permission on the subject.

Permission values can be a true or false value to explicitly set the permission, `none`, `null`, or `unset` to clear the permission, or a number to assign a weight to the permission.

* Prefixing a permission with `#` means that its value will only be applicable to a subject and its direct parents.
* Glob syntax will be evaluated for permissions:
  * `permissionsex.{permission,parent}.set` will evaluate to both `permissionsex.permission.set` and `permissionsex.parent.set`
  * `some.permission[a-z]` will match `some.permissiona`, `some.permissionb`, and so on, all the way through until `some.permissionz`

### `/pex|permissionsex <type> <subject> permission-default|perms-def|permsdef|pdef|pd|default|def <value> [--transient|t] [--context key=value...]`

**Description:**: Set the fallback permission value for a subject

**Permission:** `permissionsex.permission.set-default.<type>.<subject>`

Set the default permissions value for a subject. This is the result that is returned for a subject when no more specific node matches.

This value is roughly equivalent to the `*` permission formerly used, but will not override permissions specifically set to `false`.

### `/promote`

### `/demote`


# Platforms

PermissionsEx is supported on a variety of platforms, and is designed to be easy to port to others.


# Paper/Spigot/Bukkit

PermissionsEx is supported on Paper, Spigot, and Bukkit, at versions 1.8.8, 1.12.2, and latest. While other versions may work, we don't actively test on those versions and issues will not be prioritized.

* We override the Superperms system to follow our own matching rules. Apart from specific changes to match in a more pex-friendly way, we attempt to match standard Bukkit permission resolution as closely as possible (in terms of following permission parents, op/not op defaults, etc).
* To expose PEX information to plugins that only use superperms, several metapermissions are provided. These are:

  | Permission                 | Usage                                                                              |
  | -------------------------- | ---------------------------------------------------------------------------------- |
  | `group.<group>`            | Added with the name of each group the player is in, including inherited groups.    |
  | `groups.<group>`           | same as above                                                                      |
  | `options.<option>.<value>` | Added for each option set on the player, including options inherited from parents. |
  | `prefix.<prefix>`          | The player's prefix.                                                               |
  | `suffix.<suffix>`          | The player's suffix.                                                               |

  Note: these permissions are not visible through Vault or PEX's API -- both provide better ways to access the same data.

## Contexts

| Context Key | Example Value                | Description                                                            |
| ----------- | ---------------------------- | ---------------------------------------------------------------------- |
| `world`     | `world_nether`               | The name of the world a subject is currently in                        |
| `dimension` | `nether`                     | The name of the dimension a subject is currently in                    |
| `remoteip`  | `127.0.0.1`                  | The IP address a subject is connecting from                            |
| `localhost` | `myminecraftserver.com`      | The hostname a client is connecting to the server with                 |
| `localip`   | `[2607:f8b0:400a:801::200e]` | The ip (on the server) that is receiving the connection from a subject |
| `localport` | `25565`                      | The port (on the server) that the client is connecting to              |

### Plugin integrations

PermissionsEx integrates with some plugins to provide additional permissions features. While the goal is for each of these plugins to bundle their own integrations, during PEX development many of these are included in PEX itself.

| Plugin     | Integration                                                             | Source |
| ---------- | ----------------------------------------------------------------------- | ------ |
| WorldGuard | `region` context for every region in the player's applicable region set | PEX    |

## Vault notes

Vault is the standard permissions API to allow more extensive permissions operations on Bukkit. While Vault provides more functionality than the standard Superperms API, its model of permissions does not match PermissionsEx's entirely.

* Vault permission queries in a world that is not the player's active world do not provide accurate contexts. Because Vault only provides a world field, we only replace the `world` context in the player's active contexts. Any other location-based contexts, such as those for the current dimension or for any active regions, are not updated.
* Permissions and options can only be set in the global context or the context for just one world. Setting data does not use active contexts.


# Waterfall/BungeeCord

* All commands have an extra `/` prefix to be run on the proxy, and output gold text to distinguish them from commands running on the server.

  For example, `/pex` will become `//pex` to work with the proxy's instance of the plugin.
* All subjects, when queried on the proxy, are in the `proxy=true` context


# Fabric

On Fabric, the only system provided is Minecraft's op permissions system. Because of that, PermissionsEx provides all of its own integrations with Minecraft itself, and some other mods. We are happy to work with other mods to implement permissions checks as well -- feel free to pop into our Discord.

## Minecraft permissions

We aim to replace every op check in vanilla (i.e. unmodded) Minecraft with a permissions check. To that end, we provide the following permissions:

| Permission                                                              | Purpose                                                                                                                                                                                                       |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minecraft.command.<command>`                                           | Use the command `command`. Commands available to all users in vanilla should be granted by default.                                                                                                           |
| `minecraft.bypass.whitelist`                                            | Allow users to log in to a whitelisted server without being whitelisted                                                                                                                                       |
| `minecraft.bypass.spawnprotection`                                      | Allow users to build within the spawn protection radius                                                                                                                                                       |
| `minecraft.bypass.playercount`                                          | Allow users to log in even when the server has reached its player limit                                                                                                                                       |
| `minecraft.bypass.movespeed.player`                                     | Bypass the "Player moved too fast" limit                                                                                                                                                                      |
| `minecraft.bypass.movespeed.vehicle`                                    | Bypass the "Player moved too fast" kick when in a vehicle                                                                                                                                                     |
| `minecraft.bypass.chatspeed`                                            | Bypass the kick for sending chat messages faster than allowed by the game                                                                                                                                     |
| `minecraft.updatedifficulty`                                            | Allow setting the game's difficulty                                                                                                                                                                           |
| `minecraft.<commandblock/jigsawblock/structureblock>.<view/edit/break>` | Allow placing/editing/viewing/breaking a command block, jigsaw block, or structure block depending on which permissions are given                                                                             |
| `minecraft.debugstick.use.<target>`                                     | Allow using the debug stick on the `target`ed block. Targets are specified as `<namespace>.<item>` (e.g. `minecraft.stone`). Some functionality may require being in creative mode due to client limitations. |
| `minecraft.nbt.<query/load>.<entity/block>`                             | Allow placing blocks or entities while preserving their NBT data (`BlockEntityTag` and such)                                                                                                                  |
| `minecraft.selector`                                                    | Allow using selectors in commands                                                                                                                                                                             |
| `minecraft.adminbroadcast.send`                                         | Allow sending admin broadcasts to other players                                                                                                                                                               |
| `minecraft.adminbroadcast.receive`                                      | Receive messages sent to "ops" from command output                                                                                                                                                            |

## Subjects for Minecraft entities

* Players are represented as `user`s
* The server console is represented as the subject `system:Console`
* Command blocks are represented as `commandblock:<name>`, where the default command block name is `@`
* Sign representation has not been decided yet
* RCON connections are represented as `system:Recon` (Yes, that is `Recon` -- that's what the Rcon command source is named internally.)
* Functions executed through tags `#minecraft:tick` and `#minecraft:load` tags are represented as `function:minecraft:tick` and `function:minecraft:load` respectively

NOTE: functions currently only perform permissions checks when they're loaded, not on individual executions. This needs to be resolved for function permissions to actually be useful.

## Contexts

| Context Key      | Example Value                 | Description                                                                                                 |
| ---------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `world`          | `minecraft:the_nether`        | The identifier of a dimension a subject is currently in                                                     |
| `dimension_type` | `minecraft:the_nether`        | The identifier of the type of dimension a subject is in                                                     |
| `remoteip`       | `127.0.0.1`                   | The IP address a subject is connecting from                                                                 |
| `localhost`      | `myminecraftserver.com`       | The hostname a client is connecting to the server with                                                      |
| `localip`        | `[2607:f8b0:400a:801::200e]`  | The ip (on the server) that is receiving the connection from a subject                                      |
| `localport`      | `25565`                       | The port (on the server) that the client is connecting to                                                   |
| `function`       | `permissionsex:test_function` | The function currently executing. When nested functions are in progress, multiple values will be specified. |

## Other mods

* We provide a permission resolver for [WorldEdit](https://enginehub.org/worldedit) so its commands check PermissionsEx for permissions

## Developer information

PEX provides a significant level of integration into Fabric. This provides some details on what we look for when trying to provide permissions checks

### Permission check methods

* ServerCommandSource.hasPermissionLevel
* Entity.allowsPermissionLevel
* Entity.getPermissionLevel
* PlayerEntity.isCreativeLevelTwoOp
* ServerPlayNetworkHandler.isServerOwner
* MinecraftServer.isOwner
* MinecraftServer.getPermissionLevel
* PlayerManager.isOperator
* PlayerManager.areCheatsAllowed
* PlayerManager.getOpList
* PlayerManager.getOpNames
* OperatorList.get

### Known outstanding issues

* Broadcast to ops should have the subject type of the source in the permission somehow
* Check whether we enforce creative mode for certain items (debug stick, etc)
* Changing permissions is very slow -- investigate this

### Client checks op for

* F3 Debug toggle creative/spectator
* Debug stick and other technical blocks


# Sponge (v7 and v8)

PermissionsEx integrates directly with the Sponge permissions API. This API was designed together with PEX v2, so they have fairly equivalent functionality. PEX itself exposes a few more features than Sponge does, so it may be necessary for developers to integrate directly with the PEX API.

If another permissions plugin is installed, PEX will fail to enable.

## Contexts

In addition to the [global contexts](/components-in-detail/subject#contexts)

| Context Key | Example Value                | Description                                                            |
| ----------- | ---------------------------- | ---------------------------------------------------------------------- |
| `world`     | `DIM-1`                      | The world a subject is currently in                                    |
| `dimension` | `Overworld`                  | The dimension of the world a subject is currently in                   |
| `remoteip`  | `127.0.0.1`                  | The IP address a subject is connecting from                            |
| `localhost` | `myminecraftserver.com`      | The hostname a client is connecting to the server with                 |
| `localip`   | `[2607:f8b0:400a:801::200e]` | The ip (on the server) that is receiving the connection from a subject |
| `localport` | `25565`                      | The port (on the server) that the client is connecting to              |


# Velocity

PermissionsEx requires Velocity 1.1.0 or newer.

* All commands have an extra `/` prefix to be run on the proxy, and output gold text to distinguish them from commands running on the server.

  For example, `/pex` will become `//pex` to work with the proxy's instance of the plugin.
* All subjects, when queried on the proxy, are in the `proxy=true` context


# Components in Detail


# Subject

Everything in PermissionsEx is based around the subject. A subject is a user, group, server console, irc bot, or any other object that has permissions access. Each subject is composed of *segments* which each have a set of permissions, options, and inheritance that are active when the segment's set of parameters matches.

## Permissions

Permissions exist in a tree structure where each node has a weighting. A permission is split by the `.` character, and each segment can be set to a value.

*TODO*

## Options

Options are a simple key-value mapping. When multiple locations

## Parents

Any subject can inherit from any other subject.

## Contexts

Contexts are tags that can be applied to a segment that restrict the segment's applicability to a certain player state. Sponge provides several contexts and PermissionsEx applies a few more, but any plugin can add its own contexts (for example a region protection plugin could add a `region` context to allow for region-specific permissions). When PermissionsEx calculates permissions for a set of active contexts, any segment whose set of contexts is a subset of the subject's active contexts will be considered.

### PermissionsEx Contexts

| Context Key   | Example Value         | Description                                                  |
| ------------- | --------------------- | ------------------------------------------------------------ |
| `server-tag`  | `creative`            | Tags applied to the current server (in `permissionsex.conf`) |
| `before-time` | `2020-07-01T08:00:00` | Only active before this time                                 |
| `after-time`  | `2008-04-01T00:00:00` | Only active after the provided time                          |

#### Time formats

When using `before-time` and `after-time`, PermissionsEx supports a variety of formats:

* ISO Date Time: `2011-12-03T10:15:30` or `2011-12-03T10:15:30+01:00` or `2011-12-03T10:15:30+01:00[Europe/Paris]`
* ISO Time Relative to Today: `10:15` or `10:15:30` or `10:15:30+01:00`
* ISO Date: `2011-12-03` `2011-12-03+01:00`
* RFC 1123: `Tue, 3 Jun 2008 11:05:30 GMT`
* PermissionsEx Relative Time Format: `+1d2h-3m` (more on this later)
* Seconds since Epoch: `1578779386573`

**PermissionsEx Relative Time Format**

Times in PermissionsEx can be expressed in terms of the current time. The format is as follows:

* A leading sign (`+` or `-`)&#x20;
* Quantity (such as `2`)
* Unit (such as `m` for minute)

A relative time must always begin with a sign, however the same sign will be used until a new one is specified before a later quantity.

Here is a table of the current supported units:

* Seconds: `second`, `seconds`, `s`
* Minutes: `minute`, `minutes`, `m`
* Hours: `hour`, `hours`, `h`
* Days: `day`, `days`, `d`
* Weeks: `week`, `weeks`, `w`
* Months: `month`, `months`
* Years: `year`, `years`

For example, to express 3 days from now, the following can be used: `+3d`

2 days, 4 minutes less 16 seconds can be expressed in the following way: `+2d4m-16s`

In this way, administrators will be able to easily specify times relative to the current time.


# Defaults and Fallbacks

PermissionsEx has several solutions to apply data across a wide collection of subjects. While defaults and fallbacks are similar, they have a few key differences that are important to note. Fallbacks are most similar to how PEX v1's default group used to work, while defaults allow providing data that is actually applicable to every subject on the server. Defaults are also extremely useful for plugins that want to provide permissions that should not be granted with wildcards. For example, a vanish plugin might want to set the permission `vanish.autovanish.on-join` to false in the transient data of the default user subject. That woul make sure that admins are not automatically vanished on join, which is most likely not the intention of the server administrator.

## Defaults

Defaults are applied to any subject, regardless if it has its own parents. They are stored under the `default` subject type. There are per-type defaults, such as `default:<type>`, that are only applied to `<type>` subjects, and global defaults, stored under the subject `default:default`, that are applied to every subject. Defaults are only queried once at the lowest priority in subject data calculations, using the type of the subject that data is being calculated for, not any of its parents. For example, if a permission was being queried.

For the purpose of non-inheritable permissions, per-type defaults include non-inheritable permissions set directly and global defaults do not include non-inheritable permissions.

## Fallbacks

Fallbacks are only applied to subjects without any of their own data defined. Fallback data has higher priority than defaults. These fallback permissions are defined in the `fallback:<type>` subject, where `<type>` is the type of subject needing a fallback (for example, `user`. This means that the moment anything is set on a subject, its fallback information will disappear. **This can result in the loss of previously granted access!**

For the purposes of non-inheritable permissions, fallback data is treated as if it were directly included in the subject being queried.


# Data Stores

PermissionsEx can store its data in a variety of formats. By default, PEX uses the `file` backend to store permissions in the `permissions.json` file in the plugin data folder, but several others are available

## Moving between data stores

The currently active data store is set with the `default-backend` option in the plugin's configuration file. The default backend may be chosen from any data store configured in the `backends` map in the configuration. While only two data stores are listed by default, any number may be configured -- PermissionsEx only loads the one specified in `default-backend` and whichever data stores may be requested for imports.

The command `\pex import [id]` will import a data store with the id `id`, or if no parameters are provided give a list of available data stores to import from.

When importing from another data store, any subject that is present in the data store being imported from will **completely overwrite** the subject with the same identifier in the destination (i.e. currently active) data store.

## Data Store Types

### JSON File `file`

The default backend, writing to a file in the PermissionsEx data folder

#### Options

| Option                | Purpose                                                                                     | Default Value      |
| --------------------- | ------------------------------------------------------------------------------------------- | ------------------ |
| `file`                | The file to use                                                                             | `permissions.json` |
| `auto-reload`         | Automatically reload permissions when a change is made to the file                          | `true`             |
| `alphabetize-entries` | Whether to sort entries alphabetically (when true), or maintain existing order (when false) | `false`            |

### `sql`

Stores permissions data in an SQL database.

Currently supported databases are H2 and MariaDB/MySQL. PEX uses server-provided database connectors, so different platforms may have more limited support.

| Option | Purpose                                                                                                                                          | Default Value       |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `url`  | The URL of the database to connect to, in the format `jdbc:<type>:[/[[<user>:<password>@]<host>/]<database>`, where brackets indicate parameters | `h2:permissions.db` |

## Migration (read-only) data stores

These data stores are written to migrate from other permissions plugins. Generally these do not have to be configured manually -- they will be detected and made available for import when running `\pex import`

* LuckPerms (supports combined file format only for the moment, and does not support TOML)
* UltraPermissions (not yet implemented)
* Ops file
* GroupManager


# Learning v2 from other plugins and v1


# Command Equivalency

Since PermissionsEx 2.x has a new commands structure different from both PermissionsEx 1.x and GroupManager, this page exists to provide equivalent commands for many common operations. (This page is currently a stub, zml needs to finish it)

| PermissionsEx 1.x                         | GroupManager                                        | PermissionsEx 2.x (long)                     | PermissionsEx 2.x (short)              |
| ----------------------------------------- | --------------------------------------------------- | -------------------------------------------- | -------------------------------------- |
| `/pex user zml group set mygroup`         | `/manuadd zml mygroup`                              | `/pex user zml parent add group mygroup`     | `/pex user zml par + mygroup`          |
| `/pex user zml delete`                    | `/manudel zml`                                      | `/pex user zml delete`                       | `/pex user zml del`                    |
| `/pex user zml group add agroup`          | `/manuaddsub zml agroup`                            | `/pex user zml parent add group agroup`      | `/pex user zml par + agroup`           |
| `/pex user zml group remove agroup`       | `/manudelsub zml agroup`                            | `/pex user zml parent remove group agroup`   | `/pex user zml par - agroup`           |
| `/promote zml`                            | `/manpromote zml`                                   | `/promote user zml`                          | `/promote user zml`                    |
| `/demote zml`                             | `/mandemote zml`                                    | `/demote user zml`                           | `/demote user zml`                     |
| `/pex user zml`                           | `/manwhois zml`, `/manulistp zml`, `/manulistv zml` | `/pex user zml info`                         | `/pex user zml i`                      |
| `/pex user zml add <permission>`          | `/manuaddp zml <permission>`                        | `/pex user zml permission <permission> true` | `/pex user zml perm <permission> t`    |
| `/pex user zml  remove <permission>`      | `/manudelp zml <permission>`                        | `/pex user zml permission <permission> none` | `/pex user zml perm <permission> none` |
| `/pex user zml check <permission>`        | `/manucheckp zml <permission>`                      | **TODO**                                     | **TODO**                               |
| `/pex user zml set <key> <value>`         | `/manuaddv zml <key> <value>`                       | `/pex user zml option <key> <value>`         | `/pex user zml opt <key> <value>`      |
| /pex user zml set                         | `/manudelv zml <key>`                               | `/pex user zml option <key>`                 | `/pex user zml opt <key>`              |
| *none*                                    | `/manucheckv zml <key>`                             | **TODO**                                     | **TODO**                               |
| *unnecessary*                             | `/mangadd members`                                  | *unnecessary*                                | *unnecessary*                          |
| `/pex group members delete`               | `/mangdel members`                                  | `/pex group members delete`                  | `/pex group members del`               |
| `/pex group members parents add <parent>` | `/mangaddi members <parent>`                        | `/pex group members parent add <parent>`     | `/pex group members par + <parent`     |
| `/pex groups`                             | `/listgroups`                                       | `/pex group list`                            | `/pex group list`                      |


# Changes In 2.0

This document details most of the major changes between the 1.x and 2.x versions of PermissionsEx. Many of these are fairly significant, and despite the fact that migration is automatic it would be useful to be familiar with this document.

**Warning** This document is still somewhat WIP. If something is unclear, please try to clarify it (or contact zml if you're not sure).

## Command System

The commands system is fairly different. Take a look at the [Command Equivalency](/learning-v2-from-other-plugins-and-v1/command-equivalency) for learning what has changed. The required permissions are different, and tab completion is now supported.

## Context system

To allow for additional flexibility, PEX2 has replaced the system of world-specific permissions with contexts. A context is a tag that is attached to a group of permissions, options, and parents (a segment) and restricts it to subjects that match that context.

## File format

PEX now uses JSON as its file format. JSON is a simpler language than yaml, and after comparing the new data structure in both formats ended up being easier to read as well.

A side effect of this format change is that it is now relatively trivial to create a [schema for permissions files](https://github.com/PEXPlugins/PermissionsEx/blob/master/etc/permissions-schema.json). Hopefully this will lead to more advanced tools to automatically check permissions files.

## Default group

The default group is now present at the top of every inheritance hierarchy. The group will still not be inserted directly into users' entries in permissions files. However, it will also no longer be removed when another group is added. In fact, the default group cannot be removed from users at all at the moment.

## Rank ladders

Rank ladders have been extracted into a separate section of the configuration. This makes their editing simpler. Additionally, more powerful commands have been added to work with rank ladders.

## Permission resolution changes (and why `*` has been replaced with the default-permission command)

Rather than following the methodology of the first permission in the list that matches taking priority, PEX 2 assigns an numerical priority to each permission assignment. Negative numbers evaluate to false, positive numbers to true, and the higher the number the higher priority the assignment has

## Node format changes

Rather than using modified regexes, PEX 2.0 uses a simplifed shell glob with implicit inheritance.

| Old                              | New           |                                           |
| -------------------------------- | ------------- | ----------------------------------------- |
| \`worldedit.navigation.(jumpto\\ | thru).tool\`  | `worldedit.navigation.{jumpto,thru}.tool` |
| `commandbook.*`                  | `commandbook` |                                           |

These changes make it easier to calculate permissions, and as a bonus mean that the listing order of nodes in the permissions file no longer matters.

### Creating groups

While there used to be a`/pex group <name> create` command, in PEX 2.0 groups will automatically be created as soon as data is set on them


# Contributing


# Documentation Style Guide

For PEX 2.0's documentation, it is important to have a consistent style so that the documentation is easy to follow for users.

## Tutorials

A tutorial is a recipe for a specific configuration. It doesn't necessarily describe every aspect of a PEX feature. The goal of a tutorial is to provide a path a user can easily follow to achieve a certain goal, like setting up an admin group or setting up a ladder of membership levels.

Each tutorial should follow a step structure, where each step describes what is being done, as well as how to do it in the various interfaces to access PEX (commands, gui, potentialy text file).

## Subsystem Description

A subsystem description describes how a particular component of PEX works in detail. It's not focused on a specific way of doing things, but should give the information necessary to use the full feature set of the subsystem. Sections of one of these pages might be:

* Commands
* Effect on a subject of the various configuration states
* How to apply these changes directly to a backend (file?)


# Localization

PermissionsEx is built to be translatable. Players will be shown messages in their client's locale if the plugin has been translated, and server messages will be shown in the server's default locale.

Currently, messages are only available in English, so we are seeking contributors to translate to other languages.

## Overriding messages on your own server

Currently, messages can be changed only by editing the `messages.properties` files within the jar. There is usually one per package with the messages used in that package.

An eventual goal is to allow overriding messages using files in the plugin data folder, but this has not been implemented yet.

## How to contribute

While we eventually plan to put up a CrowdIn page to allow translations to be contributed more easily, the only way to contribute at the moment is to provide new versions of the files in the `src/main/messages` folder in each module.

Feel free to ask for help in the Discord -- we will be happy to assist in getting more localizations in.