godot-cli-control 0.2.4__tar.gz → 0.2.6__tar.gz

{godot_cli_control-0.2.4 → godot_cli_control-0.2.6}/PKG-INFO

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

{godot_cli_control-0.2.4 → godot_cli_control-0.2.6}/addons/godot_cli_control/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+### Fixed
+- **#52 `set` 走 JSON Array 喂 Vector/Color/Rect 时静默失败**：`set zoom '[1.8, 1.8]'` 等价于 `node.set("zoom", [1.8, 1.8])`，Godot 隐式构造失败 → 实际值是 `Vector2(0,0)` 或被 clamp 到 `0.00001`，但服务端仍返 `{success: true}`。`handle_set_property` 现在查 `get_property_list()` 拿声明类型，把 numeric Array 转成对应 Variant。长度不匹配或元素非数字时 fail-loud 返 `-32602 "value type mismatch ..."`，不再 silent corruption。
+- **sub-path 标量赋值现在真的会写入**：之前 `set <node> position:x 1.8` 调的是 `Object.set("position:x", 1.8)`，Godot 4 的 `Object.set` 把整串当字面属性名找不到就 silent no-op（依旧返 `{success: true}` 但 `position.x` 不变）。改用 `Object.set_indexed(NodePath, value)` 才会按 sub-path 写入。是 #54 review 阶段被新加的 `test_set_subpath_scalar_still_works` 捕获的隐藏 silent-fail。
+
+### Added
+- **#54 全部复合 Variant 都支持 Array → Variant coerce**：从 4-float 简单类型到 16-float 矩阵，全部按 axis-vector 顺序的 flat numeric Array 写入（每 N 元素 = 一个 Vector 轴）。覆盖：`Vector2/2i/3/3i/4/4i`、`Rect2/2i`、`Color`（3-element=RGB / 4-element=RGBA）、`Plane(a,b,c,d)`、`Quaternion(x,y,z,w)`、`AABB(pos 3, size 3)`、`Basis(9 axis-vector)`、`Transform2D(xaxis 2, yaxis 2, origin 2)`、`Transform3D(basis 9, origin 3)`、`Projection(16 axis-vector)`。具体 layout 见 SKILL.md。`Plane.normal` 和 `Quaternion` 不会自动归一化（与 Godot ctor 一致）。
+- **#54 防御性 fallback**：未在 coerce 名单也不在 `_ARRAY_PASSTHROUGH_SAFE_TYPES`（基本类型 / Object / 集合 / Packed*Array）白名单的声明类型 + Array 输入会 fail-loud，避免未来 Godot 加新 compound Variant 时 silent-corrupt 回归。
+- **#54 sub-path + Array 现在 fail-loud**：`set <node> transform:origin '[10, 20, 30]'` 在 Godot 里会 silent-corrupt（Vector3 leaf 不会从 Array 隐式构造，origin 仍是 (0,0,0)），server 现在主动返 `-32602 "sub-path + Array is not supported"` 提示走 top-level 形式（如 `set <node> transform '[basis 9, origin 3]'`）。sub-path 标量赋值（`position:x 1.8`）不变。
+
 ### AI-friendly CLI 改造（多个 BREAKING change）
 
 把 CLI 重定位成 AI agent 的一等接口：默认结构化输出、补齐读 / 写 / 发现的 shell 命令、明确退出码契约。shell-only 的 agent 现在不需要写 Python 脚本就能完成全部操作。
@@ -44,6 +53,23 @@
 #### Out of scope (intentional)
 - `run <script.py>` 子命令保留旧的人类可读 stderr 输出。它是交互式脚本宿主，不是 RPC，新的 JSON 信封契约只覆盖 RPC 子命令 + daemon 三命令。
 
