EtherealPerms Logo

EtherealPerms Wiki

Your complete guide to mastering permission management in Hytale.

Core Concepts

Users

Represents a player. Each has a UUID and can have individual permissions or belong to groups.

Groups

A collection of permissions and metadata. The primary way to manage permissions for many players.

Permission Nodes

A string representing a specific permission (e.g., 'etherealperms.command.creategroup'). Can be granted (true) or denied (false).

Inheritance

Allows groups to inherit permissions from other groups via the 'group.<groupname>' node.

Weight

An integer that determines which node is used when a player has multiple same nodes. The highest weight wins.

Metadata

Cosmetic data like prefixes, suffixes, and chat colors for users and groups or data to store.

Configuration

Main Config File (config.yml)

Main config file

Main Configuration File

############################################################
# +------------------------------------------------------+ #
# |                   Chat Settings                      | #
# +------------------------------------------------------+ #
############################################################

# Available placeholders:
# {MESSAGE} - The content of the chat message.
# {DISPLAYNAME} - The sender's display name.
# {PREFIX} - The sender's prefix.
# {SUFFIX} - The sender's suffix.
# {GROUP} - The sender's primary group name.

# Default Colors:
#RED
#DARK_RED
#GOLD
#YELLOW
#GREEN
#DARK_GREEN
#AQUA
#DARK_AQUA
#BLUE
#DARK_BLUE
#LIGHT_PURPLE
#DARK_PURPLE
#WHITE
#GRAY
#DARK_GRAY
#BLACK
#PINK
#ORANGE
#LIME
#CYAN
# Hex Colors can also be used | Example: <#FF0000>Test -> Red colored text "Test"

# Legacy Colors Supported:
# &0 
# &1
# &2
# &3
# &4
# &5
# &6
# &7
# &8
# &9
# &a
# &b
# &c
# &d
# &e
# &f
# &l (Bold)
# &o (Italic)

chat:
  format: '{PREFIX} {DISPLAYNAME} {SUFFIX}> {MESSAGE} '
  #format: '<red>{GROUP}<reset> <white>{DISPLAYNAME} <gray>:<reset> {MESSAGE}'
  #format: '{PREFIX} <blue>{DISPLAYNAME}<reset> {SUFFIX}: <yellow>{MESSAGE}'

  # You can also specify a format for each group.
  group-formats:
  #  default: '{DISPLAYNAME}: {MESSAGE}'
  #  admin: '[{GROUP}] {DISPLAYNAME}: {MESSAGE}'

############################################################
# +------------------------------------------------------+ #
# |                  Storage Settings                    | #
# +------------------------------------------------------+ #
############################################################

storage:
  # Available types: local, mongodb, mysql
  type: mongodb
  #sync-interval: 60 # In minutes, 0 to disable

  database:
    mongodb:
      connection-string: "mongodb://localhost:27017"
      database: "ethereal_db"
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "ethereal_db"
      username: "admin"
      password: "ciao1234"
groups.json

This file, located in 'mods/EtherealLabs_EtherealPerms/', contains all group definitions.

Example Configuration File

{
  "default": {
    "name": "default",
    "weight": 0,
    "nodes": [
      {
        "key": "etherealperms.default",
        "value": true,
        "context": {}
      },
      {
        "key": "hytale.command.spawn.self",
        "value": true,
        "context": {}
      },
      {
        "key": "prefix.1.<cyan><bold>User</bold><reset>",
        "value": true,
        "context": {}
      }
    ]
  },
  "moderator": {
    "name": "moderator",
    "weight": 0,
    "nodes": [
      {
        "key": "hytale.system.command.kick",
        "value": true,
        "context": {}
      },
      {
        "key": "prefix.1.<blue><bold>Mod</bold><reset>",
        "value": true,
        "context": {}
      },
      {
        "key": "hytale.accesscontrolmodule.command.ban",
        "value": true,
        "context": {}
      }
    ]
  },
  "admin": {
    "name": "admin",
    "weight": 0,
    "nodes": [
      {
        "key": "*",
        "value": true,
        "context": {}
      },
      {
        "key": "prefix.10.<red><bold>Admin</bold><reset>",
        "value": true,
        "context": {}
      }
    ]
  }
}
User Files (users/<uuid>.json)

Each user's data is stored in a separate file named after their UUID.

Example Configuration File

{
  "uuid": "uuid",
  "username": "Darkeox34",
  "nodes": [
    {
      "key": "prefix.10.<red>TestPrefix<reset>",
      "value": true,
      "context": {}
    },
    {
        "key": "hytale.accesscontrolmodule.command.ban",
        "value": true,
        "context": {}
    }
  ]
}

Commands

The base command is /ep (aliases: /eperms, /etherealperms). Arguments in <angle brackets> are required, while those in [square brackets] are optional.

General Commands

/ep editor

Open in-game ui editor.

etherealperms.editor
/ep reloadconfig

