feat(client): T-1132 standalone Atlas companion shell + make atlas (D-254 SS3)

New atlas_standalone scene/script: attach-or-spawn boot (one REAL
connect_to_sim attempt at SR_PORT-or-9876 — a separate throwaway TCP
probe was proven by live run to kill a pre-accept-loop server via
broken handshake pipe; never abandon a connected socket), else spawn
--port 0 via new ServerProcess.start_with_pipe + LISTENING:{port}
stdout parse, retry against the resolved port. Reader role wired end
to end: protocol.encode_startup_message optional role param (empty
omits the wire key — byte-identical for all existing callers),
sim_bridge.connection_role suppresses the post-handshake
RequestAllSettings auto-send, hud_groups skips AutoPause/AutoResume
sends for readers (all three would otherwise burn Reader violation
strikes per the T-1130 matrix — endorsed by Oscar).

Generic implant host per D-254 SS3: the shell instantiates ALL
registered implant apps; implant_app_manifest gains
available_in_companion (opt-out, default true) and
implant_registry.instantiate_all a standalone filter param (default
preserves hud.gd behavior byte-identically). Boot order is
instantiate_all THEN open_app (reverse renders a permanently black
window — app_changed fires with no listener; matches hud.gd's order).
Owned-server lifecycle: _exit_tree stops a spawned child, attached
servers survive companion close. Known engine limitation documented:
raw SIGTERM bypasses all Godot notifications and orphans a spawned
server; WM close paths verified clean.

Live-verified: spawn-mode (301 systems rendered from systems.db over
the wire), attach-mode, two simultaneous readers, clean shutdown with
zero orphan processes. 14 new gdUnit tests (port/LISTENING parsing).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-17 09:09:09 +02:00
co-authored by Claude Fable 5
parent ddc3d39d09
commit cffe760d36
10 changed files with 538 additions and 5 deletions
+9 -1
View File
@@ -639,14 +639,22 @@ static func _decode_enum_variant(raw) -> Dictionary:
## Sent by the client immediately after handshake validation.
## Server reads this to initialize SimRng (D-010, D-029).
## character_visual: optional CharacterVisualDescriptor — included as "character_visual_descriptor" dict.
## role: D-254 §2 ConnectionRole wire value — "" (default, every caller before
## D-254) omits the "role" key entirely, matching server StartupMessage::role's
## #[serde(default)] and decoding as ConnectionRole::Player — byte-identical to
## pre-D-254 output. atlas_standalone.gd is the one caller that passes "Reader"
## (unit enum variant, bare string per this file's header wire-format note —
## same encoding as PlayerAction unit variants like "MoveNorth").
static func encode_startup_message(
world_seed: int, character_visual: Variant = null
world_seed: int, character_visual: Variant = null, role: String = ""
) -> PackedByteArray:
var msg := {
"world_seed": world_seed,
}
if character_visual != null and character_visual.has_method("to_dict"):
msg["character_visual_descriptor"] = character_visual.to_dict()
if not role.is_empty():
msg["role"] = role
var result = _mp().encode(msg)
if result.status != null:
push_error("Protocol: startup message encode failed: %s" % result.status)
+40
View File
@@ -2,6 +2,9 @@ class_name ServerProcess
## Manages the Rust simulation server as a subprocess (D-020).
var _pid: int = -1
## Populated only by start_with_pipe() — the stdout FileAccess handle used to
## read the LISTENING:{port} signal (D-254 §1/§3). Null after plain start().
var _stdio: FileAccess = null
## Start the server process. Returns the PID, or -1 on failure.
@@ -19,6 +22,43 @@ func start(server_path: String, args: Array = []) -> int:
return _pid
## Start the server process with its stdout piped back to this process
## (D-254 §1/§3: the companion app's --port 0 spawn-mode, which needs to read
## the LISTENING:{port} signal main.rs prints — see server/src/main.rs). Unlike
## start()/OS.create_process, this uses OS.execute_with_pipe, which does not
## block (the shell precedent, tests/run-visual, achieves the same read via a
## redirected log file + `grep` from a wrapper script; this is the Godot-native
## equivalent for a caller with no shell wrapper). Returns the PID, or -1 on
## failure. Call read_stdout_line() from a per-frame poll to drain the pipe.
func start_with_pipe(server_path: String, args: Array = []) -> int:
if _pid > 0 and is_alive():
push_warning("ServerProcess: server already running (pid %d)" % _pid)
return _pid
if not FileAccess.file_exists(server_path):
push_error("ServerProcess: server binary not found at %s" % server_path)
return -1
var result: Dictionary = OS.execute_with_pipe(server_path, args)
if not result.has("pid") or int(result.get("pid", -1)) <= 0:
push_error("ServerProcess: failed to start server (pipe) at %s" % server_path)
return -1
_pid = int(result["pid"])
_stdio = result.get("stdio", null)
return _pid
## Non-blocking read of one line from the piped server's stdout, or "" if no
## complete line is buffered yet (FileAccess.get_line() on a pipe never
## blocks — it returns immediately with whatever is currently available).
## Only meaningful after start_with_pipe(); returns "" if _stdio was never set
## (plain start()) or the process has exited (stream at EOF).
func read_stdout_line() -> String:
if _stdio == null:
return ""
if _stdio.get_error() != OK:
return ""
return _stdio.get_line()
## Check if the server process is still running.
## NOTE: OS.is_process_running() doesn't distinguish starting/healthy/zombie.
## TODO: Add health check (e.g. TCP readiness probe) when server supports it.