Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/status-heartbeat.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ on:
- 'src/Civ13/ServerHeartbeat.php'
- 'src/Civ13/PlayercountChannel.php'
- 'src/Civ13/PortableProfile.php'
- 'src/Civ13/RegionRoster.php'
- 'tests/local/heartbeat*.php'
- '.github/workflows/status-heartbeat.yml'

Expand Down Expand Up @@ -40,5 +41,7 @@ jobs:
- run: php tests/local/heartbeat.php
- run: php tests/local/heartbeat-integration.php
- run: php tests/local/heartbeat-playercount.php
- run: php -l src/Civ13/RegionRoster.php
- run: php tests/local/heartbeat-roster.php
- run: php -l src/Civ13/ServerPlayLink.php
- run: php tests/local/play-link.php
21 changes: 19 additions & 2 deletions docs/passive-server-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,25 @@ the other regions' worktree directories in `shards`, for example
Each region's `serverdata.txt` gets its own heartbeat, sampled on the same
15-second timer, and the channel shows the distinct ckeys across every advancing
world, so a traveller seen in two regions counts once. It reads `offline` only
when every world is stale or missing. The status and round embeds still describe
the server's own world. The current-round embed retains its existing one-minute update
when every world is stale or missing.

Instead of listing directories, a server can point `region_group` at the Civ13
shard group file, for example `"region_group": "D:/Civ13Regions/earth.json"`.
Every region in it (`<root>/<id>`) other than the server's own world is
watched under its group name, and the list follows the file: a region added to
or removed from the group is picked up on the next sample, without a bot
restart. An unreadable file keeps the last good list.

