godot-cli-control 0.2.5__tar.gz → 0.2.7__tar.gz

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.5
+Version: 0.2.7
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/addons/godot_cli_control/README.md

@@ -93,11 +93,12 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 | `action_press(action)` | `await client.action_press("jump")` |
 | `action_release(action)` | `await client.action_release("jump")` |
 | `action_tap(action, duration)` | `await client.action_tap("attack", 0.1)` |
-| `input_get_pressed` (raw RPC) | `await client.request("input_get_pressed")` |
 | `hold(action, duration)` | `await client.hold("run", 1.5)` |
 | `combo(steps)` | `await client.combo([{"action": "jump", "duration": 0.1}])` |
 | `combo_cancel()` | `await client.combo_cancel()` |
 | `release_all()` | `await client.release_all()` |
+| `get_pressed()` | `await client.get_pressed()` |
+| `list_input_actions(include_builtin=False)` | `await client.list_input_actions()` |
 
 ### Error codes
 
@@ -110,7 +111,7 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 | `1003` | server | Method not found on the node (schema error, don't retry) |
 | `1004` | server | Combo already in progress (call `combo-cancel` to retry) |
 | `1005` | server | Scene tree too large (lower `depth` or pass `--max-nodes`) |
-| `1006` | server | Resource transiently unavailable (e.g. screenshot before viewport ready) — safe to retry |
+| `1006` | server | Resource transiently unavailable (e.g. screenshot during scene transition). Rare under normal use — GameBridge waits for viewport first-frame before listening, and `screenshot` retries internally. Safe to retry if you do hit it. |
 | `-32600` | server | Malformed JSON-RPC request |
 | `-32601` | server | Unknown method name |
 | `-32602` | server | Invalid params (incl. blocked methods/properties from the security blacklist, or `set` value-type mismatch — e.g. `Vector2` property given an array of wrong length / non-numeric elements) |

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/addons/godot_cli_control/bridge/error_codes.gd

@@ -16,6 +16,11 @@ const COMBO_IN_PROGRESS: int = 1004
 const SCENE_TREE_TOO_LARGE: int = 1005
 # 资源 transient 不可用（screenshot viewport texture null 等）。
 # 与 1003 拆开：1003 是 schema 错（永久），1006 是时机错（短重试可能成功）。
+# issue #61 落地后语义：GameBridge 启动 gate（H）保证 client 连上时 viewport
+# 至少画过一帧 + take_screenshot_async 内部循环（D）兜底动态 transient，
+# 所以正常用法下 1006 不应触发。但它仍是 last-resort 合法信号 ——
+# client 必须保留对 1006 的处理（不要假设它消失），未来若改为 fail-loud
+# 会让 scene 切换瞬间的截图变成硬错。
 const RESOURCE_UNAVAILABLE: int = 1006
 
 const INVALID_PARAMS: int = -32602

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/addons/godot_cli_control/bridge/game_bridge.gd

@@ -6,6 +6,11 @@ const DEFAULT_PORT: int = 9877
 const SETTING_AUTO_ENABLE: String = "godot_cli_control/auto_enable_in_debug"
 const SETTING_OUTBOUND_BUFFER_MB: String = "godot_cli_control/outbound_buffer_mb"
 const DEFAULT_OUTBOUND_BUFFER_MB: int = 10
+# 启动 gate：listen 前等 viewport 首帧 ready 的上限帧数。
+# 60fps 下 ~2s；shader 编译 / 大资源加载超过这个就走 fallback —— 仍开端口，
+# 把后续 screenshot 的 transient 兜底交给 take_screenshot_async 的循环。
+# 设计意图见 issue #61：根因消除（H）+ handler 内动态兜底（D）。
+const FIRST_FRAME_READY_MAX_FRAMES: int = 120
 
 var _tcp_server: TCPServer = TCPServer.new()
 var _active_peer: WebSocketPeer = null
@@ -56,6 +61,13 @@ func _ready() -> void:
 		ProjectSettings.get_setting(SETTING_OUTBOUND_BUFFER_MB, DEFAULT_OUTBOUND_BUFFER_MB)
 	)
 	_outbound_buffer_size = max(1, mb) * 1024 * 1024
+	# 启动 gate：等 viewport 首帧 ready 后再开 listen。
+	# 根因：issue #61。screenshot 在「viewport 从未画过一次」时拿到 null
+	# texture → 报 1006 transient；让 client connect 上来这件事本身就承诺
+	# 「至少画过一帧」，把根因消除而不是各 handler 各自打补丁。
+	# 超时不阻塞 listen —— 端口冲突 / 启动诊断信号要保留（_tcp_server.listen
+	# 失败的 printerr 在端口冲突时是用户唯一的 root cause 提示）。
+	await _wait_first_frame_ready()
 	# 启动 TCP 服务器
 	_port = _parse_port_from_args()
 	# 安全：显式绑 127.0.0.1，避免 Godot TCPServer 默认 "*" 暴露到 LAN