Reloads all user and group data from the configuration files.

etherealperms.reloadconfig
/ep listgroups

Lists all available groups.

etherealperms.listgroups
/ep creategroup <name> [weight]

Creates a new group.

etherealperms.creategroup
/ep deletegroup <group>

Delete a group.

etherealperms.deletegroup
/ep sync run

Synchronize local data with remote data

etherealperms.sync.run
/ep sync upload

Synchronize remote data with local data

etherealperms.sync.upload

User Commands

Base Permission: etherealperms.user

/ep user info <player>

Displays information about a user.

etherealperms.user.info
/ep user group add <player> <group>

Adds a user to a group.

Example Command
/ep user group add Darkeox34 admin
etherealperms.user.group.add
/ep user group remove <player> <group>

Removes a user from a group.

Example Command
/ep user group remove Darkeox34 admin
etherealperms.user.group.remove
/ep user group set <player> <group>

Sets a user's primary group, removing them from all others.

Example Command
/ep user group set Darkeox34 admin
etherealperms.user.group.set
/ep user permission set <player> <node> [true|false]

Sets a permission node for a user.

Example Command
/ep user permission set Darkeox34 myplugin.permission --value=true
etherealperms.user.permission.set
/ep user permission unset <player> <node>

Removes a permission node from a user.

Example Command
/ep user permission unset Darkeox34 myplugin.permission
etherealperms.user.permission.unset
/ep user meta set <player> <key> <value>

Sets a metadata pair of value [key,value] for a user

Example Command
/ep user meta set Darkeox34 example.key example.value
etherealperms.user.meta.set
/ep user meta setsuffix <player> <weight> <suffix>

Sets a suffix for a user, removing all other suffixes.

Example Command
/ep user meta setsuffix Darkeox34 10 <red><bold><italic>MySuffix<reset><#FF00000>
etherealperms.user.meta.setsuffix
/ep user meta addprefix <player> <weight> <prefix> [color] [format]

Adds a prefix for a user

Example Command
/ep user meta setprefix Darkeox34 10 <red><bold><italic>MyPrefix<reset><#FF00000>
etherealperms.user.meta.addprefix
/ep user meta removesuffix <player> <weight> [suffix]

Removes a suffix from a user

Example Command
/ep user meta removesuffix Darkeox34 10 --suffix=<red>MySuffix
etherealperms.user.meta.removesuffix
/ep user meta setprefix <player> <weight> <prefix>

Sets a prefix to a user, removing all other prefixes.

Example Command
/ep user meta setprefix Darkeox34 10 <red><bold>Admin<reset>
etherealperms.user.meta.setprefix
/ep user meta addsuffix <player> <weight> <suffix>

Adds a suffix to a user

Example Command
/ep user meta addsuffix Darkeox34 10 <red><bold>MySuffix<reset>
etherealperms.user.meta.addsuffix
/ep user meta removeprefix <player> <weight> [prefix]

Removes a prefix from a user

Example Command
/ep user meta removeprefix Darkeox34 10 --prefix=<red>MyPrefix
etherealperms.user.meta.removeprefix
/ep user clone <player> <target>

Clone user configuration from a source user to a target user.

Example Command
/ep user clone Darkeox34 zDavid
etherealperms.user.clone

Group Commands

Base Permission: etherealperms.group

/ep group info <group>

Displays information about a group.

etherealperms.group.info
/ep group deletegroup <group>

Deletes a group.

Example Command
/ep group deletegroup admin
etherealperms.group.delete
/ep group rename <group> <new_name>

Renames a group.

Example Command
/ep group rename admin admins
etherealperms.group.rename
/ep group setweight <group> <weight>

Sets the weight for a group.

Example Command
/ep group setweight admin 50
etherealperms.group.setweight
/ep group parent add <group> <parent_group>

Adds a parent to a group.

Example Command
/ep group parent add admin moderator
etherealperms.group.parent.add
/ep group parent remove <group> <parent_group>

Removes a parent from a group.

Example Command
/ep group parent remove admin moderator
etherealperms.group.parent.remove
/ep group meta set <group> <key> <value>

Sets a metadata value for a group.

Example Command
/ep group meta set admin example.key example.value
etherealperms.user.meta.set
/ep group meta setsuffix <group> <weight> <suffix>

Sets a suffix to a group.

Example Command
/ep group meta setsuffix admin 10 <red><bold><italic>MySuffix<reset><#FF00000>
etherealperms.group.meta.setsuffix
/ep group meta addprefix <group> <weight> <prefix>

Adds a prefix to a group

Example Command
/ep group meta addprefix admin 10 <red><bold>Admin<reset>
etherealperms.group.meta.addprefix
/ep group meta removesuffix <group> <weight> <suffix>

Removes a suffix from a group

Example Command
/ep group meta removesuffix admin 10 --suffix=<red>MySuffix
etherealperms.group.meta.removesuffix
/ep group meta setprefix <group> <weight> <prefix>