The status embed and the current-round embed in the player-count channel show
the same group-wide count in an `Online Players (N)` field, one line per region
with players (for example `**Gaia** (2): alice, bob`). Each ckey is listed once:
a traveller still listed by the region it left goes under the region it moved
to, and one listed by no region (between leaving one world and joining the
next) stays counted under *Between regions* for up to 30 seconds, so a trip
never drops the count. A logout shows there for that window too. When every
world is down nobody is listed. When the names do not fit in one embed field,
the field shows per-region counts. A server without shards keeps its plain
player list. The current-round embed retains its existing one-minute update
cadence. Remote/unobserved servers explicitly show unknown health and label
cached players unverified. This does not change the separate legacy serverinfo
web-service or verification-API indicators.
Expand Down
5 changes: 3 additions & 2 deletions docs/shard-group.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,9 @@ A region that belongs to another entry's group sets `'shard_of' => '<parent key>
- keeps its own webhooks (`/webhook/<key>`), rounds, bans, admin and verification
files, chat relays and round embed;
- never renames the player-count channel: the parent lists the region's
directory in `shards` and counts its players there (a player seen in both
worlds counts once);
directory in `shards` (or the whole group file in `region_group`, see
[passive-server-status.md](passive-server-status.md)) and counts its players
there, by region, each player once;
- never receives Discord OOC. A message in the shared OOC channel goes to the
parent world only, which shares it in game with the other regions (Civ13
`region_ooc.dm`, which needs the group's transfer agents).
Expand Down
128 changes: 116 additions & 12 deletions src/Civ13/GameServer.php
Original file line number Diff line number Diff line change
Expand Up @@ -152,8 +152,18 @@ class GameServer
public ?ServerPlayLink $playLink = null;
/** @var array<string, ServerHeartbeat> Shard region directory => its heartbeat. */
private array $shardHeartbeats = [];
/** @var list<array{state:string, reason:string, players:list<string>}> Last local observation of every world in the group. */
/** @var list<array{name?:string, state:string, reason:string, players:list<string>}> Last local observation of every world in the group. */
private array $worlds = [];
/** @var array<string, string> Shard region directory => its display name. */
private array $shardNames = [];
/** Display name of this server's own world in its group (the group file's region name). */
private string $regionName = '';
/** Civ13 shard group file (scripts/shard-group, for example D:/Civ13Regions/earth.json) whose regions are counted. */
private string $regionGroupFile = '';
/** @var array<string, true> Shard directories that came from the group file (re-read when it changes). */
private array $groupShards = [];
private ?string $regionGroupStamp = null;
private ?RegionRoster $roster = null;

/**
* @param Civ13 $civ13 The bot instance (held by reference).
Expand Down Expand Up @@ -291,6 +301,11 @@ public function __construct(public Civ13 &$civ13, array &$options)
}
$this->shardHeartbeats[rtrim($shard, '/\\')] = new ServerHeartbeat(rtrim($shard, '/\\').Civ13::serverdata);
}
// Or every region of a Civ13 shard group file, re-read when the group gains or loses regions.
if (is_string($options['region_group'] ?? null) && $options['region_group'] !== '') {
$this->regionGroupFile = $options['region_group'];
$this->loadRegionGroup();
}
$this->discord2unban = $this->basedir.Civ13::discord2unban;
$this->discord2ban = $this->basedir.Civ13::discord2ban;
$this->admins = $options['admin_file'] ?? $this->basedir.Civ13::admins;
Expand Down Expand Up @@ -412,18 +427,107 @@ private function refreshLocalServerStatus(): array

return ['state' => 'unknown', 'reason' => 'No enabled local heartbeat observation', 'age' => null, 'data' => null];
}
$this->loadRegionGroup();
$status = ($this->heartbeat ??= new ServerHeartbeat($this->serverdata))->poll();
$this->players = self::heartbeatPlayers($status);
$this->worlds = [['state' => $status['state'], 'reason' => $status['reason'], 'players' => $this->players]];
$worlds = [['name' => $this->regionName !== '' ? $this->regionName : $this->name, 'state' => $status['state'], 'reason' => $status['reason'], 'players' => $this->players]];
// Shards share the 15-second poll so each heartbeat keeps its own progress evidence.
foreach ($this->shardHeartbeats as $heartbeat) {
foreach ($this->shardHeartbeats as $directory => $heartbeat) {
$shard = $heartbeat->poll();
$this->worlds[] = ['state' => $shard['state'], 'reason' => $shard['reason'], 'players' => self::heartbeatPlayers($shard)];
$worlds[] = ['name' => $this->shardNames[$directory] ?? self::regionLabel((string) $directory), 'state' => $shard['state'], 'reason' => $shard['reason'], 'players' => self::heartbeatPlayers($shard)];
}
// One roster across the group: each ckey once, and a traveller between regions is not dropped.
$this->worlds = ($this->roster ??= new RegionRoster())->observe($worlds, hrtime(true) / 1e9);

return $status;
}

/** "D:/Civ13Regions/earth/northamerica" => "Northamerica", for a `shards` directory without a group name. */
private static function regionLabel(string $directory): string
{
return ucfirst(basename(str_replace('\\', '/', $directory)));
}

private static function samePath(string $a, string $b): bool
{
$normalize = fn (string $path): string => rtrim(str_replace('\\', '/', $path), '/');

return strcasecmp($normalize($a), $normalize($b)) === 0;
}

/**
* Reads the shard group file (Civ13 scripts/shard-group: `root` plus `regions[].id/name`; each region
* runs in <root>/<id>) and watches every region other than this server's own world. Only re-read when
* the file changes; an unreadable or malformed file keeps the last good region list.
*/
private function loadRegionGroup(): void
{
if ($this->regionGroupFile === '') {
return;
}
clearstatcache(true, $this->regionGroupFile);
$stamp = @filemtime($this->regionGroupFile).':'.@filesize($this->regionGroupFile);
if ($stamp === $this->regionGroupStamp) {
return;
}
$bytes = @is_file($this->regionGroupFile) ? @file_get_contents($this->regionGroupFile, false, null, 0, 1048577) : false;
$group = is_string($bytes) && strlen($bytes) <= 1048576 ? json_decode($bytes, true, 32) : null;
if (! is_array($group) || ! is_string($group['root'] ?? null) || $group['root'] === '' || ! is_array($group['regions'] ?? null)) {
if ($this->regionGroupStamp === null) {
$this->logger->warning("GameServer {$this->key}: region_group {$this->regionGroupFile} is unreadable; counting this world only.");
}
$this->regionGroupStamp = $stamp;

return;
}
$this->regionGroupStamp = $stamp;
$root = rtrim($group['root'], '/\\');
$listed = [];
foreach ($group['regions'] as $region) {
if (! is_array($region) || ! is_string($region['id'] ?? null) || preg_match('/^[A-Za-z0-9_-]{1,64}$/D', $region['id']) !== 1) {
continue;
}
$directory = $root.'/'.$region['id'];
$name = is_string($region['name'] ?? null) && trim($region['name']) !== '' ? trim($region['name']) : ucfirst($region['id']);
if (self::samePath($directory, $this->basedir)) {
$this->regionName = $name;

continue;
}
foreach (array_keys($this->shardHeartbeats) as $known) {
if (! isset($this->groupShards[$known]) && self::samePath((string) $known, $directory)) {
$this->shardNames[$known] = $name; // Also listed in `shards`: keep that heartbeat, name it.

continue 2;
}
}
$listed[$directory] = true;
$this->shardNames[$directory] = $name;
$this->shardHeartbeats[$directory] ??= new ServerHeartbeat($directory.Civ13::serverdata);
}
foreach (array_keys($this->groupShards) as $gone) {
if (! isset($listed[$gone])) {
unset($this->shardHeartbeats[$gone], $this->shardNames[$gone]);
}
}
$this->groupShards = $listed;
}

/** The group-wide "Online Players" field, grouped by region when this server heads a region group. */
private function addRosterField(Embed $embed): Embed
{
if ($this->roster === null || ! $this->worlds) {
return $embed;
}
$grouped = count($this->shardHeartbeats) > 0;
if (! $grouped && $this->roster->total() === 0) {
return $embed; // A lone world with nobody on keeps its old, field-less embed.
}
[$name, $value] = $this->roster->field($grouped);

return $embed->addFieldValues($name, $value, ! $grouped);
}

/** @return list<string> */
private static function heartbeatPlayers(array $status): array
{
Expand Down Expand Up @@ -712,10 +816,10 @@ public function createCurrentRoundEmbedMessageBuilder(): ?MessageBuilder
{
$status = $this->refreshLocalServerStatus();
if ($status['data'] === null) {
return $this->addPlayButton(Civ13::createBuilder()->addEmbed($this->heartbeatEmbed($status)));
return $this->addPlayButton(Civ13::createBuilder()->addEmbed($this->addRosterField($this->heartbeatEmbed($status))));
}
if (! $round = $this->getRound($this->current_round)) {
return $this->addPlayButton(Civ13::createBuilder()->addEmbed($this->heartbeatEmbed($status)));
return $this->addPlayButton(Civ13::createBuilder()->addEmbed($this->addRosterField($this->heartbeatEmbed($status))));
}
$round_embed_builder = function (array $round) use ($status): ?MessageBuilder {
$data = self::heartbeatServerdata($status['data']);
Expand All @@ -736,9 +840,7 @@ public function createCurrentRoundEmbedMessageBuilder(): ?MessageBuilder
if (isset($data[10])) {
$embed->addFieldValues('Season', $data[10], true);
}
if ($this->players) {
$embed->addFieldValues('Online Players ('.count($this->players).')', empty($this->players) ? 'N/A' : implode(', ', $this->players), true);
}
$this->addRosterField($embed);
$embed->addFieldValues(
'Participating Players ('.count($players = array_keys($round['players'])).')',
$players
Expand Down Expand Up @@ -2093,7 +2195,7 @@ public function generateServerstatusEmbed(): ?Embed
$status = $this->refreshLocalServerStatus();
$embed = $this->heartbeatEmbed($status);
if ($status['data'] === null) {
return $embed;
return $this->addRosterField($embed);
}
$data = self::heartbeatServerdata($status['data']);
if (isset($data['round_timer'])) {
Expand All @@ -2106,7 +2208,9 @@ public function generateServerstatusEmbed(): ?Embed
if (isset($data['epoch'])) {
$embed->addFieldValues('Epoch', $data['epoch'], true);
}
if (isset($data['ckey_list'])) { // Player list
if ($this->shardHeartbeats) { // Every region of the group, grouped by region
$this->addRosterField($embed);
} elseif (isset($data['ckey_list'])) { // Player list
$players = explode('&', $data['ckey_list']);
$players = array_filter(array_map(fn ($player) => Civ13::sanitizeInput($player), $players));
if (! $players_list = implode(', ', $players)) {
Expand Down Expand Up @@ -2238,7 +2342,7 @@ public function __toString(): string
public function __toArray(): array
{
$array = get_object_vars($this);
unset($array['civ13'], $array['heartbeat'], $array['shardHeartbeats'], $array['worlds']);
unset($array['civ13'], $array['heartbeat'], $array['shardHeartbeats'], $array['worlds'], $array['shardNames'], $array['groupShards'], $array['regionGroupStamp'], $array['roster']);

return $array;
}
Expand Down
4 changes: 4 additions & 0 deletions src/Civ13/PortableProfile.php
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ public static function load(string $file): array
if (!self::absoluteAdminFile($shard)) { throw new \InvalidArgumentException('shards needs absolute region directory paths'); }
}
}
if (array_key_exists('region_group', $server)) {
// A Civ13 shard group file (scripts/shard-group): every region in it is counted and listed by region.
if (!is_string($server['region_group']) || !self::absoluteAdminFile($server['region_group']) || !is_file($server['region_group'])) { throw new \InvalidArgumentException('region_group must be an existing absolute shard group file path'); }
}
foreach (['discussion','playercount','ooc','lobby','asay','ic','transit','adminlog','debug','garbage','runtime','attack'] as $field) {
if (!is_string($server[$field] ?? null) || ($server[$field] !== '' && !preg_match('/^[0-9]{17,20}$/D', $server[$field]))) { throw new \InvalidArgumentException('Explicit channel string required'); }
}
Expand Down
Loading
Loading