Show sleep state and every region in host status

src/Civ13/Local/GaiaHostControl.php

@@ -44,7 +44,11 @@ public function request(string $action): PromiseInterface
     /** One line for Discord from a status answer. */
     public static function describe(array $status): string
     {
-        $parts = [($status['listening'] ?? false) ? 'Server port is open.' : 'Server is not running.'];
+        $parts = [match ($status['state'] ?? null) {
+            'asleep' => 'Server is asleep (frozen in memory; a join or travel wakes it).',
+            'cold' => 'Server is asleep (stopped after its last save; a join or travel starts it).',
+            default => ($status['listening'] ?? false) ? 'Server port is open.' : 'Server is not running.',
+        }];
         $world = $status['world'] ?? null;
         if (is_array($world)) {
             $parts[] = ($world['ready'] ?? false) ? 'World ready' : 'World not ready';
@@ -57,7 +61,16 @@ public static function describe(array $status): string
             if (is_string($operation['error'] ?? null) && $operation['error'] !== '') { $line .= ': '.substr($operation['error'], 0, 200); }
             $parts[] = $line;
         }
-        return implode(' ', array_map(static fn ($part) => str_ends_with($part, '.') ? $part : $part.'.', $parts));
+        $line = implode(' ', array_map(static fn ($part) => str_ends_with($part, '.') ? $part : $part.'.', $parts));
+        // A region host (Civ13 scripts/shard-group) also lists every region of its group.
+        $regions = [];
+        foreach (is_array($status['regions'] ?? null) ? array_slice($status['regions'], 0, 16) : [] as $region) {
+            if (!is_array($region) || !is_string($region['name'] ?? null) || !is_string($region['state'] ?? null)) { continue; }
+            $name = substr(preg_replace('/[^\w \-\'().]/u', '', $region['name']) ?? '', 0, 64);
+            $state = preg_replace('/[^a-z]/', '', $region['state']) ?? '';
+            $regions[] = "{$name}: {$state}".(is_int($region['players'] ?? null) ? ", {$region['players']} players" : '');
+        }
+        return $regions === [] ? $line : $line."\nRegions: ".implode('; ', $regions).'.';
     }
 
     private static function absolute(string $path): bool { return str_starts_with($path, '/') || (bool) preg_match('/^[A-Za-z]:[\\\\\/]/', $path); }

tests/local/gaia-host.php

@@ -42,6 +42,10 @@ function gaiaCheck(bool $ok, string $what): void { if (!$ok) { throw new Runtime
     [$status, $error] = $run('status');
     gaiaCheck($error === null && $status['world']['clients'] === 3, 'status answer');
     gaiaCheck(GaiaHostControl::describe($status) === 'Server port is open. World ready. 3 players. Last action: stop (done).', 'status line: '.GaiaHostControl::describe($status));
+    $region = ['listening' => true, 'state' => 'awake', 'world' => ['ready' => true, 'clients' => 2],
+        'regions' => [['id' => 'gaia', 'name' => 'Gaia', 'state' => 'awake', 'players' => 2], ['id' => 'deep', 'name' => 'The Deep <@&1>', 'state' => 'asleep', 'players' => null], 'junk']];
+    gaiaCheck(GaiaHostControl::describe($region) === "Server port is open. World ready. 2 players.\nRegions: Gaia: awake, 2 players; The Deep 1: asleep.", 'region line: '.GaiaHostControl::describe($region));
+    gaiaCheck(str_starts_with(GaiaHostControl::describe(['state' => 'cold', 'listening' => false]), 'Server is asleep (stopped'), 'cold line');
     [$value, $error] = $run('start');
     gaiaCheck($value === null && $error instanceof RuntimeException && $error->getMessage() === 'Refused: the server is already running', 'refusal text');
     [$value, $error] = $run('stop');