Init
This commit is contained in:
349
content/ui-systems/permissions/_index.en.md
Normal file
349
content/ui-systems/permissions/_index.en.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
title: Permissions System
|
||||
type: docs
|
||||
weight: 12
|
||||
---
|
||||
|
||||
The Permissions system provides fine-grained access control for commands, editor features, and custom plugin functionality.
|
||||
|
||||
**Package:** `com.hypixel.hytale.server.core.permissions`
|
||||
|
||||
## Overview
|
||||
|
||||
Hytale uses a permission system with:
|
||||
- **User permissions** - Directly assigned to individual players
|
||||
- **Group permissions** - Inherited by all members of a group
|
||||
- **Permission providers** - Custom logic for dynamic permissions
|
||||
|
||||
## Accessing the Permissions Module
|
||||
|
||||
```java
|
||||
import com.hypixel.hytale.server.core.permissions.PermissionsModule;
|
||||
|
||||
// Use static get() method - NOT HytaleServer.get().getPermissionsModule()
|
||||
PermissionsModule permissions = PermissionsModule.get();
|
||||
```
|
||||
|
||||
## Checking Permissions
|
||||
|
||||
```java
|
||||
UUID playerUuid = player.getPlayerRef().getUuid();
|
||||
|
||||
// Check if player has permission
|
||||
boolean canEdit = permissions.hasPermission(playerUuid, "hytale.editor.asset");
|
||||
|
||||
// Check in command context
|
||||
if (permissions.hasPermission(ctx.sender().getUuid(), "myplugin.admin")) {
|
||||
// Admin-only logic
|
||||
}
|
||||
```
|
||||
|
||||
## User Permissions
|
||||
|
||||
Manage permissions for individual players:
|
||||
|
||||
```java
|
||||
UUID playerUuid = player.getPlayerRef().getUuid();
|
||||
|
||||
// Add permissions
|
||||
permissions.addUserPermission(playerUuid, Set.of(
|
||||
"myplugin.feature.create",
|
||||
"myplugin.feature.delete"
|
||||
));
|
||||
|
||||
// Remove permissions
|
||||
permissions.removeUserPermission(playerUuid, Set.of(
|
||||
"myplugin.feature.delete"
|
||||
));
|
||||
```
|
||||
|
||||
## Group Permissions
|
||||
|
||||
Groups allow shared permissions across multiple players:
|
||||
|
||||
### Managing Groups
|
||||
|
||||
```java
|
||||
// Add player to a group
|
||||
permissions.addUserToGroup(playerUuid, "moderators");
|
||||
|
||||
// Remove player from a group
|
||||
permissions.removeUserFromGroup(playerUuid, "moderators");
|
||||
|
||||
// Get all groups for a player
|
||||
Set<String> groups = permissions.getGroupsForUser(playerUuid);
|
||||
```
|
||||
|
||||
### Group Permission Events
|
||||
|
||||
Listen for group changes using specific event subclasses:
|
||||
|
||||
```java
|
||||
import com.hypixel.hytale.server.core.event.events.permissions.*;
|
||||
|
||||
// Player ADDED to group
|
||||
getEventRegistry().register(PlayerGroupEvent.Added.class, event -> {
|
||||
UUID playerUuid = event.getPlayerUuid();
|
||||
String group = event.getGroupName(); // Note: getGroupName(), NOT getGroup()
|
||||
log("Player joined group: " + group);
|
||||
});
|
||||
|
||||
// Player REMOVED from group
|
||||
getEventRegistry().register(PlayerGroupEvent.Removed.class, event -> {
|
||||
UUID playerUuid = event.getPlayerUuid();
|
||||
String group = event.getGroupName();
|
||||
log("Player left group: " + group);
|
||||
});
|
||||
|
||||
// Group permissions ADDED
|
||||
getEventRegistry().register(GroupPermissionChangeEvent.Added.class, event -> {
|
||||
String group = event.getGroupName();
|
||||
Set<String> added = event.getAddedPermissions();
|
||||
log("Group " + group + " got permissions: " + added);
|
||||
});
|
||||
|
||||
// Group permissions REMOVED
|
||||
getEventRegistry().register(GroupPermissionChangeEvent.Removed.class, event -> {
|
||||
String group = event.getGroupName();
|
||||
Set<String> removed = event.getRemovedPermissions();
|
||||
log("Group " + group + " lost permissions: " + removed);
|
||||
});
|
||||
|
||||
// Player permissions ADDED
|
||||
getEventRegistry().register(PlayerPermissionChangeEvent.PermissionsAdded.class, event -> {
|
||||
UUID playerUuid = event.getPlayerUuid();
|
||||
Set<String> added = event.getAddedPermissions();
|
||||
});
|
||||
|
||||
// Player permissions REMOVED
|
||||
getEventRegistry().register(PlayerPermissionChangeEvent.PermissionsRemoved.class, event -> {
|
||||
UUID playerUuid = event.getPlayerUuid();
|
||||
Set<String> removed = event.getRemovedPermissions();
|
||||
});
|
||||
```
|
||||
|
||||
## Built-in Permissions
|
||||
|
||||
Hytale includes many built-in permissions:
|
||||
|
||||
### Command Permissions
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `hytale.command.*` | All command access |
|
||||
| `hytale.command.gamemode` | Change game mode |
|
||||
| `hytale.command.tp` | Teleportation |
|
||||
| `hytale.command.give` | Give items |
|
||||
| `hytale.command.time` | Time control |
|
||||
|
||||
### Editor Permissions
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `hytale.editor.asset` | Asset editing |
|
||||
| `hytale.editor.packs.*` | Pack management |
|
||||
| `hytale.editor.builderTools` | Builder tools access |
|
||||
| `hytale.editor.brush.*` | Brush tools |
|
||||
| `hytale.editor.prefab.*` | Prefab editing |
|
||||
| `hytale.editor.selection.*` | Selection tools |
|
||||
| `hytale.editor.history` | Undo/redo history |
|
||||
|
||||
### Camera Permissions
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `hytale.camera.flycam` | Free camera mode |
|
||||
|
||||
## Custom Permission Provider
|
||||
|
||||
Implement `PermissionProvider` for dynamic permission logic:
|
||||
|
||||
{{< callout type="info" >}}
|
||||
**Note:** `PermissionProvider` is an interface that provides sets of permissions, not a simple hasPermission check. The `PermissionsModule` checks these sets.
|
||||
{{< /callout >}}
|
||||
|
||||
```java
|
||||
import com.hypixel.hytale.server.core.permissions.provider.PermissionProvider;
|
||||
|
||||
public class VIPPermissionProvider implements PermissionProvider {
|
||||
private final Map<UUID, Set<String>> vipPermissions = new ConcurrentHashMap<>();
|
||||
private final Map<UUID, Set<String>> vipGroups = new ConcurrentHashMap<>();
|
||||
|
||||
@Override
|
||||
@Nonnull
|
||||
public String getName() {
|
||||
return "VIPPermissionProvider";
|
||||
}
|
||||
|
||||
@Override
|
||||
public Set<String> getUserPermissions(@Nonnull UUID uuid) {
|
||||
// Return the permissions for this user
|
||||
// VIP users get extra permissions automatically
|
||||
if (isVIP(uuid)) {
|
||||
Set<String> perms = new HashSet<>(vipPermissions.getOrDefault(uuid, Collections.emptySet()));
|
||||
perms.add("vip.lounge");
|
||||
perms.add("vip.cosmetics");
|
||||
return perms;
|
||||
}
|
||||
return vipPermissions.getOrDefault(uuid, Collections.emptySet());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void addUserPermissions(@Nonnull UUID uuid, @Nonnull Set<String> permissions) {
|
||||
vipPermissions.computeIfAbsent(uuid, k -> new HashSet<>()).addAll(permissions);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void removeUserPermissions(@Nonnull UUID uuid, @Nonnull Set<String> permissions) {
|
||||
Set<String> userPerms = vipPermissions.get(uuid);
|
||||
if (userPerms != null) {
|
||||
userPerms.removeAll(permissions);
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public Set<String> getGroupPermissions(@Nonnull String group) {
|
||||
return Collections.emptySet();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void addGroupPermissions(@Nonnull String group, @Nonnull Set<String> permissions) {}
|
||||
|
||||
@Override
|
||||
public void removeGroupPermissions(@Nonnull String group, @Nonnull Set<String> permissions) {}
|
||||
|
||||
@Override
|
||||
public Set<String> getGroupsForUser(@Nonnull UUID uuid) {
|
||||
return vipGroups.getOrDefault(uuid, Collections.emptySet());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void addUserToGroup(@Nonnull UUID uuid, @Nonnull String group) {
|
||||
vipGroups.computeIfAbsent(uuid, k -> new HashSet<>()).add(group);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void removeUserFromGroup(@Nonnull UUID uuid, @Nonnull String group) {
|
||||
Set<String> groups = vipGroups.get(uuid);
|
||||
if (groups != null) {
|
||||
groups.remove(group);
|
||||
}
|
||||
}
|
||||
|
||||
private boolean isVIP(UUID uuid) {
|
||||
// Your VIP checking logic
|
||||
return vipDatabase.contains(uuid);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Registering Custom Providers
|
||||
|
||||
```java
|
||||
@Override
|
||||
public void start() {
|
||||
PermissionsModule permissions = PermissionsModule.get();
|
||||
permissions.addProvider(new VIPPermissionProvider());
|
||||
}
|
||||
```
|
||||
|
||||
## Permission Wildcards
|
||||
|
||||
Permissions support wildcard matching:
|
||||
|
||||
```java
|
||||
// Grant all permissions under a namespace
|
||||
permissions.addUserPermission(playerUuid, Set.of("myplugin.*"));
|
||||
|
||||
// This now passes:
|
||||
permissions.hasPermission(playerUuid, "myplugin.anything");
|
||||
permissions.hasPermission(playerUuid, "myplugin.feature.nested");
|
||||
```
|
||||
|
||||
## Command Permission Integration
|
||||
|
||||
Commands automatically check permissions based on their ID:
|
||||
|
||||
```java
|
||||
public class AdminCommand extends AbstractCommand {
|
||||
|
||||
public AdminCommand() {
|
||||
super("admin", "myplugin.commands.admin.description");
|
||||
// Permission check is automatic based on command registration
|
||||
}
|
||||
|
||||
@Override
|
||||
protected CompletableFuture<Void> execute(CommandContext ctx) {
|
||||
// Only players with appropriate permission reach here
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### Role-Based Access
|
||||
|
||||
```java
|
||||
public class RoleManager {
|
||||
private final PermissionsModule permissions;
|
||||
|
||||
public RoleManager() {
|
||||
this.permissions = PermissionsModule.get();
|
||||
}
|
||||
|
||||
public void promoteToModerator(UUID playerUuid) {
|
||||
permissions.addUserToGroup(playerUuid, "moderators");
|
||||
permissions.addUserPermission(playerUuid, Set.of(
|
||||
"server.kick",
|
||||
"server.mute",
|
||||
"server.warn"
|
||||
));
|
||||
}
|
||||
|
||||
public void demoteFromModerator(UUID playerUuid) {
|
||||
permissions.removeUserFromGroup(playerUuid, "moderators");
|
||||
permissions.removeUserPermission(playerUuid, Set.of(
|
||||
"server.kick",
|
||||
"server.mute",
|
||||
"server.warn"
|
||||
));
|
||||
}
|
||||
|
||||
public boolean canModerate(UUID playerUuid) {
|
||||
return permissions.getGroupsForUser(playerUuid).contains("moderators");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Feature Gating
|
||||
|
||||
```java
|
||||
public void useFeature(Player player, String featureName) {
|
||||
UUID uuid = player.getPlayerRef().getUuid();
|
||||
PermissionsModule perms = PermissionsModule.get();
|
||||
|
||||
String permission = "myplugin.feature." + featureName;
|
||||
if (!perms.hasPermission(uuid, permission)) {
|
||||
player.sendMessage(Message.translation("error.no_permission"));
|
||||
return;
|
||||
}
|
||||
|
||||
// Execute feature
|
||||
executeFeature(player, featureName);
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
{{< callout type="info" >}}
|
||||
**Permission Guidelines:**
|
||||
- Use namespaced permissions (e.g., `myplugin.feature.name`)
|
||||
- Prefer groups for role-based access over individual permissions
|
||||
- Check permissions at entry points, not deep in logic
|
||||
- Use wildcards sparingly and intentionally
|
||||
{{< /callout >}}
|
||||
|
||||
{{< callout type="warning" >}}
|
||||
**Security Note:** Always validate permissions server-side. Never trust client-reported permission states.
|
||||
{{< /callout >}}
|
||||
Reference in New Issue
Block a user