Context-Aware Permissions

Contexts allow you to create permissions that only apply under specific conditions, such as being in a certain world or gamemode. This powerful feature lets you create location-specific or situation-specific permission rules.

What are Contexts?

A context is a condition that must be met for a permission to apply. When you add a context to a permission, that permission only takes effect when the player matches the specified context.

text
# Permission without context - always applies
fly.enable: true

# Permission with context - only applies in "hub" world
fly.enable: true [world=hub]

# The player can fly in the hub, but not in other worlds

Available Context Types

World Context

Permissions based on which world the player is currently in.

text
# Allow flight only in the hub world
/hp group addpermission vip fly.enable true world=hub

# Allow building only in the creative world
/hp group addpermission default build.* true world=creative

# Deny PvP in spawn world
/hp group addpermission default pvp.enable false world=spawn

Gamemode Context

Permissions based on the player's current gamemode.

text
# Allow WorldEdit only in creative mode
/hp group addpermission builder worldedit.* true gamemode=creative

# Restrict certain commands to survival
/hp group addpermission default economy.trade true gamemode=survival

Server Context

For multi-server networks, permissions can be restricted to specific servers.

text
# Permission only on the skyblock server
/hp group addpermission default island.* true server=skyblock
The server context is useful for networks running multiple servers with shared permission data. On single-server setups, this context isn't needed.

Context Syntax

Contexts are specified as key=value pairs after the permission value:

text
/hp group addpermission <group> <permission> <value> [context1=value1] [context2=value2]

Examples:
/hp group addpermission vip fly.enable true world=hub
/hp group addpermission builder we.* true world=creative gamemode=creative

Multiple Contexts (AND Logic)

You can combine multiple contexts. When multiple contexts are specified, ALL must match for the permission to apply (AND logic).

text
# Only applies when BOTH conditions are true:
# - Player is in the "creative" world
# - Player is in creative gamemode
/hp group addpermission builder worldedit.* true world=creative gamemode=creative

# The player must be in the creative world AND in creative gamemode
# If either condition is false, this permission doesn't apply
Multiple contexts use AND logic, not OR. If you need OR logic (world=hub OR world=spawn), you need to add separate permissions for each case.

Global (Default) Context

Permissions without any context are "global" - they apply everywhere.

text
# Global permission (no context) - applies everywhere
/hp group addpermission vip chat.color true

# Context-specific - only in hub
/hp group addpermission vip fly.enable true world=hub

How Context Resolution Works

When checking a permission, HyperPerms:

  1. Gets the player's current contexts (world, gamemode, etc.)
  2. Looks for permissions that match ALL specified contexts
  3. More specific (more contexts) matches take priority
  4. Falls back to global permissions if no contextual match exists
text
# Example resolution:
# Player is in world "hub", gamemode "survival"

# Group has these permissions:
# 1. fly.enable: true world=hub gamemode=creative
# 2. fly.enable: true world=hub
# 3. fly.enable: false

# Resolution:
# - Permission 1: world matches, but gamemode doesn't → skip
# - Permission 2: world matches → APPLIES (fly.enable = true)
# - Permission 3: would apply, but permission 2 is more specific

Contextual Permission Priority

More specific contexts take priority over less specific ones:

text
# Priority (highest to lowest):
# 1. world=hub gamemode=creative (2 contexts - most specific)
# 2. world=hub (1 context)
# 3. gamemode=creative (1 context)
# 4. (no context - global)

# Example:
/hp group addpermission default build.place true           # Global: yes
/hp group addpermission default build.place false world=spawn  # Spawn: no

# In spawn world: build.place = false (more specific)
# In other worlds: build.place = true (global fallback)

Configuration

Enable or disable context calculators in config.json:

json
{
  "contexts": {
    "world": true,
    "gamemode": true
  }
}
Disabling unused context calculators can provide a small performance improvement. Only disable contexts you're certain you won't need.

Use Cases and Examples

Hub-Only Perks

Give VIPs special abilities only in the hub:

text
/hp group addpermission vip fly.enable true world=hub
/hp group addpermission vip speed.boost true world=hub
/hp group addpermission vip doublejump.use true world=hub

Creative World Building

Allow building tools only in the creative world:

text
/hp group addpermission builder worldedit.* true world=creative
/hp group addpermission builder voxelsniper.* true world=creative
/hp group addpermission builder build.unlimited true world=creative

Spawn Protection

Prevent building in spawn while allowing it elsewhere:

text
# Allow building globally
/hp group addpermission default build.place true
/hp group addpermission default build.break true

# Deny in spawn (more specific, takes priority)
/hp group addpermission default build.place false world=spawn
/hp group addpermission default build.break false world=spawn

Gamemode-Specific Features

Restrict certain features to specific gamemodes:

text
# Economy only works in survival
/hp group addpermission default economy.* true gamemode=survival

# Creative mode has building tools
/hp group addpermission default creative.tools true gamemode=creative

PvP Arenas

Enable PvP only in arena worlds:

text
# Disable PvP globally
/hp group addpermission default pvp.attack false

# Enable in arena world
/hp group addpermission default pvp.attack true world=arena

Managing Contextual Permissions

Adding Context Permissions

CommandDescription
/hp group addpermission <group> <perm> <value> [contexts...]Add with context
/hp user addpermission <user> <perm> <value> [contexts...]User context permission

Removing Context Permissions

When removing, you must specify the same contexts:

text
# Adding
/hp group addpermission vip fly.enable true world=hub

# Removing (must match contexts exactly)
/hp group removepermission vip fly.enable world=hub

# This WON'T work (different/no contexts):
/hp group removepermission vip fly.enable  # Wrong - no context

Debugging Contexts

text
# Enable verbose to see context matching
/hp verbose

# Check what contexts a player currently has
/hp user info <player>

# Test a permission in current context
/hp check <player> <permission>

See Also