Permissions

Permissions are the foundation of access control in HyperPerms. This guide explains what permission nodes are, how they work, and best practices for using them.

What is a Permission Node?

A permission node is a string that represents a specific action or feature that can be granted or denied. Permission nodes follow a hierarchical naming convention that makes them easy to organize and manage.

text
# Example permission nodes
chat.use           # Ability to use chat
teleport.home      # Ability to teleport home
mod.kick           # Ability to kick players
build.place        # Ability to place blocks

Permission Node Format

Permission nodes typically follow this pattern:

text
<plugin>.<category>.<action>

Examples:
hyperperms.user.info     # HyperPerms user info command
worldedit.selection.wand # WorldEdit wand selection
essentials.fly           # Essentials fly command

Naming Conventions

  • Use lowercase letters only
  • Separate parts with dots (.)
  • Be specific and descriptive
  • Group related permissions under common prefixes
Most plugins document their permission nodes. Check the plugin's documentation to find the exact nodes you need.

Permission Values

Each permission can have one of three states:

  • true - Permission is granted
  • false - Permission is explicitly denied
  • undefined - Permission is not set (will inherit or default)
text
# Grant a permission
/hp group addpermission admin mod.kick true

# Deny a permission
/hp group addpermission guest build.place false

# The difference matters for inheritance!

True vs Undefined

Understanding the difference between true and undefined is important:

  • A true permission explicitly grants access
  • An undefined permission will check parent groups (inheritance)
  • If still undefined after inheritance, plugins typically deny access

Negating Permissions

Setting a permission to false explicitly denies it, even if it would be granted by inheritance:

text
# Admin inherits from Mod, which has mod.* (all mod permissions)
# But we want to deny ban specifically for Admin
/hp group addpermission admin mod.ban false

# Admin now has all mod.* EXCEPT mod.ban
Be careful with negated permissions. They can create confusing situations if not documented well. Consider using separate groups instead of negations when possible.

Wildcards

Wildcards allow you to grant multiple permissions at once using the *character.

Partial Wildcards

text
# Grant all teleport permissions
/hp group addpermission vip teleport.* true

# This grants:
# - teleport.home
# - teleport.spawn
# - teleport.player
# - teleport.warp
# - (any other teleport.* permission)

Full Wildcard

text
# Grant ALL permissions
/hp group addpermission owner * true

# This grants every single permission!
The full wildcard (*) grants every permission. Only use it for the most trusted rank (usually owner/admin). Even then, consider whether it's really necessary.

Wildcard Behavior

Wildcards are expanded at check time, not when set. This means:

  • New permissions added by plugins are automatically included
  • You can still override specific permissions within a wildcard
  • Explicit values take priority over wildcard matches
text
# Grant all mod permissions
/hp group addpermission mod mod.* true

# But deny ban specifically
/hp group addpermission mod mod.ban false

# mod.ban = false (explicit), all other mod.* = true (wildcard)

Permission Inheritance and Resolution

When checking if a player has a permission, HyperPerms follows this order:

  1. User-specific permissions - Highest priority
  2. User's primary group - Second priority
  3. User's other groups - By weight (highest first)
  4. Inherited group permissions - Following the inheritance chain
  5. Default value - If nothing is set

Learn more in the inheritance guide.

Context-Specific Permissions

Permissions can be restricted to specific contexts like worlds or gamemodes:

text
# Permission only applies in the "creative" world
/hp group addpermission builder build.* true world=creative

# Permission only applies in survival gamemode
/hp group addpermission default pvp.enable true gamemode=survival

Learn more in the contexts guide.

Common Permission Patterns

Tiered Access

text
# Basic tier
home.use          # Can use /home
home.set          # Can set home

# Premium tier
home.multiple     # Can have multiple homes
home.unlimited    # No limit on homes

Moderation Levels

text
# Helper
mod.warn          # Can warn players

# Moderator
mod.kick          # Can kick players
mod.mute          # Can mute players

# Admin
mod.ban           # Can ban players
mod.ban.permanent # Can permanently ban

Feature Toggles

text
# Bypass permissions
cooldown.bypass        # Skip command cooldowns
filter.bypass          # Bypass chat filter
limit.bypass           # Bypass various limits

Best Practices

Do

  • Use descriptive, hierarchical permission names
  • Document what each permission does
  • Use inheritance to avoid repetition
  • Test permissions after making changes
  • Use the verbose command to debug issues

Don't

  • Give * to untrusted players
  • Use too many negated permissions
  • Forget to test after changes
  • Create overly complex permission structures

Debugging Permissions

If a permission isn't working as expected:

text
# Enable verbose mode to see all permission checks
/hp verbose

# Check a specific player's permissions
/hp user info <player>

# Test a specific permission
/hp check <player> <permission>

See Also