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 (updated on join)
• Primary Group - The user's main/display group (see below)
• Inherited Groups - Additional groups the user belongs to
• Nodes - User-specific permission nodes
• Custom Prefix/Suffix - Optional override of group prefix/suffix

User JSON Structure

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "PlayerName",
  "primaryGroup": "admin",
  "customPrefix": "&e[VIP] ",
  "customSuffix": null,
  "nodes": [
    {
      "permission": "custom.permission",
      "value": true,
      "contexts": {
        "world": "creative"
      }
    }
  ]
}

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

# Both of these work the same:
/hp user info Steve
/hp user info 853c80ef-3c37-49fd-aa49-938b674adae6

Primary Group System

What is the Primary Group?

Every user has exactly one primary group. This is stored in theprimaryGroup field and determines:

• The displayed rank/role in chat and other places
• Which group's prefix/suffix is used (if not overridden)
• The value of %group% and %primarygroup% placeholders

The primary group defaults to default for new players and is automatically included when calculating inherited permissions.

# Set a player's primary group
/hp user setprimarygroup Steve admin

# Steve's chat will now show the admin prefix
# Steve also inherits admin group permissions

Primary Group vs Additional Groups

Players can belong to multiple groups simultaneously. The primary groupis for display purposes, while additional groups provide extra permissions:

# Steve's primary group is "mod" (determines display)
/hp user setprimarygroup Steve mod

# Add "vip" as an additional group (for permissions only)
/hp user addgroup Steve vip

# Result:
# - Steve shows [Mod] prefix in chat (from primary group)
# - Steve has permissions from BOTH mod AND vip groups

Prefix/Suffix Resolution Priority

When HyperPerms needs to display a player's prefix or suffix, it checks in this order (first match wins):

1. User's Custom Prefix/Suffix
   If set via /hp user setprefix or /hp user setsuffix
2. Primary Group's Prefix/Suffix
   If the primary group has a non-empty prefix/suffix
3. Highest Priority Group
   From all inherited groups, using prefixPriority/suffixPriority, then weight as tiebreaker
4. Config Default
   Falls back to defaults.prefix/defaults.suffix in config.json

Example:
- Steve has customPrefix: null
- Steve's primaryGroup: "mod" (prefix: "&9[Mod] ")
- Steve also has group "vip" (prefix: "&a[VIP] ", weight: 20)
- Steve also has group "admin" (prefix: "&c[Admin] ", weight: 90)

Result: Steve shows "&9[Mod] " prefix
Why? Primary group takes precedence over higher-weight groups

To show Admin prefix instead:
/hp user setprimarygroup Steve admin

Setting Primary Group via Web Editor

You can also set a user's primary group through the web editor:

1. Open the web editor with /hp editor
2. Navigate to the Users tab
3. Select the player you want to modify
4. Use the "Primary Group" dropdown to select the desired group
5. Save and apply changes

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

# 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

User Permissions vs Group Permissions

Managing Users

Viewing User Information

This shows:

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

Managing Groups

# 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

# 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:

# 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:

# 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 ""

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:

# 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

• Groups - How to create and manage groups
• Inheritance - How permissions are resolved
• Tracks - Automated promotion/demotion
• User Commands - Complete command reference