+### AI-friendliness review fixes (2026-05-11)
+
+#### Fixed
+- **CLI flag position**: `--json` / `--text` / `--no-json` 现在在 RPC 子命令尾部也接受（之前只能写最前面）。argparse 子 parser 用 `default=argparse.SUPPRESS` + 顶层 `set_defaults` 兜底，避免子 parser 默认值覆盖父 parser 解析结果。
+- **Error code 1004 collision**: `low_level_api.gd` 的 scene tree 超限改用新业务码 `1005 "scene tree too large"`，与 input_simulation `1004 "combo in progress"` 解耦。新增 `error_codes.gd` 集中常量。
+- **pytest fixture default port**: `--godot-cli-port` 默认从 9877 改为 0（OS-assigned），与 `daemon start` 默认对齐；多项目并行测试不再撞端口。
+- **Addon README error-code table**: 之前只列到 1003，补全 1004 / 1005 / 客户端 -1xxx 段。
+- **Scene tree hard limit bypass (DoS fix)**: `handle_get_scene_tree` 入口现在把 `max_nodes` clamp 到硬墙 `_BUILD_TREE_NODE_LIMIT` (5000)。修复前客户端传 `max_nodes=999999` 会让服务端先把整棵超大树构造成 Dictionary 再被 1005 错误丢弃（内存浪费 / OOM 路径）。
+- **Error code 1003 semantic split**: screenshot 在 viewport texture 为 null 时不再借用 `1003 METHOD_NOT_FOUND`，改用新业务码 `1006 RESOURCE_UNAVAILABLE`。1003 现在是纯 schema 错（不应 retry），1006 是 transient 错（短重试可能成功），agent 据此分别处置。
+
+#### Added
+- `tree --max-nodes <N>`（默认 200）：节点数软上限；超出时响应含 `truncated: true` + `total_nodes`，agent 据此决定分子树。硬墙仍是 5000 节点 → `1005`。
+- `set` / `call --text-value`：禁用 JSON 解析、把 value/args 强制按字符串处理，避开 `null` / `true` / `42` 这类字面量被解析成 Variant 类型的 footgun。
+
+#### Changed
+- **BREAKING (轻微)**：`daemon start` / `run` 默认 headless 行为改为基于 `sys.stdout.isatty()` 自动判定 —— pipe / CI / agent shell 默认 headless；交互终端默认开窗。新增 `--gui` 强制开窗 flag。`--headless` 仍可显式传，覆盖自动判。脚本里依赖 "默认会开窗" 的需要加 `--gui`。
+
 ## [0.1.6] - Unreleased
 
 ### Added

{godot_cli_control-0.2.4 → godot_cli_control-0.2.6}/addons/godot_cli_control/README.md

@@ -99,7 +99,29 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 | `combo_cancel()` | `await client.combo_cancel()` |
 | `release_all()` | `await client.release_all()` |
 
