Player Permissions

Checking Permissions

The Player component implements PermissionHolder:

Player player = store.getComponent(ref, Player.getComponentType());

// check if player has permission
if (player.hasPermission("mymod.admin")) {
    // allow admin action
}

// with default value if permission not set
boolean canBuild = player.hasPermission("mymod.build", true);

Or check by UUID via PermissionsModule:

PermissionsModule perms = PermissionsModule.get();
boolean hasAdmin = perms.hasPermission(playerUuid, "mymod.admin");

Permission Format

Permissions use dot-notation hierarchy:

mymod.command.teleport
mymod.command.spawn
mymod.admin

Wildcards

Pattern	Effect
*	Grants all permissions
-*	Denies all permissions
prefix.*	Grants all under prefix.
-prefix.*	Denies all under prefix.
-node	Explicitly denies a node

Wildcards are evaluated hierarchically. mymod.command.* matches mymod.command.teleport.

At each level, positive permissions are checked before negative ones. If both * and -mymod.admin are present, * grants access because it’s checked first.

Managing Permissions

Use PermissionsModule for runtime permission changes:

PermissionsModule perms = PermissionsModule.get();

User Permissions

// add permissions to a user
perms.addUserPermission(playerUuid, Set.of("mymod.vip", "mymod.fly"));

// remove permissions from a user
perms.removeUserPermission(playerUuid, Set.of("mymod.fly"));

Group Membership

// add user to a group
perms.addUserToGroup(playerUuid, "VIP");

// remove user from a group
perms.removeUserFromGroup(playerUuid, "VIP");

// get user's groups
Set<String> groups = perms.getGroupsForUser(playerUuid);

Group Permissions

// add permissions to a group
perms.addGroupPermission("VIP", Set.of("mymod.vip.feature"));

// remove permissions from a group
perms.removeGroupPermission("VIP", Set.of("mymod.vip.feature"));

Groups

Default Groups

Group	Permissions	Description
Default	(none)	All players without explicit group
OP	*	Full permissions via wildcard (see Access Control)

Users without explicit group assignment are in the Default group.

Virtual Groups

Virtual groups are permission sets keyed by group name. When a player belongs to a group, they receive that group’s virtual permissions.

Commands can tag themselves with a game mode via setPermissionGroup(GameMode.Creative). At startup, the server collects these into virtual groups keyed by the game mode name (e.g., "Creative").

Players in a group named "Creative" receive all permissions tagged with GameMode.Creative.

Resolution Order

When checking permissions:

1. User’s direct permissions
2. For each group the user belongs to:
   • Group permissions
   • Virtual group permissions (game-mode based)
3. Default value (false if not specified)

The first definitive answer (grant or deny) wins.

Permission Events

Listen for permission changes:

// user permissions changed
eventRegistry.register(PlayerPermissionChangeEvent.PermissionsAdded.class, event -> {
    UUID uuid = event.getPlayerUuid();
    Set<String> added = event.getAddedPermissions();
});

eventRegistry.register(PlayerPermissionChangeEvent.PermissionsRemoved.class, event -> {
    UUID uuid = event.getPlayerUuid();
    Set<String> removed = event.getRemovedPermissions();
});

// user group membership changed
eventRegistry.register(PlayerGroupEvent.Added.class, event -> {
    UUID uuid = event.getPlayerUuid();
    String group = event.getGroupName();
});

eventRegistry.register(PlayerGroupEvent.Removed.class, event -> {
    UUID uuid = event.getPlayerUuid();
    String group = event.getGroupName();
});

// group permissions changed
eventRegistry.register(GroupPermissionChangeEvent.Added.class, event -> {
    String group = event.getGroupName();
    Set<String> added = event.getAddedPermissions();
});

eventRegistry.register(GroupPermissionChangeEvent.Removed.class, event -> {
    String group = event.getGroupName();
    Set<String> removed = event.getRemovedPermissions();
});

Storage

Permissions are persisted to permissions.json, which stores user permissions, group memberships, and group permission sets as JSON at the server root.

Built-in Permission Nodes

Namespace	Format	Description
System commands	hytale.system.command.<cmd>	Core server commands
Built-in mods	hytale.<modname>.command.<cmd>	Built-in mod commands
Custom mods	<group>.<modname>.command.<cmd>	Your mod’s commands
Editor	hytale.editor.<feature>	Builder tools features
Camera	hytale.camera.<type>	Camera modes

Common editor permissions:

Permission	Description
hytale.editor.builderTools	Builder tools access
hytale.editor.asset	Asset editor access
hytale.editor.brush.*	Brush tool permissions
hytale.editor.prefab.*	Prefab tool permissions
hytale.editor.selection.*	Selection tool permissions
hytale.editor.history	Undo/redo access
hytale.camera.flycam	Fly camera access

Command Permissions

See Command Permissions for how commands integrate with the permission system, including auto-generated permission strings and the self/other pattern.