@@ -81,6 +93,23 @@ func _ready() -> void:
 		print("GameBridge: idle-timeout %ds enabled" % _idle_timeout_secs)
 
 
+func _wait_first_frame_ready() -> void:
+	# dummy renderer (--headless) 下 RenderingServer.frame_post_draw 永不发射；
+	# 与 take_screenshot_async 用同一套检测，dummy 路径走 process_frame ×2。
+	# 上限 FIRST_FRAME_READY_MAX_FRAMES 后无论 viewport 是否 ready 都返回，
+	# 让 listen 不被 GPU 卡死 / 大场景首帧拖住，避免 daemon 启动绑架到项目复杂度。
+	var dummy: bool = RenderingServer.get_rendering_device() == null
+	if dummy:
+		await get_tree().process_frame
+		await get_tree().process_frame
+		return
+	for _i in FIRST_FRAME_READY_MAX_FRAMES:
+		await RenderingServer.frame_post_draw
+		var image: Image = get_viewport().get_texture().get_image()
+		if image != null:
+			return
+
+
 func _process(_delta: float) -> void:
 	if not _tcp_server.is_listening():
 		return

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/addons/godot_cli_control/bridge/low_level_api.gd

@@ -14,6 +14,10 @@ const _BUILD_TREE_HARD_LIMIT: int = 50
 const _BUILD_TREE_NODE_LIMIT: int = 5000
 # wait_game_time_async 防呆上限：防止误传 1e9 之类的数值挂死 session
 const _MAX_WAIT_SECONDS: float = 3600.0
+# take_screenshot_async 循环上限：常态下 GameBridge 启动 gate 已保证 viewport
+# ready（issue #61 H 部分），这个循环只兜动态 transient（scene transition、
+# 窗口 resize 一瞬）。30 帧 ~500ms @ 60fps，超时报 1006 给 client 兜底。
+const SCREENSHOT_MAX_FRAMES: int = 30
 
 # ProjectSettings 路径：第三方项目通过这两条额外补 ban 自家属性 / 方法。
 # 合并到内置黑名单（去重，不能减只能加 —— 不开放 unban 是为了防止误删安全网）。
@@ -416,13 +420,25 @@ func take_screenshot_async() -> Dictionary:
 	# dummy renderer (--headless) 下 RenderingServer.frame_post_draw 永不发射，
 	# await 会永久挂死。RenderingServer.get_rendering_device() 在 dummy driver
 	# 下返回 null，用它检测后改走 process_frame 推进路径。
-	if RenderingServer.get_rendering_device() == null:
-		# dummy 路径：连续推 2 帧，让 viewport 跑一次完整 update
-		await get_tree().process_frame
-		await get_tree().process_frame
-	else:
-		await RenderingServer.frame_post_draw
-	var image: Image = get_viewport().get_texture().get_image()
+	# windowed 下循环等到 ready 是 issue #61 的 D 部分：兜底动态 transient
+	# （scene 切换 / 窗口 resize 一瞬）。常态下 GameBridge._wait_first_frame_ready
+	# 已经保证 client 连上 = viewport 至少画过一帧（H），所以通常第一次就拿到 image。
+	# SCREENSHOT_MAX_FRAMES 后仍 null 才报 1006 —— 1006 是 last-resort 兜底，
+	# 仍是合法 transient（client 仍应处理）。
+	# dummy 路径只试一次：headless 下 viewport texture 永远拿不到 image（无真 GPU），
+	# 循环 N 次只会让 Godot 内部 "Parameter t is null" push_error 噪音放大 N 倍。
+	var dummy: bool = RenderingServer.get_rendering_device() == null
+	var max_iters: int = 1 if dummy else SCREENSHOT_MAX_FRAMES
+	var image: Image = null
+	for _i in max_iters:
+		if dummy:
+			await get_tree().process_frame
+			await get_tree().process_frame
+		else:
+			await RenderingServer.frame_post_draw
+		image = get_viewport().get_texture().get_image()
+		if image != null:
+			break
 	if image == null:
 		# 1006 (transient) ≠ 1003 (schema)：agent 可短重试，等下一帧 viewport 就绪。
 		return _err(CliControlErrorCodes.RESOURCE_UNAVAILABLE, "Screenshot unavailable (viewport texture is null)")

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/addons/godot_cli_control/tests/gut/test_game_bridge.gd

