# Project Essentials Permissions This modification serves as a command permissions provider for players. It is very suitable for delimiting the permissions of players and limiting the player's capabilities, for example, to prohibit changing the weather or to allow repair items. If you ever used `PermissionsEx` for spigot, then you will not have problems with setting permissions. Also, the mod has its own API, to use it, start by reading the documentation. ## How to Install For start the modification, you **need installed Forge**, it is desirable that the version matches the supported versions. You can download Forge 1.14.4 from the [link](https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.14.4.html) and Forge 1.15.2 from it [link](https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.15.2.html). Move the downloaded mod to the `mods` folder (*installation example below*). ``` val MV = valueOf(your_minecraft_version) . ├── assets ├── config ├── libraries ├── mods (that's how it should be) │ ├── Project Essentials Core-MOD-1.MV.X-1.X.X.jar (mandatory) │ ├── Project Essentials Cooldown-1.MV.X-1.X.X.jar (recommended) │ └── Project Essentials Permissions-1.MV.X-1.X.X.jar └── ... ``` ### **Dependencies** Also **do not forget** to install dependencies, only two types of dependencies: **mandatory** (*game will not start without a mod*) and **recommended** (*without a mod, game can start, but I recommend using it*). #### **Download dependencies**: [Cooldown](https://github.com/ProjectEssentials/ProjectEssentials-Cooldown) · [Core](https://github.com/ProjectEssentials/ProjectEssentials-Core) ### One more step Now try to start the game, go to the `mods` tab, if this modification is displayed in the `mods` tab, then the mod has been **successfully installed.** ## **Commands and Permissions** {% hint style="info" %} #### Command aliases also can be used with `permissions` command, example: `/permission` or `/perm`. {% endhint %} | Name | Usage Example | Permission | Description | | --------------------- | -------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------ | | `/permissions about` | `-` | `ess.perm.about` | Just send you about message. | | `/permissions save` | `-` | `ess.perm.save` | Save permissions configuration. | | `/permissions reload` | `-` | `ess.perm.reload` | Reload permissions configuration without saving. | | `/permissions group` | ... \[group name] \[set \| remove] \[node] | `ess.perm.group` | Remove or set permission for the target group. | | `/permissions user` | `... [user name] [set \| remove] [node]` or `[user name] set [group name]` | `ess.perm.user` | Remove or set user permission node or only set group for the user. | ## Configuration ### Configuration location ``` .minecraft/config/ProjectEssentials/permissions.json ``` ### Configuration documentation ### `groups` configuration section `groups` - contains an array of groups, each element of the array (group) must have the `name`, `isDefault` and `permissions` properties, if there is no property, the default value will be used, but I strongly recommend adding all the properties manually. `name` - is the name of the group; it should preferably not contain any characters other than letters; **This property is required**. `isDefault` - only accepts a boolean value; if false, the group will not be set by default; if true, the group will be used as the default; **Note:** at least one group must have the value `true`, if this is not the case, I do not know what will happen, **I did not check**. `permissions` - is a string array, it just records the rights for a specific group. If you are not familiar with `json`, I strongly recommend that you get familiar with it. **Note:** If the `permissions` array has `"*"`, then this is equivalent to the **operator’s permissions or just gives all the permissions** that the PermissionsAPI controls. `inheritFrom` - is a string array. Contains groups in which permissions must be inherited. For example: Supporter-1 group inherit Default permissions, etc. ### `users` configuration section `users` - contains an array of users, each element of the array (user) must have the `nickname`, `group` and `permissions` properties, if there is no property, the default value will be used, but I strongly recommend writing all the properties manually. `nickname` - is the nickname of the player; it should preferably not contain any characters other than letters; **This property must be required**. `group` - is the name of the group in which the player is entitled. `permissions` - is a list of rights that belong to a specific player, they can serve as a finer setting of rights; **Note:** If the player has a group, then the rights that are written by the player will be added to the rights that he received from the group. **In short: these are just additional rights for the player.** ### Just in case If something goes according to the cunt, and your configuration flies, just delete the configuration or take the default configuration from here. **Minimal default configuration:** ```javascript { "groups": [ { "name": "default", "isDefault": true, "permissions": [] }, { "name": "owner", "isDefault": false, "permissions": ["*"] } ], "users": [ { "nickname": "*", "group": "default", "permissions": [] } ] } ``` **And with default permissions:** ```javascript { "groups": [ { "name": "default", "isDefault": true, "permissions": [ "native.help", "native.list", "native.me", "native.message", "native.teammsg", "native.tell", "native.trigger", "native.w", "native.event.modifyworld", "ess.warp", "ess.warp.set", "ess.warp.remove", "ess.chat", "ess.chat.mention.all", "ess.home", "ess.home.set", "ess.home.remove", "ess.spawn", "ess.afk", "ess.sendpos", "ess.tpaccept", "ess.tpdeny", "ess.tptoggle", "ess.tpaall", "ess.tpacancel", "ess.tpa", "ess.tpahere" ], "inheritFrom": [] }, { "name": "owner", "isDefault": false, "permissions": ["*"], "inheritFrom": ["default"] } ], "users": [ { "nickname": "*", "group": "default", "permissions": [] } ] } ``` ## API in Using ### Dev. Dependencies 1.14.4 ``` - kotlin-std lib version: 1.3.61 - kotlinx serialization version: 0.14.0 - forge version: 1.14.4-28.1.114 - brigadier version: 1.0.17 - target jvm version: 1.8 ``` ### Dev. Dependencies 1.15.2 ``` - kotlin-std lib version: 1.3.61 - kotlinx serialization version: 0.14.0 - forge version: 1.14.4-31.1.1 - brigadier version: 1.0.17 - target jvm version: 1.8 ``` ### Get as Dependency {% hint style="warning" %} :: For Forge 1.14.4 only :: {% endhint %} ```groovy repositories { maven { url("https://jitpack.io") } } dependencies { compile( group: "com.github.projectessentials", name: "ProjectEssentials-Permissions", version: "v1.14.4-1.+" ) } ``` {% hint style="warning" %} :: For Forge 1.15.2 only :: {% endhint %} ```groovy repositories { maven { url("https://jitpack.io") } } dependencies { compile( group: "com.github.projectessentials", name: "ProjectEssentials-Permissions", version: "v1.15.2-1.+" ) } ``` ### API Documentation ``` PermissionsAPI.hasPermission - accepts: - playerNickName - nickname of target player. (string) - node - permission node as string, e.g ess.weather (string) - isServerSender - needed for additional checking permissions. ((boolean) by default is false) - return: true if the user has permission, else return false. (boolean) ``` ``` PermissionsAPI.getAllUserPermissions - accepts: - playerNickName - the nickname of the target player. (string) - return: list with all able users and groups for user permissions. (list with string type) ``` ``` PermissionsAPI.getDefaultGroup - description: NOTE: if default group does not exist then return group without permissions and without a name. - return: default group in what defined configuration file. (Group class instance) ``` ``` PermissionsAPI.getGroupPermissions - accepts: - groupName - just group name. (string) OR - groupInstance - just group class instance. (Group class instance) - return: list with all able group permissions. (list with string type) ``` ``` PermissionsAPI.getUserGroup - accepts: - playerNickName - the nickname of the target player. (string) - return: an instance of the class of the rights group the user belongs to. (Group class instance) ``` ``` PermissionsAPI.getUserPermissions - accepts: - playerNickName - the nickname of the target player. (string) - return: list with all able user permissions. (list with string type) ``` ``` PermissionsAPI.removeGroupPermission - description: Remove permission node from the group. - accepts: - groupName - just group name. (string) - node - group permission. (string) OR - groupInstance - just group class instance. (Group class instance) - node - group permission. (string) ``` ``` PermissionsAPI.removeUserPermission - description: Remove permission node from user. - accepts: - playerNickName - nickname of target player. (string) node - user permission. setting up for "*" (any) player. (string) ``` ``` PermissionsAPI.setGroupPermissionNode - description: Install \ Add new permission for group. - accepts: - groupName - just group name. (string) - node - new group permission. (string) OR - groupInstance - just group class instance. (Group class instance) - node - new group permission. (string) ``` ``` PermissionsAPI.setUserPermissionGroup - description: Install \ Set a new permission group for the user. - accepts: - playerNickName - nickname of target player. (string) - groupName - new user permission group. (string) OR - playerNickName - nickname of target player. (string) - groupInstance - new user permission group. (Group class instance) ``` ``` PermissionsAPI.setUserPermissionNode - description: Install \ Add new permission for the user. - type: MutableList ``` ``` PermissionsAPI.oppedPlayers - description: Contain all opped players, for advanced permission checking. - accepts: - playerNickName - nickname of target player. (string) - node - new user permission. setting up for "*" (any) player. (string) ``` ## If you have any questions or encounter a problem, be sure to open an [issue](https://github.com/ProjectEssentials/ProjectEssentials-Permissions/issues/new/choose) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://mairwunnx.gitbook.io/project-essentials/project-essentials-permissions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.