Users

Users are individual players on your server. While most permission management is done through groups, you can also assign permissions directly to specific users.

User Data Structure

Each user in HyperPerms has:

  • UUID - Unique identifier (from the game)
  • Username - Current player name
  • Primary Group - Main group determining display
  • Groups - All groups the user belongs to
  • Permissions - User-specific permission overrides
  • Custom Prefix/Suffix - Optional override of group prefix/suffix

UUID-Based Identification

HyperPerms uses UUIDs (Universally Unique Identifiers) to track players. This means:

  • Player data persists even if they change their username
  • No data loss from name changes
  • Commands accept both username and UUID
text
# Both of these work the same:
/hp user info Steve
/hp user info 853c80ef-3c37-49fd-aa49-938b674adae6
Players must have joined the server at least once for HyperPerms to know their UUID. You can't assign permissions to players who have never connected.

Primary Group vs Additional Groups

Primary Group

Every user has exactly one primary group. The primary group:

  • Determines the default prefix/suffix (unless overridden)
  • Is the "main" rank shown in various places
  • Defaults to the default group for new players
text
# Set a player's primary group
/hp user setprimarygroup Steve admin

Additional Groups

Players can belong to multiple groups simultaneously. All permissions from all groups are combined:

text
# Steve is already in "mod" group
# Add them to "vip" as well
/hp user addgroup Steve vip

# Steve now has permissions from both mod AND vip
Use multiple groups to handle different permission "tracks" - for example, a player can be both a moderator (staff track) and vip (donor track).

User-Specific Permissions

You can assign permissions directly to individual users, independent of their groups. User-specific permissions have the highest priority - they override group permissions.

When to Use User Permissions

  • Temporary exceptions - Give someone a permission temporarily
  • Special cases - A single player needs something unique
  • Restrictions - Deny a permission from a specific player
  • Testing - Test permissions before adding to a group
text
# Give Steve the ability to fly (user-specific)
/hp user addpermission Steve fly.enable true

# Deny Alex from using the ban command (even if their group has it)
/hp user addpermission Alex mod.ban false
Avoid using too many user-specific permissions. They're harder to manage than groups and can create confusing situations. Prefer creating a new group instead if multiple users need the same special permissions.

User Permissions vs Group Permissions

User PermissionsGroup Permissions
Highest priorityLower priority than user
Affects one playerAffects all group members
Good for exceptionsGood for standard permissions
Harder to trackEasy to manage centrally

Managing Users

Viewing User Information

CommandDescription
/hp user info <player>View user's permissions and groups

This shows:

  • Player's UUID and username
  • Primary group
  • All groups (including inherited)
  • User-specific permissions
  • Current prefix/suffix

Managing Groups

CommandDescription
/hp user addgroup <player> <group>Add player to a group
/hp user removegroup <player> <group>Remove player from group
/hp user setprimarygroup <player> <group>Set primary group
text
# Promote Steve to VIP
/hp user addgroup Steve vip
/hp user setprimarygroup Steve vip

# Add moderator role while keeping VIP
/hp user addgroup Steve mod
/hp user setprimarygroup Steve mod  # Show mod prefix instead of vip

Managing User Permissions

CommandDescription
/hp user addpermission <player> <permission> [value]Add permission
/hp user removepermission <player> <permission>Remove permission
/hp user clear <player>Remove all user-specific data
text
# Give temporary flight access
/hp user addpermission Steve fly.enable true

# Remove user-specific permission (will fall back to group permissions)
/hp user removepermission Steve fly.enable

Promotion and Demotion

If you have tracks set up, you can promote or demote users along them:

CommandDescription
/hp user promote <player> <track>Promote on a track
/hp user demote <player> <track>Demote on a track
text
# Promote Steve on the staff track
/hp user promote Steve staff

# Demote Steve on the staff track
/hp user demote Steve staff

Learn more in the tracks guide.

Custom Prefix and Suffix

You can override a user's prefix/suffix regardless of their group:

text
# Give Steve a custom prefix (overrides group prefix)
/hp user setprefix Steve "&6[MVP] "

# Clear custom prefix (use group prefix instead)
/hp user setprefix Steve ""
Use custom prefixes for special titles, event winners, or content creators who need unique display names.

Permission Resolution Order

When checking a user's permission, HyperPerms checks in this order:

  1. User-specific permission - Direct permission on the user
  2. Primary group permission - From their main group
  3. Other groups - By weight, highest first
  4. Inherited permissions - Following group inheritance chains
  5. Default - Plugin default if nothing is set

The first match wins. If a user has fly.enable: true directly, it doesn't matter what their groups say.

Best Practices

Do

  • Use groups for most permissions
  • Use user permissions only for temporary/special cases
  • Document why a user has special permissions
  • Regularly audit user-specific permissions

Don't

  • Give every user individual permissions
  • Forget about user permissions when troubleshooting
  • Use user permissions instead of creating appropriate groups

Cleaning Up User Data

To reset a user's data back to default:

text
# Remove all user-specific data
/hp user clear Steve

# This removes:
# - User-specific permissions
# - Additional groups (sets back to default only)
# - Custom prefix/suffix

See Also