Permissions

Permissions

Complete guide to the Hytale Admin permission system — 16 granular permissions, custom permission groups, and OP management.

Permission Reference

The plugin defines 16 custom permissions that control access to every feature:

Permission Hierarchy

Permissions follow a read → manage pattern:

• *-read = view-only access
• *-manage = full control (includes read)

Having *-manage without *-read still works — the manage permission implies read access.

Permission Groups

Permission groups allow you to define reusable sets of permissions for roles.

Create Permission Group

Delete Permission Group

Example Groups

OP Management

Grant or revoke operator status for players:

Grant OP

Revoke OP

Note: OP management uses UUIDs, not player names. The plugin resolves names to UUIDs for you.

Data Storage

Permissions are stored in permissions.json on the server. The Java mod reads this file on startup and the panel can modify it via the API.

Game Translation System

For the item search and inventory editor, item names are translated using a priority chain:

13 locale mappings are supported. The gameLanguage setting ('auto' by default) follows the panel locale.

Troubleshooting

User can't access a feature

• Check which permission is required for that feature (see table above)
• Verify the user/subuser has the permission assigned
• Server owners have all permissions by default

Permission group creation fails

• Group name may already exist
• API connection lost
• permissions.json file locked or corrupted

OP status doesn't persist

• OP changes should persist across restarts (stored server-side)
• If not persisting, check permissions.json write permissions
• Server may overwrite permissions on certain events

Activity log shows "unknown" actor

• The admin username is passed from the panel session
• If session expired during action, actor may be empty

Permissions don't take effect immediately

• Some permission changes may require the affected user to refresh their page
• Server-side permission groups may need a server restart to reload

API Client & Internal Architecture

Full API endpoint documentation is available in the HytaleAdminAPI Reference. This section covers the PHP client that the panel plugin uses internally to communicate with the Hytale server mod. For endpoint parameters, response schemas, and request examples, see the HytaleAdminAPI documentation.

HytaleApiService — PHP Client

The panel plugin communicates with the Hytale server mod via a HytaleApiService class that wraps all HTTP calls. Every feature (Dashboard, Players, Chat, etc.) uses this service.

Client Configuration Parameters

// How the API service is constructed — from server allocation + egg variables
$allocation = $server->allocation;
$host = $allocation->ip;  // Server IP from allocation
$port = $server->egg_variable('HYTALE_API_PORT') ?? 8080;
$token = $server->egg_variable('HYTALE_API_TOKEN');

$service = new HytaleApiService($host, $port, $token);

// Base request method — all API calls go through this
protected function request(string $method, string $endpoint, array $data = []): array
{
    $response = Http::timeout($this->timeout)
        ->withToken($this->token)  // Bearer token
        ->withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
        ])
        ->{$method}("{$this->baseUrl}/{$endpoint}", $data);

    if ($response->failed()) {
        throw new HytaleApiException(
            "API {$method} /{$endpoint} failed: HTTP {$response->status()}",
            $response->status()
        );
    }

    return $response->json();
}

Request Flow — Panel to Server Mod

┌──────────────┐    HTTP/JSON     ┌─────────────────┐    Java API    ┌──────────────┐
│  Panel Plugin │ ──────────────> │ Hytale Mod HTTP  │ ──────────── > │ Hytale Server│
│  (PHP/Laravel)│ <────────────── │ Server (Netty)   │ < ──────────── │   (Game)     │
│               │    JSON response│                  │   Game state   │              │
└──────────────┘                  └─────────────────┘                └──────────────┘

Key architectural notes:

• The mod embeds a Netty HTTP server inside the Hytale server process
• All game-affecting operations (kick, ban, teleport) execute on the server main thread
• Read-only operations (status, player list) may use cached data
• The API is synchronous from the panel's perspective but internally queues to the game thread

Feature → API Endpoint Mapping

See HytaleAdminAPI Reference for request/response details of each endpoint.

BSON Item Data Handling

Hytale uses BSON (Binary JSON) for item serialization. The panel must handle encoding/decoding for inventory operations.

// Item data structure — as returned from the API
$item = [
    'id'       => 'hytale:wooden_sword',     // Namespaced item ID
    'count'    => 1,                          // Stack count
    'slot'     => 3,                          // Inventory slot index
    'nbt'      => [                           // BSON-encoded properties
        'damage'     => 15,
        'enchants'   => [
            ['id' => 'sharpness', 'level' => 3],
        ],
        'customName' => '§6Legendary Blade',  // Color-coded display name
    ],
];

// Give item to player — constructs BSON payload
$this->request('POST', "items/give", [
    'uuid'     => $playerUuid,
    'item_id'  => $itemId,       // e.g. 'hytale:iron_ore'
    'count'    => $count,
    'nbt_data' => $nbtData,      // Optional BSON properties
]);
// Executes on server main thread, item appears in player's inventory immediately

Player Data Merge (UUID Resolution)

The plugin handles UUID-to-name resolution with merge logic for players who change names.

// UUID resolution — the mod tracks players by UUID, panel displays names
$players = $this->request('GET', 'players');

// Each player has both UUID and current name
// The panel caches UUID→name mappings
// When a player renames, the old name is replaced on next login
foreach ($players as $player) {
    // $player['uuid']     => "550e8400-e29b-41d4-a716-446655440000"
    // $player['name']     => "Steve"
    // $player['position'] => { "x": 100.5, "y": 64.0, "z": -200.3 }
    // $player['gameMode'] => "SURVIVAL"
    // $player['health']   => 20.0
    // $player['food']     => 18
}

Caching Strategy

// Cache example — status with 5-second TTL
$status = Cache::remember("hytale_status_{$serverId}", 5, function () {
    return $this->apiService->getStatus();
});

Demo Mode Architecture

When the server is offline, the plugin enters demo mode — it shows mock data so admins can explore the UI without a running server.

// Demo mode detection — automatically activates when API is unreachable
try {
    $status = $this->apiService->getStatus();
    $demoMode = false;
} catch (HytaleApiException $e) {
    $demoMode = true;
    $status = $this->getDemoStatus();  // Returns hardcoded mock data
}

// Demo data includes:
// - 0 TPS, 0 players, all features show placeholder data
// - UI is fully interactive but changes are not sent to server
// - Yellow banner shows "Demo Mode — Server is offline"

API Client Error Map

Complete Error Reference (All Features)

Connection Errors

Authentication / Token Errors

Player Management Errors

Chat System Errors

World Management Errors

Backup System Errors

Server Configuration Errors

API Response Code Reference

Complete Notification Reference