Hytale Permissions

Hytale Permission Management

Use this skill when managing permission nodes and groups in Hytale plugins. Permissions control what actions players can perform on the server, from basic commands to advanced administrative functions.

Quick Reference

Key Concepts

Permission Check Order

1. User's direct permissions — Permissions granted directly to the player
2. Group permissions — Permissions from groups the player belongs to
3. Virtual groups — Game-mode-based permissions (e.g., Creative mode grants builder tools)
4. Default value — Falls back to false if no match found

The first definitive match wins. If a player has a permission granted at the user level, group permissions won't override it.

Accessing PermissionsModule

PermissionsModule perms = PermissionsModule.get();

Limitations

The module does not support:

• Listing all defined groups
• Deleting a group entirely

Groups are implicitly created when you first add permissions to them.

Checking Permissions

Basic Check

boolean canUse = PermissionsModule.get().hasPermission(playerUUID, "myplugin.feature.use");
if (canUse) {
    // Player has permission
} else {
    // Player lacks permission
}

Check with Default Value

Returns the default when no explicit permission is set — useful for features enabled by default that can be revoked:

boolean canUse = PermissionsModule.get().hasPermission(playerUUID, "myplugin.feature.use", true);

Using PermissionHolder Interface

Players and command senders implement PermissionHolder, allowing direct checks:

// In a command or event handler where you have access to the player
if (player.hasPermission("myplugin.admin.manage")) {
    // Player has admin permission
}

Managing User Permissions

Adding Permissions

Permissions are additive — new permissions are added on top of existing ones, not replaced.

PermissionsModule perms = PermissionsModule.get();

// Add a single permission
perms.addUserPermission(playerUUID, Set.of("myplugin.vip.chat"));

// Add multiple permissions at once
Set<String> newPerms = Set.of(
    "myplugin.vip.chat",
    "myplugin.vip.fly",
    "myplugin.vip.kit"
);
perms.addUserPermission(playerUUID, newPerms);

Removing Permissions

PermissionsModule perms = PermissionsModule.get();

Set<String> toRemove = Set.of("myplugin.vip.fly");
perms.removeUserPermission(playerUUID, toRemove);

Managing Groups

Groups let you assign a collection of permissions to multiple players.

Adding Permissions to a Group

If the group doesn't exist, it will be created automatically.

PermissionsModule perms = PermissionsModule.get();

Set<String> vipPerms = Set.of(
    "myplugin.vip.chat",
    "myplugin.vip.fly",
    "myplugin.vip.kit"
);
perms.addGroupPermission("VIP", vipPerms);

Removing Permissions from a Group

PermissionsModule perms = PermissionsModule.get();

Set<String> toRemove = Set.of("myplugin.vip.fly");
perms.removeGroupPermission("VIP", toRemove);

Adding a User to a Group

PermissionsModule perms = PermissionsModule.get();
perms.addUserToGroup(playerUUID, "VIP");

Removing a User from a Group

PermissionsModule perms = PermissionsModule.get();
perms.removeUserFromGroup(playerUUID, "VIP");

Getting a User's Groups

PermissionsModule perms = PermissionsModule.get();
Set<String> groups = perms.getGroupsForUser(playerUUID);
for (String group : groups) {
    System.out.println("Player is in group: " + group);
}

Built-in Groups

Players without any explicit group assignment are automatically part of the Default group.

Wildcards

Wildcards grant or deny multiple permissions with a single pattern.

Wildcard Examples

// Grant all permissions to admins
perms.addGroupPermission("Admin", Set.of("*"));

// Grant all plugin permissions to moderators
perms.addGroupPermission("Moderator", Set.of("myplugin.*"));

// Grant all permissions except admin commands
perms.addGroupPermission("Helper", Set.of(
    "*",
    "-myplugin.admin.*"  // Deny admin permissions
));

Warning: Negation permissions (starting with -) take precedence at each level. Use them carefully to avoid accidentally blocking permissions.

Built-in Permission Nodes

HytalePermissions Utility

// Generate permission for a command
String perm = HytalePermissions.fromCommand("gamemode");
// Result: "hytale.command.gamemode"

// Generate permission for a subcommand
String perm = HytalePermissions.fromCommand("gamemode", "creative");
// Result: "hytale.command.gamemode.creative"

Common Permission Nodes

Listening to Permission Events

Available Events

Event Listener Example

public class PermissionListener {
    public static void onPermissionsAdded(PlayerPermissionChangeEvent.PermissionsAdded event) {
        UUID playerUUID = event.getPlayerUuid();
        Set<String> added = event.getAddedPermissions();
        System.out.println("Permissions added to " + playerUUID + ": " + added);
    }

    public static void onGroupAdded(PlayerGroupEvent.Added event) {
        UUID playerUUID = event.getPlayerUuid();
        String groupName = event.getGroupName();
        System.out.println("Player " + playerUUID + " joined group: " + groupName);
    }
}