-Error codes: `-32600` invalid request, `-32601` unknown method, `-32602` invalid params, `1001` node not found, `1002` property not found, `1003` method not found.
+### Error codes
+
+Three numeric ranges share `error.code`; they never overlap, so a single field is unambiguous.
+
+| Code | Source | Meaning |
+|---|---|---|
+| `1001` | server | Node not found at the given path |
+| `1002` | server | Property not found / shape mismatch |
+| `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 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) |
+| `-1001` | client | Connection failure (daemon not running, port wrong, proxy hijacking localhost) |
+| `-1002` | client | Timeout waiting for response |
+| `-1003` | client | CLI usage error (combo missing steps, malformed `--steps-json`, …) |
+| `-1004` | client | Local file IO error (e.g. screenshot can't write the destination) |
+| `-1005` | client | `run <script>` user script raised an uncaught exception — fix the script |
+| `-1099` | client | Internal CLI bug — please file an issue |
+
+For full retry guidance see the SKILL.md shipped by `godot-cli-control init` (`.claude/skills/godot-cli-control/SKILL.md` in the target project).
 
 ## Activation Modes
 

godot_cli_control-0.2.6/addons/godot_cli_control/bridge/error_codes.gd

@@ -0,0 +1,28 @@
+class_name CliControlErrorCodes
+extends RefCounted
+## 集中错误码常量。新加业务码必须在这里登记，
+## 避免 1004 那种隐式撞码（input_sim 用 "combo in progress"，
+## low_level 又用 "scene tree too large"）。
+##
+## 三段制（详见 SKILL.md 错误码表）：
+##   1xxx        服务端业务码
+##   -32xxx      JSON-RPC 标准
+##   -1xxx       客户端（Python）侧；GDScript 这边不会产出
+
+const NODE_NOT_FOUND: int = 1001
+const PROPERTY_NOT_FOUND: int = 1002       # 也用于 "node has no 'text' property"
+const METHOD_NOT_FOUND: int = 1003
+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
+const INVALID_REQUEST: int = -32600
+const METHOD_UNKNOWN: int = -32601

{godot_cli_control-0.2.4 → godot_cli_control-0.2.6}/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.4 → godot_cli_control-0.2.6}/addons/godot_cli_control/bridge/input_simulation_api.gd

@@ -1,6 +1,10 @@
 class_name InputSimulationApi
 extends Node
 ## 输入模拟 API：动作级按键、持续控制、组合序列
+##
+## 错误码常量来自 res://addons/godot_cli_control/bridge/error_codes.gd
+## （class_name CliControlErrorCodes）。靠 Godot 全局 class 注册解析；若 GUT
+## 测试跑前遇到 "Class 'CliControlErrorCodes' not found"，先 import 一次。
 
 # 手动按下的动作（无定时器）
 var _pressed_actions: Dictionary = {}
@@ -46,10 +50,10 @@ func is_combo_active() -> bool:
 
 func handle_action_press(params: Dictionary) -> Dictionary:
 	if _combo_active:
-		return _err(1004, "combo in progress")
+		return _err(CliControlErrorCodes.COMBO_IN_PROGRESS, "combo in progress")
 	var action: String = params.get("action", "") as String
 	if not InputMap.has_action(action):
-		return _err(1003, "Unknown action: %s" % action)
+		return _err(CliControlErrorCodes.METHOD_NOT_FOUND, "Unknown action: %s" % action)
 	_do_press(action)
 	_pressed_actions[action] = true
 	return {"success": true}
@@ -57,10 +61,10 @@ func handle_action_press(params: Dictionary) -> Dictionary:
 
 func handle_action_release(params: Dictionary) -> Dictionary:
 	if _combo_active:
-		return _err(1004, "combo in progress")
+		return _err(CliControlErrorCodes.COMBO_IN_PROGRESS, "combo in progress")
 	var action: String = params.get("action", "") as String
 	if not InputMap.has_action(action):
-		return _err(1003, "Unknown action: %s" % action)
+		return _err(CliControlErrorCodes.METHOD_NOT_FOUND, "Unknown action: %s" % action)
 	_do_release(action)
 	_pressed_actions.erase(action)
 	_held_actions.erase(action)
@@ -71,10 +75,10 @@ func handle_action_release(params: Dictionary) -> Dictionary:
 ## 定时器到期后自动释放
 func handle_action_tap(params: Dictionary) -> Dictionary:
 	if _combo_active:
-		return _err(1004, "combo in progress")
+		return _err(CliControlErrorCodes.COMBO_IN_PROGRESS, "combo in progress")
 	var action: String = params.get("action", "") as String
 	if not InputMap.has_action(action):
-		return _err(1003, "Unknown action: %s" % action)
+		return _err(CliControlErrorCodes.METHOD_NOT_FOUND, "Unknown action: %s" % action)
 	var duration: float = params.get("duration", 0.1) as float
 	_do_press(action)
 	_held_actions[action] = duration
@@ -104,10 +108,10 @@ func handle_list_input_actions(params: Dictionary) -> Dictionary:
 
 func handle_hold(params: Dictionary) -> Dictionary:
 	if _combo_active:
-		return _err(1004, "combo in progress")
+		return _err(CliControlErrorCodes.COMBO_IN_PROGRESS, "combo in progress")
 	var action: String = params.get("action", "") as String
 	if not InputMap.has_action(action):
-		return _err(1003, "Unknown action: %s" % action)
+		return _err(CliControlErrorCodes.METHOD_NOT_FOUND, "Unknown action: %s" % action)
 	var duration: float = params.get("duration", 0.0) as float
 	_do_press(action)
 	_held_actions[action] = duration
@@ -137,7 +141,7 @@ func release_all() -> void:
 func handle_combo(params: Dictionary, request_id: String) -> void:
 	if _combo_active:
 		if _send_response_callback.is_valid():
-			_send_response_callback.call(request_id, _err(1004, "combo in progress"))
+			_send_response_callback.call(request_id, _err(CliControlErrorCodes.COMBO_IN_PROGRESS, "combo in progress"))
 		return
 	var steps: Array = params.get("steps", []) as Array
 	_combo_request_id = request_id
@@ -188,7 +192,7 @@ func _begin_combo_step() -> void:
 	var raw: Variant = _combo_steps[_combo_index]
 	if not raw is Dictionary:
 		_abort_combo_with_error(
-			-32602, "combo step must be object at index %d" % _combo_index
+			CliControlErrorCodes.INVALID_PARAMS, "combo step must be object at index %d" % _combo_index
 		)
 		return
 	var step: Dictionary = raw as Dictionary
@@ -198,7 +202,7 @@ func _begin_combo_step() -> void:
 		var action: String = step["action"] as String
 		if not InputMap.has_action(action):
 			_abort_combo_with_error(
-				1003, "Unknown action at combo step %d: %s" % [_combo_index, action]
+				CliControlErrorCodes.METHOD_NOT_FOUND, "Unknown action at combo step %d: %s" % [_combo_index, action]
 			)
 			return
 		var duration: float = step.get("duration", 0.1) as float
@@ -207,7 +211,7 @@ func _begin_combo_step() -> void:
 		_combo_timer = duration
 	else:
 		_abort_combo_with_error(
-			-32602, "combo step missing 'wait' or 'action' at index %d" % _combo_index
+			CliControlErrorCodes.INVALID_PARAMS, "combo step missing 'wait' or 'action' at index %d" % _combo_index
 		)