tools: live debug HUD (gbhud.py) + 'gbctl hud'

Reads WRAM over the control socket, resolves addresses from pokeyellow.sym, and
pretty-prints game state (location, player pos/facing, movement+collision debug,
player name/money/badges, party nicknames/levels/HP bars) refreshing ~5Hz.
'gbctl hud' spawns it in a tmux split bound to the live instance.

1 files changed, 17 insertions, 1 deletions

diff --git a/gbctl b/gbctl
index 7eb521c..4c3d4f9 100755
--- a/gbctl
+++ b/gbctl
@@ -284,6 +284,22 @@ def cmd_screen(argv):
     r = subprocess.run(args, capture_output=True, text=True)
     sys.stdout.write(r.stdout)
 
+def cmd_hud(argv):
+    # spawn a tmux pane running the live debug HUD, bound to the resolved socket
+    sock_path = _resolve_sock(argv)
+    if "TMUX" not in os.environ:
+        die("not inside tmux; gbctl hud needs a tmux session")
+    hud = os.path.join(HERE, "tools", "gbhud.py")
+    split = "-h"
+    if "--split" in argv:
+        i = argv.index("--split"); split = {"h":"-h","v":"-v"}.get(argv[i+1],"-h")
+    cmd = "exec python3 %s --sock %s" % (_shquote(hud), _shquote(sock_path))
+    r = subprocess.run(["tmux", "split-window", split, "-P", "-F", "#{pane_id}", cmd],
+                       capture_output=True, text=True)
+    if r.returncode != 0:
+        die("tmux spawn failed: %s" % r.stderr.strip())
+    print("hud pane=%s sock=%s" % (r.stdout.strip(), sock_path))
+
 def cmd_monitor(argv):
     secs = float(argv[0]) if argv and _isnum(argv[0]) else None
     if secs is not None:
@@ -319,7 +335,7 @@ def _isnum(x):
 # main dispatch
 # ---------------------------------------------------------------------------
 LIFECYCLE = {"spawn": cmd_spawn, "list": cmd_list, "stop": cmd_stop,
-             "screen": cmd_screen, "monitor": cmd_monitor}
+             "screen": cmd_screen, "monitor": cmd_monitor, "hud": cmd_hud}
 
 # convenience aliases -> raw protocol verbs
 ALIASES = {"press": None, "tap": None, "hold": None, "buttons": None}