Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

[!TIP] AI-Assisted Install: Just tell any AI assistant:
Set up game-server-admin from https://github.com/hyperpolymath/game-server-admin
The AI reads the manifest, asks you a few questions, and handles everything.

Overview

Game-server discovery, configuration management, and administration — built on Gossamer (linearly-typed webview shell) and backed by VeriSimDB. GSA aims to remain game-neutral; the current 18-profile registry is a legacy compatibility inventory, not a universal server contract.

GSA provides a set of protocol probes, a legacy registry of game profiles, configuration extraction/editing paths, and a GUI. The current registry still loads the existing profiles/*.a2ml corpus for compatibility; A2ML is retired by the current standards and is not a format for new profiles. A draft, versioned JSON profile/config validator now exists only as a fixture-tested slice; it is not wired into the GUI, public ABI, deployment path, or a live game adapter. See docs/developer/GAME-PROFILE-CONTRACT.adoc for the boundary and open maintainer decisions.

New in this version: User-configurable server connections with support for default servers and favorites list. See Configuration for details.

Architecture

┌─────────────────────────────────────────────────┐
│  Gossamer GUI (Ephapax + HTML/JS)               │
│  8 panels, each a Clade citizen with inheritance │
└────────────────────┬────────────────────────────┘
                     │ IPC (gossamer:// bridge)
┌────────────────────┴────────────────────────────┐
│  Probe Engine (Ephapax + Zig FFI)               │
│  Protocol fingerprint → game profile → config   │
└────────────────────┬────────────────────────────┘
                     │ REST (localhost:8090)
┌────────────────────┴────────────────────────────┐
│  VeriSimDB Instance (gsa-verisimdb)             │
│  8 modalities per server, drift detection       │
└─────────────────────────────────────────────────┘

Panels

Panel	Kind	Description
Server Browser	inspector	Discover/fingerprint servers, add to management
Config Editor	editor	Legacy profile-backed config forms; the draft generic validator is fixture-only and not wired into the GUI
Server Actions	terminal	Start/stop/restart with confirmation
Live Logs	terminal	Real-time log streaming with ANSI color
Health Dashboard	scanner	VeriSimDB drift detection and health gauges
Config History	database	Temporal version timeline with diff viewer
Cross-Server Search	database	VQL full-text + vector search across configs

All panels are registered in the PanLL Clade system with inheritance. The existing game-profile clades correspond to the legacy profile corpus; the fixture-only JSON contract does not generate production profiles or clades.

Supported Games (Initial)

Valheim, Barotrauma, Don’t Starve Together, Minecraft Java/Bedrock, Factorio, Terraria, ARK, Rust (game), CS2, Garry’s Mod, Project Zomboid, Starbound, DayZ, Void Expanse — plus IDApTIK and Burble.

Quick Start

# Start the VeriSimDB instance
just verisimdb-up

# Build and run the CLI
just run status              # system status, VeriSimDB health, loaded profiles
just run probe <host> [port] # fingerprint a game server (default port 27015)
just run profiles            # list all 18 supported game profiles

# Or build and launch the GUI
just build && just gui

CLI Reference

The gsa binary is built automatically by zig build and lives at src/interface/ffi/zig-out/bin/gsa.

Command	Description
gsa status	VeriSimDB health, build info, loaded game profiles
gsa probe <host> [port]	Fingerprint a game server (Steam, Minecraft, RCON, HTTP, TCP banner)
gsa profiles	JSON listing of all supported games with engine/port/config details
gsa version	Print version string
gsa help	Usage information

Environment variables: GSA_VERISIMDB_URL (default http://localhost:8090), GSA_PROFILES_DIR (default ./profiles).

Game Profiles and the Compatibility Boundary

The runtime registry still loads the existing profiles/*.a2ml corpus. Those files are a legacy dependency: do not create, restore, regenerate, or extend A2ML profiles, and do not bulk-rewrite the existing corpus. The registry has not yet been migrated to a new canonical profile format.

A draft JSON descriptor and field validator are available at schemas/game-profile-draft-0.1.schema.json and src/interface/ffi/src/profile_contract.zig. The SOP example under fixtures/standard-operating-psychopathy/ is synthetic design data, not a live server contract. The validator is currently exercised only by Zig tests; it is not connected to the production registry, C ABI, GUI, deployment actions, or a real adapter. It cannot establish server reachability or operational status.

Before a stable contract or migration, maintainers must decide the canonical serialization/schema, versioning and ownership, the mapping for legacy profiles, and any session-data authorization/retention/audit requirements. See docs/developer/GAME-PROFILE-CONTRACT.adoc and the docs/reports/quality/2026-10-18-game-profile-recon.adoc recon report.

ABI/FFI Standard

• ABI (Idris2): src/interface/abi/ — formal type specs with dependent type proofs

• FFI (Zig): src/interface/ffi/ — C-compatible implementation

• Core (Ephapax): src/core/ — linear type enforcement for resource safety

VeriSimDB Integration

Each managed server is a VeriSimDB octad with all 8 modalities:

• Graph: server→game-profile, server→cluster edges

• Vector: config embedding for similarity search

• Tensor: performance metrics over time

• Semantic: game type, version, mods, status

• Document: existing legacy config representation (A2ML output; not a new canonical contract)

• Temporal: every config version with timestamp

• Provenance: who changed what, when, why (hash-chain)

• Spatial: datacenter geolocation

Dedicated instance on port 8090 with persistent storage and 15s drift detection.

Configuration

GSA now supports user-specific configuration through a Nickel (.ncl) configuration file. This allows you to:

• Set a default server IP and port

• Maintain a list of favorite servers

• Customize UI preferences

• Configure connection settings

Initial Setup

To create a default configuration file:

./gsa config init

This creates user-config.ncl from the template.

Configuration Commands

# Show current configuration
./gsa config show

# Set default server
./gsa config set-default mc.example.com 25565

# Add a favorite server
./gsa config add-favorite "My Minecraft" mc.example.com 25565

# List favorite servers
./gsa config list-favorites

Configuration File

The configuration file (user-config.ncl) is gitignored to ensure your server credentials remain private. See USER-CONFIG.md for complete documentation.

License

SPDX-License-Identifier: CC-BY-SA-4.0

Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>