PHP client example

Eranio Published on: 14. October 2026

StreamBridge (Hytale): PHP client example

A simple PHP client that takes on the same role as the plugin: periodically poll the bridge endpoint, report your own status, and process the returned actions. Useful if you want to build your own integration against the same interface.

Base class

<?php

class StreamBridgeHytaleClient
{
    private string $url;
    private string $token;

    public function __construct(string $url, string $token)
    {
        $this->url = rtrim($url, '/') . '/api/v1/hytale/bridge';
        $this->token = $token;
    }

    /**
     * Reports the current state and fetches waiting actions.
     *
     * @param array $players List of online players
     * @param array $results Results of previously executed actions
     * @return array{actions: array, display: array}
     */
    public function poll(array $players = [], array $results = [], bool $paused = false): array
    {
        $ch = curl_init($this->url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode([
                'version' => '1.4.0',
                'paused' => $paused,
                'game' => 'hytale',
                'players' => $players,
                'results' => $results,
            ]),
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'Authorization: Bearer ' . $this->token,
            ],
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 10,
        ]);
        $response = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($status !== 200) {
            throw new RuntimeException("Bridge request failed (HTTP {$status}): {$response}");
        }

        return json_decode($response, true) ?? ['actions' => [], 'display' => []];
    }
}

Usage

$client = new StreamBridgeHytaleClient('https://your-panel.example', 'your-token');

$players = [
    ['name' => 'Steve', 'health' => 20, 'max_health' => 20, 'food' => 20, 'level' => 0,
     'world' => 'default', 'dimension' => '', 'gamemode' => 'survival', 'effects' => [], 'timers' => []],
];

$result = $client->poll($players);

foreach ($result['actions'] as $action) {
    $color = ($action['group'] ?? '') === 'sabotage' ? 'red' : 'green';
    echo "Action {$action['action']} for {$action['player']} from {$action['viewer']} (display: {$color})\n";
    // Execute the action in your own game/server here ...

    // Then report the result on the next poll() call:
    // $results[] = ['id' => $action['id'], 'ok' => true, 'detail' => null];
}

if ($result['display']['live'] ?? false) {
    echo "{$result['display']['streamer']} is currently live on {$result['display']['platform']}!\n";
}

Important: every received action must be acknowledged in the results array (with its id) on the next poll() call, otherwise it keeps counting as still open.

FAQ

What does the group field on an action mean? It shows whether the action is classified as sabotage (sabotage) or not (empty). On StreamBridge-Hytale this only controls the title display color, you can use it for your own purposes in your own integration.

How often should I call poll()? The real plugin polls every 1000 milliseconds by default (see pollIntervalMs in the configuration).

What happens if I don't report a result? The action stays "sent but unconfirmed" and the server never records it as successful.