Registering Events

public class MyPlugin extends JavaPlugin {
    @Override
    public void setup() {
        EventRegistry events = this.getEventRegistry();
        events.registerGlobal(
            PlayerPermissionChangeEvent.PermissionsAdded.class,
            PermissionListener::onPermissionsAdded
        );
        events.registerGlobal(
            PlayerGroupEvent.Added.class,
            PermissionListener::onGroupAdded
        );
    }
}

Creating a Custom Permission Provider

Useful for database-backed permissions, cross-server synchronization, or features like permission expiry.

Implementing PermissionProvider

public class DatabasePermissionProvider implements PermissionProvider {
    @Nonnull
    @Override
    public String getName() {
        return "DatabasePermissionProvider";
    }

    // User permission methods
    @Override
    public void addUserPermissions(@Nonnull UUID uuid, @Nonnull Set<String> permissions) {
        // Save to your database
    }

    @Override
    public void removeUserPermissions(@Nonnull UUID uuid, @Nonnull Set<String> permissions) {
        // Remove from your database
    }

    @Override
    public Set<String> getUserPermissions(@Nonnull UUID uuid) {
        // Query your database
        return Set.of();
    }

    // Group permission methods
    @Override
    public void addGroupPermissions(@Nonnull String group, @Nonnull Set<String> permissions) {
        // Save to your database
    }

    @Override
    public void removeGroupPermissions(@Nonnull String group, @Nonnull Set<String> permissions) {
        // Remove from your database
    }

    @Override
    public Set<String> getGroupPermissions(@Nonnull String group) {
        // Query your database
        return Set.of();
    }

    // User-group membership methods
    @Override
    public void addUserToGroup(@Nonnull UUID uuid, @Nonnull String group) {
        // Save to your database
    }

    @Override
    public void removeUserFromGroup(@Nonnull UUID uuid, @Nonnull String group) {
        // Remove from your database
    }

    @Override
    public Set<String> getGroupsForUser(@Nonnull UUID uuid) {
        // Query your database
        return Set.of("Default");
    }
}

Warning: Hytale automatically assigns players to game-mode groups (like Creative or Adventure) using the first provider. If your provider throws an error when the group doesn't exist, the player will be disconnected! Always handle missing groups gracefully.

Registering Your Provider

public class MyPlugin extends JavaPlugin {
    @Override
    public void setup() {
        // Add your provider alongside the default one
        PermissionsModule.get().addProvider(new DatabasePermissionProvider());
    }
}

The PermissionsModule aggregates permissions from all registered providers:

• Permission checks query all providers
• Write operations (add/remove) use the first provider

Replacing the Default Provider

If you want full control, remove the default provider first:

public class MyPlugin extends JavaPlugin {
    @Override
    public void setup() {
        PermissionsModule perms = PermissionsModule.get();

        // Remove the default provider FIRST
        perms.removeProvider(perms.getFirstPermissionProvider());

        // Then add your provider
        perms.addProvider(new DatabasePermissionProvider());
    }
}

Note: When you remove the default provider, the /op self command will stop working since it checks for provider tampering.

Best Practices

Permission Naming Conventions

Follow the pattern: namespace.category.action

// Good - clear hierarchy
"myplugin.admin.ban"
"myplugin.user.teleport.home"
"myplugin.vip.chat.color"

// Bad - unclear structure
"myplugin_ban"
"teleport"
"vipChatColor"

Use Constants for Permissions

Define permissions as constants to avoid typos:

public final class MyPermissions {
    public static final String ADMIN_BAN = "myplugin.admin.ban";
    public static final String ADMIN_KICK = "myplugin.admin.kick";
    public static final String USER_HOME = "myplugin.user.home";
    public static final String VIP_FLY = "myplugin.vip.fly";
}

// Usage
if (player.hasPermission(MyPermissions.ADMIN_BAN)) {
    // ...
}

Don't Over-Permission

Only create permissions for actions that genuinely need access control. Not everything needs a permission check.

Thread Safety

If you create a custom provider, ensure it's thread-safe. Permission checks can occur from multiple threads simultaneously. Use ReadWriteLock or ConcurrentHashMap for your data structures.

In-Game Commands

/op Command

/perm Command

Related Classes

• com.hypixel.hytale.server.core.permissions.PermissionsModule
• com.hypixel.hytale.server.core.permissions.PermissionProvider
• com.hypixel.hytale.server.core.permissions.PermissionHolder
• com.hypixel.hytale.server.core.permissions.HytalePermissions
• com.hypixel.hytale.server.core.permissions.PlayerPermissionChangeEvent
• com.hypixel.hytale.server.core.permissions.PlayerGroupEvent
• com.hypixel.hytale.server.core.permissions.GroupPermissionChangeEvent