@@ -405,3 +405,26 @@ func test_check_idle_resets_activity_when_busy() -> void:
 	_bridge._check_idle()
 	var now: int = Time.get_ticks_msec()
 	assert_almost_eq(_bridge._last_activity_ms, now, 200, "busy 时 _check_idle 必须把活动戳推到 ~now")
+
+
+# ── 启动 gate (issue #61 H 部分) ─────────────────────────────────
+# GUT 跑 --headless → RenderingServer.get_rendering_device() == null → dummy 路径。
+# 真 windowed 路径无法在 GUT 内测（要真 GPU），靠 e2e 覆盖。
+
+func test_wait_first_frame_ready_returns_under_headless() -> void:
+	# 关键防回归：dummy 路径不能 await frame_post_draw（永不发射 → 死锁）。
+	# 用 process_frame 推两帧应在毫秒级返回，否则函数被误改成走 windowed 分支。
+	# 必须 add_child 进 tree，否则 await get_tree().process_frame 拿不到 tree。
+	if _bridge.is_inside_tree():
+		_bridge.get_parent().remove_child(_bridge)
+	add_child_autofree(_bridge)
+	var t0: int = Time.get_ticks_msec()
+	await _bridge._wait_first_frame_ready()
+	var elapsed_ms: int = Time.get_ticks_msec() - t0
+	# 2s 余量，正常应在 < 100ms 返回
+	assert_lt(elapsed_ms, 2000, "_wait_first_frame_ready 在 headless 下必须秒返不死锁")
+
+
+func test_first_frame_ready_max_frames_constant_is_positive() -> void:
+	# 防回归：常量被改成 0 或负数会让循环立刻退出 → 启动 gate 失效。
+	assert_gt(GameBridgeScript.FIRST_FRAME_READY_MAX_FRAMES, 0)

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/addons/godot_cli_control/tests/gut/test_low_level_api.gd

@@ -694,3 +694,26 @@ func test_node_exists_false_for_missing_path() -> void:
 		"path": "/root/__missing__",
 	})
 	assert_false(result.get("exists"))
+
+
+# ── take_screenshot_async（issue #61 D 部分）──────────────────────
+# GUT 跑在 --headless 下，RenderingServer.get_rendering_device() == null，
+# 走 dummy 推帧路径。这两条测试主要防 await 死锁回归（早期版本一次没等
+# 到 ready 就报 1006，绕过 H 启动 gate 后会再撞）。
+
+func test_screenshot_returns_image_or_1006_under_headless() -> void:
+	# headless 下 viewport texture 可能是 null（dummy 无真实 RenderingDevice）。
+	# 合法结果：要么拿到 base64 image，要么循环跑满后报 1006。
+	# 关键不变量：函数必须返回（不死锁）、不抛、payload 形状正确。
+	var result: Dictionary = await _api.take_screenshot_async()
+	assert_true(result.has("image") or result.has("error"),
+		"take_screenshot_async must return image or error envelope")
+	if result.has("error"):
+		var err: Dictionary = result["error"] as Dictionary
+		assert_eq(int(err.get("code")), 1006,
+			"headless null viewport must report RESOURCE_UNAVAILABLE not other code")
+
+
+func test_screenshot_max_frames_constant_is_positive() -> void:
+	# 防回归：常量被改成 0 或负数会让循环立刻退出 → 等同未修。
+	assert_gt(LowLevelApiScript.SCREENSHOT_MAX_FRAMES, 0)

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/python/godot_cli_control/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.2.7'
+__version_tuple__ = version_tuple = (0, 2, 7)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/python/godot_cli_control/cli.py