Sets a prefix to a group

Example Command
/ep group meta setprefix admin 10 <red><bold>Admin<reset>
etherealperms.group.meta.setprefix
/ep group meta addsuffix <group> <weight> <suffix>

Adds a suffix to a group

Example Command
/ep group meta addsuffix admin 10 <red><bold>MySuffix<reset>
etherealperms.group.meta.addsuffix
/ep group meta removeprefix <group> <weight> <prefix>

Removes a prefix from a group

Example Command
/ep group meta removeprefix admin 10 --prefix=<red>MyPrefix
etherealperms.group.meta.removeprefix

Developer API

EtherealPerms provides a robust API for developers to interact with the permission system directly from their plugins. Access the API instance via EtherealPerms.api.

Permission Checks

fun hasPermission(uuid: UUID, permission: String): Boolean

Checks if a specific user possesses a permission node.

Parameters

uuid
UUID
The unique identifier of the user.
permission
String
The permission node to check (e.g., 'myplugin.command').

Returns

True if the user has the permission, false otherwise.

Example

if (api.hasPermission(player.uniqueId, "myplugin.admin")) {
    player.sendMessage("You have access!")
}
fun isPlayerInGroup(uuid: UUID, group: String): Boolean

Checks if a player is a member of a specific group (including inheritance if applicable in future updates, currently direct check).

Parameters

uuid
UUID
The unique identifier of the user.
group
String
The name of the group to check.

Returns

True if the player is in the group.

Example

if (api.isPlayerInGroup(player.uniqueId, "vip")) {
    // Player is VIP
}

User Metadata

fun getUserPrefix(uuid: UUID): String

Retrieves the highest priority chat prefix for a user.

Parameters

uuid
UUID
The unique identifier of the user.

Returns

The prefix string containing legacy/hex color codes.

Example

val prefix = api.getUserPrefix(player.uniqueId)
fun getUserSuffix(uuid: UUID): String

Retrieves the highest priority chat suffix for a user.

Parameters

uuid
UUID
The unique identifier of the user.

Returns

The suffix string.

Example

val suffix = api.getUserSuffix(player.uniqueId)
fun getUserPrimaryGroup(uuid: UUID): Group?

Gets the user's primary group (usually the one with highest weight).

Parameters

uuid
UUID
The unique identifier of the user.

Returns

The Group object or null if none found.

Example

val group = api.getUserPrimaryGroup(player.uniqueId)
fun getUserGroups(uuid: UUID): List<Group>

Retrieves all groups the user is a member of.

Parameters

uuid
UUID
The unique identifier of the user.

Returns

A list of Group objects.

Example

api.getUserGroups(uuid).forEach { group ->
    println("Member of: ${group.name}")
}

User Management

fun addUserPermission(uuid: UUID, permission: String)

Grants a specific permission node to a user.

Parameters

uuid
UUID
The unique identifier of the user.
permission
String
The node to add.

Example

api.addUserPermission(uuid, "bonus.coins")
fun removeUserPermission(uuid: UUID, permission: String)

Revokes a permission node from a user.

Parameters

uuid
UUID
The unique identifier of the user.
permission
String
The node to remove.

Example

api.removeUserPermission(uuid, "bonus.coins")
fun setPlayerToGroup(uuid: UUID, group: String)

Sets the player's primary group, removing all other group memberships.

Parameters

uuid
UUID
The unique identifier of the user.
group
String
The target group name.

Example

api.setPlayerToGroup(uuid, "admin")
fun addPlayerToGroup(uuid: UUID, group: String)

Adds a player to a group without affecting other memberships.

Parameters

uuid
UUID
The unique identifier of the user.
group
String
The group to add.

Example

api.addPlayerToGroup(uuid, "builder")
fun removePlayerFromGroup(uuid: UUID, group: String)

Removes a player from a specific group.

Parameters

uuid
UUID
The unique identifier of the user.
group
String
The group to remove.

Example

api.removePlayerFromGroup(uuid, "default")

Group Management

fun addGroupPermission(groupName: String, permission: String)

Adds a permission node to a group by name.

Parameters

groupName
String
The name of the group.
permission
String
The permission node.

Example

api.addGroupPermission("default", "spawn.use")
fun removeGroupPermission(groupName: String, permission: String)

Removes a permission node from a group by name.

Parameters

groupName
String
The name of the group.
permission
String
The permission node.

Example

api.removeGroupPermission("default", "spawn.use")

Utilities

fun translateColors(message: String): Message

Parses a string with legacy (&a) or Hex (<#FFFFFF>) color codes into a Hytale Message component.

Parameters

message
String
The raw string to translate.

Returns

A com.hypixel.hytale.server.core.Message object.

Example

val msg = api.translateColors("<green>Success! <#ff00ff>Woohoo!")
player.sendMessage(msg)