Migration Guide

Moving to HyperPerms from another permission plugin? This guide covers how to migrate your existing permission setup safely and efficiently.

Before You Migrate

1. Create Backups

Back up your entire server, or at minimum:

• Your old permission plugin's data folder
• The plugins/HyperPerms/ folder (if you've already been using it)
• Any configuration files that reference permissions

2. Document Your Current Setup

Before migrating, make note of:

• All groups and their inheritance structure
• Key permissions for each group
• Special user-specific permissions
• Any context-based permissions (world-specific, etc.)

3. Plan for Downtime

Schedule the migration during low-activity hours. While migrations are usually quick, you may need time to verify and adjust settings.

General Migration Process

HyperPerms supports importing from various permission plugins. The general process is:

1. Install HyperPerms alongside your existing permission plugin
2. Use the import command to transfer data
3. Verify the imported data
4. Remove the old permission plugin
5. Restart your server

Using the Import Command

Supported import sources:

• luckperms - LuckPerms (if ported to Hytale)
• json - Generic JSON format
• yaml - Generic YAML format

Manual Migration

If automatic import isn't available for your plugin, you can migrate manually. This is often the most reliable method.

Step 1: Export Your Current Data

Most permission plugins allow exporting to a readable format. Check your current plugin's documentation for export options.

Step 2: Create Groups in HyperPerms

Create each group from your old setup:

# For each group in your old setup:
/hp group create <groupname>
/hp group setweight <groupname> <weight>
/hp group setprefix <groupname> "<prefix>"
/hp group setdisplayname <groupname> "<displayname>"

Step 3: Recreate Inheritance

Set up the same inheritance structure:

# If vip inherited from default in your old setup:
/hp group addparent vip default

# If mod inherited from vip:
/hp group addparent mod vip

Step 4: Add Permissions

Transfer permissions from your old groups:

# For each permission in the old group:
/hp group addpermission <group> <permission> <true/false>

Step 5: Migrate User Data

For users with specific group assignments or custom permissions:

# Assign user to groups
/hp user addgroup <player> <group>
/hp user setprimarygroup <player> <group>

# Add user-specific permissions
/hp user addpermission <player> <permission> <true/false>

Permission Syntax Differences

Different plugins may use different permission syntax. Here are common translations:

Negated Permissions

# Some plugins use prefix notation:
-permission.node

# HyperPerms uses value notation:
/hp group addpermission <group> permission.node false

Wildcards

# Wildcard syntax is the same in most plugins:
permission.*

# HyperPerms supports full wildcard:
*

Context Syntax

# Some plugins: world:spawn
# HyperPerms: world=spawn

/hp group addpermission <group> <permission> true world=spawn

Post-Migration Verification

After migrating, verify everything works correctly:

1. Check Group Structure

2. Verify Player Permissions

3. Test Critical Permissions

Have players from different ranks test their key permissions:

• Can default players use basic commands?
• Do VIP perks work?
• Can moderators use moderation tools?
• Do admin commands work?

Troubleshooting Migration Issues

Permissions Not Working

• Check spelling of permission nodes
• Verify the player is in the correct group
• Ensure inheritance is set up correctly
• Look for conflicting (negated) permissions

Players Missing Groups

• User UUIDs must match - migrations are UUID-based
• Offline-mode servers may have UUID mismatches
• Manually reassign groups if needed

Prefixes/Suffixes Not Showing

• Verify chat formatting is enabled in config
• Check that prefixes include color codes
• Ensure group weights are set correctly

Backup Recommendations

After a successful migration, set up a backup strategy:

# Create a manual backup
/hp backup create migration-complete

# List available backups
/hp backup list

Rolling Back

If migration fails and you need to roll back:

1. Stop your server
2. Remove HyperPerms from the plugins folder
3. Restore your old permission plugin
4. Restore your backed-up data
5. Restart your server

Next Steps

After successful migration:

• Review configuration options
• Learn about HyperPerms permission system
• Try the web editor
• Set up context-based permissions