@@ -670,7 +670,7 @@ RPC_SPECS: tuple[RpcSpec, ...] = (
         handler=cmd_wait_time,
         description="按 game time 等待 N 秒（在 --write-movie 模式下与录像帧对齐）。",
         positionals=(
-            Positional("seconds", None, "等待秒数（>0）"),
+            Positional("seconds", None, "等待秒数（服务端范围 0 ≤ seconds ≤ 3600；client 在 ≤0 时短路返回成功）"),
         ),
         example="wait-time 0.5",
         text_formatter=_fmt_wait_time_text,

{godot_cli_control-0.2.5 → godot_cli_control-0.2.7}/python/godot_cli_control/templates/skill/SKILL.md

@@ -42,7 +42,8 @@ godot-cli-control daemon stop
 |---|---|
 | 0 | Success (or, for `exists` / `visible` / `wait-node`, the boolean was true / found) |
 | 1 | RPC error (server returned `{"error":...}`); also `exists`/`visible`=false, `wait-node`=timeout, `daemon status`=stopped |
-| 2 | Connection / IO / usage error (daemon not running, malformed `combo` input, etc.) |
+| 2 | Connection / IO / usage error (daemon not running, malformed `combo` input, script path not found). Also: **`daemon stop` returns 2** when the daemon stopped cleanly but `ffmpeg` transcode of the recorded `.avi`→`.mp4` failed — the raw `.avi` is kept and `.cli_control/ffmpeg.log` has the details. `run <script>` propagates this: a successful script + failed transcode still exits 2. |
+| 3 | `daemon stop --all` partial failure: at least one daemon in the registry failed to stop. Per-record `rc` is in the JSON `result.stopped[]`. |
 | 64 | Argparse usage error |
 
 Shell-`if` works:
@@ -53,6 +54,22 @@ if godot-cli-control exists /root/Main/Boss; then
 fi
 ```
 
+## Daemon management
+
+```bash
+godot-cli-control daemon start             # boot daemon for cwd project
+godot-cli-control daemon status            # exit 0 = running, 1 = stopped
+godot-cli-control daemon stop              # stop cwd-project daemon (rc 0; rc 2 = ffmpeg transcode failed)
+godot-cli-control daemon stop --project /path/to/other/godot/project
+godot-cli-control daemon stop --all        # stop every registered daemon; exit 3 if any failed
+godot-cli-control daemon ls                # list all running daemons (cross-project, walks the registry)
+```
+
+- **`daemon status` payload when running**: `{"state": "running", "pid": N, "port": M}`.
+- **`daemon status` payload when stopped**: `{"state": "stopped"}`. If the previous launch wrote `.cli_control/godot.log` or recorded an exit code, the envelope also includes `"last_log": "<path>"` and/or `"last_exit_code": <int>` — use these to diagnose why the daemon died without manually grepping under `.cli_control/`.
+- **`daemon ls` payload**: `{"daemons": [{"project_root", "pid", "port", "started_at", "godot_bin", "log_path"}, ...]}`. Dead records (PID gone) are auto-pruned on each call, so this is the canonical list of *actually-alive* daemons across all projects on the machine.
+- **`daemon stop --all` payload**: `{"stopped": [{"project_root","pid","port","rc"[, "error"]}, ...], "rc": 0|3}`. Each entry's `rc` is the per-project stop result; the top-level `rc` is the aggregate exit code.
+
 ## JSON envelope examples
 
 ```bash
@@ -90,10 +107,10 @@ Three numeric ranges cohabit in `error.code`. Knowing which is which lets you de
 |---|---|
 | `1001` | Node not found at the given path. Most common — usually the agent passed a wrong / not-yet-loaded path. Retry after `wait-node`. |
 | `1002` | Property not found on the node, or shape mismatch (e.g. `text` on a node that doesn't have it). Don't retry; inspect with `tree`. |
-| `1003` | Method not found on the node. Schema error — don't retry, inspect with `tree`. |
+| `1003` | Method not found on the node, **or** unknown InputMap action passed to `press`/`release`/`tap`/`hold`/`combo` (`"Unknown action: <name>"`). Schema error — don't retry. For node methods inspect with `tree`; for missing actions run `actions` (or `actions --all`). |
 | `1004` | Combo already in progress. Call `combo-cancel` (or `release-all`) and re-issue. Safe to retry after that. |
 | `1005` | Scene tree too large to serialize (default safety limit). Pass `--max-nodes` or query a subtree with `children` / `tree <subpath>`. Don't retry as-is. |
-| `1006` | Resource transiently unavailable (e.g. screenshot before viewport renders the first frame). Safe to retry after `wait-time 0.05` or similar. |
+| `1006` | Resource transiently unavailable (e.g. screenshot during scene transition / window resize). Rare under normal use: GameBridge waits for viewport first-frame before accepting connections, and `screenshot` retries internally up to ~30 frames (~500ms at 60 fps, ~1s at 30 fps, longer when `--write-movie` lowers the fixed fps). If you still see this, retry after `wait-time 0.05` or similar. |
 
 **JSON-RPC standard — negative integers `-32xxx`:**
 
@@ -143,7 +160,7 @@ Server vs client ranges never overlap, so a single `code` field is unambiguous.
 
 **Wait:**
 - `wait-node <path> [timeout]` — block until node appears (exit 0=found, 1=timeout)
-- `wait-time <seconds>` — wait N in-game seconds (matters for `--write-movie`)
+- `wait-time <seconds>` — wait N in-game seconds (matters for `--write-movie`). Server bounds: `0 ≤ seconds ≤ 3600`; passing out-of-range gets `-32602 "seconds must be ..."`. Client short-circuits `seconds <= 0` without an RPC.
 
 **Render:**
 - `screenshot <path>` — write PNG (path is **required** as of 0.2.0)
@@ -190,7 +207,7 @@ godot-cli-control call /root/Game start_game 1 '"easy"'    # int 1, string "easy
 
 So `position '[100, 200]'` → `Vector2(100, 200)`, `transform '[1,0,0, 0,1,0, 0,0,1, 10,20,30]'` → `Transform3D(IDENTITY, (10,20,30))`. Wrong length or non-numeric elements fail loud with `-32602 "value type mismatch ..."` instead of silently setting `(0, 0)` like pre-0.2.5 versions did.
 
-**Sub-path + Array also fails loud.** `set <node> transform:origin '[10, 20, 30]'` is rejected with `-32602 "sub-path + Array is not supported"`: Godot's `Object.set("transform:origin", Array)` silently drops the Array (origin stays at `(0,0,0)`) — same footgun class as #52, so the server pre-empts it. Sub-paths are scalar-only (`set <node> position:x 1.8`); to write a whole compound Variant use the top-level Array form above.
+**Sub-path + Array also fails loud.** `set <node> transform:origin '[10, 20, 30]'` is rejected with `-32602 "sub-path + Array is not supported"`: Godot's `Object.set("transform:origin", Array)` silently drops the Array (origin stays at `(0,0,0)`) — same class of footgun as the strict Variant checks above, so the server pre-empts it. Sub-paths are scalar-only (`set <node> position:x 1.8`); to write a whole compound Variant use the top-level Array form above.
 
 **Footgun**: bare `null` / `true` / `false` / numeric strings parse as JSON literals first, **not** as strings. If you actually mean the string `"null"`, wrap it explicitly:
 
@@ -294,7 +311,7 @@ Errors raise `RpcError(code, message)` (a `RuntimeError` subclass) that preserve
 | `await client.is_visible(path)` | `visible <path>` |
 | `await client.get_children(path)` | `children <path>` |
 | `await client.screenshot()` | `screenshot <path>` |
-| `await client.get_scene_tree(depth)` | `tree [depth]` |
+| `await client.get_scene_tree(depth, max_nodes=None)` | `tree [depth] [--max-nodes N]` |
 | `await client.wait_for_node(path, timeout)` | `wait-node <path> [timeout]` |
 | `await client.wait_game_time(seconds)` | `wait-time <seconds>` |
 | `await client.action_press(action)` | `press <action>` |
@@ -321,6 +338,12 @@ def run(bridge):
 
 `bridge` is a synchronous wrapper around `GameClient` — same method names, no `await`. Sibling-imports work (the script's directory is on `sys.path`).
 
+**Exit code (when `run` started the daemon itself):**
+- `0` — script succeeded and daemon stopped cleanly.
+- `1` — script raised (envelope carries `code: -1005` with the exception summary; full traceback on stderr).
+- `2` — script-path / daemon-start failed, **or** the script succeeded but the auto-`daemon stop` afterwards hit an ffmpeg transcode failure (success envelope still emits, with `daemon_stop_warning` populated; raw `.avi` is preserved).
+- `64` — argparse usage error (e.g. malformed `--idle-timeout`).
+
 ## pytest plugin (preferred for end-to-end test suites)
 
 `pip install godot-cli-control[pytest]` registers a `pytest11` entry-point that exposes two fixtures, so a Godot e2e test is a one-liner:
@@ -367,6 +390,7 @@ pytest_plugins = ["godot_cli_control.pytest_plugin"]
 - **`tree` returns `1005 "scene tree too large"`** — your scene has more than 5000 visible nodes (a Grid / spawned-bullets situation). Pass `--max-nodes 200` to cap, or `children <path>` for one specific subtree.
 - **`set` with a string that *looks* like JSON** — value parser parses JSON first. To force a literal `"42"` string, pass `'"42"'`; to set a literal hash sign or array text, JSON-encode it.
 - **`daemon start` opens a window when I expected headless** — your stdout is a TTY (interactive terminal). Pass `--headless` explicitly, or shell out from a context where stdout is piped.
+- **`screenshot` used to fail with `1006` on the first call** — fixed. GameBridge now waits for the viewport's first frame before opening the port, so `connect succeeded` implies `viewport has rendered ≥ once`. The magic `bridge.wait(1.5)` before the first screenshot in older example scripts is no longer needed.
 
 ---