godot-cli-control 0.4.0__tar.gz → 0.4.2__tar.gz

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.4.0
+Version: 0.4.2
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Project-URL: Homepage, https://github.com/ClaymanTwinkle/godot-cli-control
 Project-URL: Repository, https://github.com/ClaymanTwinkle/godot-cli-control

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/addons/godot_cli_control/CHANGELOG.md

@@ -6,6 +6,17 @@
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-06-14
+
+### Fixed
+- **`call` 对错类型「标量」实参不再假成功（#167 的标量侧补集）**：#167 只关了 `call` 的 **JSON Array → 复合 Variant** 侧假成功；错类型的标量实参（`set_name 42` 数字→StringName、`set_z_index '"abc"'` String→int 等）此前仍直接喂 `callv`，引擎喷 `Cannot convert argument` 返回 `null`，RPC 却假 `ok:true`/`result:null`——调用方以为方法生效实则没跑（与 #164/#167 同级数据风险，且 README/SKILL 已宣称「typed 方法假成功不再可能」，文档与实现脱节）。现连 daemon 前按方法声明签名对非 Array 实参也做类型守卫：镜像 Godot `Variant::can_convert_strict`，命中安全互转组（数值组 `bool`/`int`/`float`、字符串组 `String`/`StringName`/`NodePath`）透传，跨组（必 `Cannot convert`）`-32602` fail-loud。数值宽化（`float`→`int`）、`bool`→`int`、`String`→`String` 等合法调用零回归；`null` 实参保守透传（不在本 issue 新增拦截）。纯 addon 服务端行为改动，老项目跑一次 `init` 同步。
+- **`plugin.cfg` 版本号不再僵在 `0.1.0`**：此前 addon 的 `plugin.cfg` 一直写死 `version="0.1.0"`，CI 仅在打包 AssetLib zip 时按 tag `sed` 修正，而 pip wheel 在那条 sed 之前就已构建——于是 `pip install godot-cli-control` + `init` 复制进下游项目的 addon、以及直接 clone addon 的用法，都拿到错误的 `0.1.0`（Godot 编辑器插件列表 / AssetLib 元数据里显示）。现把 committed 值对齐到上次发布版本，并让 `release.sh` 在打 tag 前自动同步 `plugin.cfg` 版本号并入库，三条取用路径（git-direct / pip+init / AssetLib）从此一致。纯元数据修正，不影响 CLI 行为（CLI 版本一直来自 hatch-vcs 的 `_version.py`）。
+
+## [0.4.1] - 2026-06-14
+
+### Fixed
+- **#167 `call` 对 typed 参数不再假成功，且复用 `set` 的 Array→复合 Variant coerce**：此前 `handle_call_method` 裸 `node.callv(method, args)`，当方法形参是强类型（`Rect2`/`Vector2`/`Color` 等）而 CLI 传 JSON Array 时，Godot 只喷 `Cannot convert argument ...` 引擎错误并返回 `null`，RPC 仍假 `ok:true`/`result:null`——调用方以为方法生效实则没跑（#164 的 live `WANDER` 演示就栽在这）。GDScript 无 try-catch 抓不到 callv 运行期错误，现改为连 daemon 前按方法声明签名（`get_method_list()`）预校验：① JSON Array 喂复合 Variant 形参时按声明类型 coerce（`call /root/Mob enable_wander '[0,0,640,480]'` → `enable_wander(rect: Rect2)`），复用 `set` 那套 `_coerce_compound_array`（长度/元素错同样 `-32602` fail-loud）；② Array 喂标量/Object 形参（callv 必转换失败）→ `-32602` fail-loud；③ arg 数量越界（认可选/默认参数与 vararg）→ `-32602` fail-loud。标量实参（数字/字符串/布尔）与拿不到签名的内建方法保持原样透传，零回归。纯 addon 服务端行为改动，老项目跑一次 `init` 同步。
+
 ## [0.4.0] - 2026-06-12
 
 ### Added

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/addons/godot_cli_control/README.md

@@ -89,7 +89,7 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 | `get_property(path, property)` | `await client.get_property("/root/Player", "position")` — returns bare value; CLI `get` returns `{"value": ..., "type"?: ...}` shape |
 | `get_properties(path, properties)` | `await client.get_properties("/root/Player", ["position", "health"])` — multi-property atomic read; returns `{prop: bare_value, ...}` dict |
 | `set_property(path, property, value)` | `await client.set_property("/root/Player", "visible", False)` |
-| `call_method(path, method, args)` | `await client.call_method("/root/Player", "take_damage", [10])` |
+| `call_method(path, method, args)` | `await client.call_method("/root/Player", "take_damage", [10])`. A JSON array passed for a parameter the method declares as a compound Variant (`Rect2`/`Vector2`/`Color`/…) is coerced from the method signature, same as `set_property` (`call_method("/root/Mob", "enable_wander", [[0,0,640,480]])` → `enable_wander(rect: Rect2)`); arg-count / type mismatches fail loud with `-32602` instead of a silent `ok:true`/`result:null` (#167); a scalar of the wrong type (a string for an `int` param, a number for a `String`/`StringName`) likewise fails loud rather than passing through (#183). |
 | `emit_signal(path, signal, args)` | `await client.emit_signal("/root/Game", "level_complete", [])` — fire a node signal (test seam). **Disabled by default** (server returns `1015`); daemon must be started with `--allow-emit-signal` (debug-build + localhost + explicit opt-in). `call <node> emit_signal` is always blocked by the method blacklist — use this method. CLI: `emit-signal <path> <signal> [args...]` |
 | `get_text(path)` | `await client.get_text("/root/UI/Label")` |
 | `node_exists(path)` | `await client.node_exists("/root/MyScene/Button")` |
@@ -157,7 +157,7 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 | `1016` | server | RESPONSE_TOO_LARGE: a single response exceeded the outbound WebSocket buffer (default 10 MB, `godot_cli_control/outbound_buffer_mb`) and was replaced with this error instead of hanging the call to a `-1002` timeout. Usually a bytes-API `screenshot` of a hiDPI frame — pass a path (daemon writes to disk) or raise the buffer. |
 | `-32600` | server | Malformed JSON-RPC request |
 | `-32601` | server | Unknown method name |
-| `-32602` | server | Invalid params (incl. blocked methods/properties from the security blacklist, `set` value-type mismatch — e.g. `Vector2` property given an array of wrong length / non-numeric elements, or `hold` given `duration ≤ 0` — use `press` for an indefinite hold; also out-of-range values like a scene `timeout` outside `(0, 3600]` sent directly via `GameClient`, and `find_nodes` called with no filter at all or with both `text` and `text_contains`) |
+| `-32602` | server | Invalid params (incl. blocked methods/properties from the security blacklist, `set` value-type mismatch — e.g. `Vector2` property given an array of wrong length / non-numeric elements; `call` typed-arg coercion failure / argument-count mismatch — wrong array length, non-numeric element, a JSON array given to a scalar/Object parameter, a scalar of the wrong type (a string for an `int` param, a number for a `String`/`StringName`), or wrong arg count (#167/#183); or `hold` given `duration ≤ 0` — use `press` for an indefinite hold; also out-of-range values like a scene `timeout` outside `(0, 3600]` sent directly via `GameClient`, and `find_nodes` called with no filter at all or with both `text` and `text_contains`) |
 | `-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`, a non-numeric `tap`/`wait-time` arg, a `scene-change` path not starting with `res://`/`uid://`, a `scene-reload`/`scene-change` `--timeout` outside `(0, 3600]`, a `set`/`call` value that fails JSON parsing, script path not found, script missing `run(bridge)`, **multi-instance ambiguity** (≥2 instances running and no `--instance`/`--name` given), **named instance not running** (explicit `--instance nope` but that instance isn't up), **instance port not readable yet** (alive but mid-startup — transient, retry), or `--instance` / `--name` conflict). Always exits **64** (#82 / #111). |

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/addons/godot_cli_control/bridge/low_level_api.gd

@@ -100,6 +100,29 @@ const _ARRAY_PASSTHROUGH_SAFE_TYPES: Array[int] = [
 	TYPE_PACKED_VECTOR4_ARRAY,
 ]
 
+# #167：call 实参传 JSON Array 时，「callv 能正常透传、不会 Cannot-convert 静默失败」的
+# 声明参数类型白名单。命中 = 直接把原 Array 喂 callv；不命中且非可 coerce 的复合 Variant
+# = fail-loud（见 _coerce_call_arg）。入选：untyped(Variant) 形参、Array 形参、Packed*Array
+# （Godot 允许 Array→Packed* 的 call-arg 转换）。
+# **刻意不含** Dictionary / 标量 / Object —— JSON Array → 这些类型 callv 会 "Cannot convert
+# argument" 喷错并返回 null（旧版假 ok:true 的根因），必须拦。注意与 _ARRAY_PASSTHROUGH_SAFE_TYPES
+# 语义不同：那张表是 property set 侧「Object.set 不 silent-corrupt」，这张是 call 侧
+# 「callv 不静默失败」——两套失败模式不同，故不能共用同一张表。
+const _CALL_ARG_ARRAY_OK_TYPES: Array[int] = [
+	TYPE_NIL, TYPE_ARRAY,
+	TYPE_PACKED_BYTE_ARRAY, TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY,
+	TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY, TYPE_PACKED_STRING_ARRAY,
+	TYPE_PACKED_VECTOR2_ARRAY, TYPE_PACKED_VECTOR3_ARRAY, TYPE_PACKED_COLOR_ARRAY,
+	TYPE_PACKED_VECTOR4_ARRAY,
+]
+
+# #183：标量 call 实参「callv 能隐式转换、不静默失败」的互转组，镜像 Godot
+# Variant::can_convert_strict 的数值组 / 字符串组（见 _call_arg_convertible）。组内
+# 任意互转 callv 接受（数值宽化 / 字符串类互通）；跨组（如 String→int、数字→StringName）
+# callv 必 "Cannot convert" 喷错返 null —— 旧版假 ok:true 的标量侧根因，必须拦。
+const _NUMERIC_ARG_TYPES: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT]
+const _STRINGY_ARG_TYPES: Array[int] = [TYPE_STRING, TYPE_STRING_NAME, TYPE_NODE_PATH]
+
 
 func _ready() -> void:
 	_property_blacklist = _merge_extra(_property_blacklist, SETTING_PROPERTY_BLACKLIST_EXTRA)
@@ -285,14 +308,39 @@ func handle_set_property(params: Dictionary) -> Dictionary:
 	return {"success": true}
 
 
-## 把 JSON Array 按声明类型转成 Variant：Vector2/2i/3/3i/4/4i / Rect2/2i /
-## Color / Plane / Quaternion / AABB / Basis / Transform2D/3D / Projection。
+## 按属性声明类型把 JSON Array coerce 成对应 Variant（property set 侧入口）。
 ## 节点没声明该属性：返 {} 表示"沿用原 value"。
-## 声明类型在 match 之外且 ∉ _ARRAY_PASSTHROUGH_SAFE_TYPES：返 {"error": ...} fail-loud，
-##   防御未来 Godot 加新 compound Variant 时 silent-corrupt 回归（详见 fallback 注释）。
-## 声明类型在 _ARRAY_PASSTHROUGH_SAFE_TYPES（基本类型 / 集合 / Packed*）：返 {} 沿用原 value。
-## 转换失败（长度不对 / 元素非数字）：返 {"error": ...} 让调用方 fail-loud。
-## 转换成功：返 {"value": <coerced>}。
+## 声明类型是复合 Variant：委托 _coerce_compound_array（成功 {"value":...} / 长度·元素错 {"error":...}）。
+## 声明类型非复合：在 _ARRAY_PASSTHROUGH_SAFE_TYPES 内 → 返 {} 沿用原 value；否则 fail-loud
+##   （防御未来 Godot 加新 compound Variant 时 silent-corrupt 回归，详见下方 fallback 注释）。
+func _coerce_array_to_declared_type(node: Node, property: String, arr: Array) -> Dictionary:
+	var declared_type: int = -1
+	for prop_info: Dictionary in node.get_property_list():
+		if prop_info["name"] == property:
+			declared_type = int(prop_info["type"])
+			break
+	if declared_type == -1:
+		return {}  # 动态 / 未声明属性，沿用原 value
+	var coerced: Dictionary = _coerce_compound_array(declared_type, arr, property)
+	if not coerced.is_empty():
+		return coerced  # 复合类型命中：{"value": ...} 或 {"error": ...}
+	# 防御性 fallback：声明类型不是复合 Variant 也不在已知 passthrough-safe 名单里时，主动
+	# fail-loud。目的是防止未来 Godot 加新 compound Variant（且 Object.set 同样 silent-corrupt-
+	# on-Array）时重蹈 #52。passthrough-safe = 基本类型 / Object / 集合 / Packed*Array —— 它们
+	# 要么 Godot Object.set 自己拒收 Array（写入失败但不 silent），要么本就接受 Array 输入。
+	if declared_type in _ARRAY_PASSTHROUGH_SAFE_TYPES:
+		return {}
+	return _err(CliControlErrorCodes.INVALID_PARAMS,
+		"value type mismatch for '%s': Array coercion not implemented for declared type %d. If this is a known-safe passthrough, add it to _ARRAY_PASSTHROUGH_SAFE_TYPES; otherwise add a coerce branch."
+			% [property, declared_type])
+
+
+## 把 JSON Array 按「复合 Variant 声明类型」转成对应 Variant：Vector2/2i/3/3i/4/4i /
+## Rect2/2i / Color / Plane / Quaternion / AABB / Basis / Transform2D/3D / Projection。
+## 命中复合类型 → {"value": <coerced>}（成功）或 {"error": ...}（长度/元素不对，fail-loud）；
+## 声明类型不是复合 Variant → 返 {}，由调用方决定 passthrough 还是 fail-loud
+##   （property set 侧 _ARRAY_PASSTHROUGH_SAFE_TYPES；call 实参侧 _CALL_ARG_ARRAY_OK_TYPES）。
+## `label` 仅用于错误信息（property set 传属性名，call 实参传 "arg N of <method>"）。
 ## *i 变体（Vector2i / Vector3i / Vector4i / Rect2i）允许 float 输入并截断到 int，
 ## 与 GDScript `Vector2i(1.7, 2.3) → (1, 2)` 构造器行为一致。
 ##
@@ -303,63 +351,56 @@ func handle_set_property(params: Dictionary) -> Dictionary:
 ##   - Transform3D : [basis 9 axis-vector, origin.xyz]                                   (12 floats)
 ##   - Projection  : [xaxis.xyzw, yaxis.xyzw, zaxis.xyzw, waxis.xyzw]                    (16 floats)
 ## Quaternion / Plane 的 normal 不会自动归一化 —— 调用方传非单位向量后果自负。
-func _coerce_array_to_declared_type(node: Node, property: String, arr: Array) -> Dictionary:
-	var declared_type: int = -1
-	for prop_info: Dictionary in node.get_property_list():
-		if prop_info["name"] == property:
-			declared_type = int(prop_info["type"])
-			break
-	if declared_type == -1:
-		return {}  # 动态 / 未声明属性，沿用原 value
+func _coerce_compound_array(declared_type: int, arr: Array, label: String) -> Dictionary:
 	match declared_type:
 		TYPE_VECTOR2:
-			return _coerce_numeric_array(arr, [2], "Vector2", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [2], "Vector2", label, func(v: Array) -> Variant:
 				return Vector2(v[0], v[1]))
 		TYPE_VECTOR2I:
-			return _coerce_numeric_array(arr, [2], "Vector2i", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [2], "Vector2i", label, func(v: Array) -> Variant:
 				return Vector2i(int(v[0]), int(v[1])))
 		TYPE_VECTOR3:
-			return _coerce_numeric_array(arr, [3], "Vector3", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [3], "Vector3", label, func(v: Array) -> Variant:
 				return Vector3(v[0], v[1], v[2]))
 		TYPE_VECTOR3I:
-			return _coerce_numeric_array(arr, [3], "Vector3i", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [3], "Vector3i", label, func(v: Array) -> Variant:
 				return Vector3i(int(v[0]), int(v[1]), int(v[2])))
 		TYPE_VECTOR4:
-			return _coerce_numeric_array(arr, [4], "Vector4", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [4], "Vector4", label, func(v: Array) -> Variant:
 				return Vector4(v[0], v[1], v[2], v[3]))
 		TYPE_VECTOR4I:
-			return _coerce_numeric_array(arr, [4], "Vector4i", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [4], "Vector4i", label, func(v: Array) -> Variant:
 				return Vector4i(int(v[0]), int(v[1]), int(v[2]), int(v[3])))
 		TYPE_RECT2:
-			return _coerce_numeric_array(arr, [4], "Rect2", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [4], "Rect2", label, func(v: Array) -> Variant:
 				return Rect2(v[0], v[1], v[2], v[3]))
 		TYPE_RECT2I:
-			return _coerce_numeric_array(arr, [4], "Rect2i", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [4], "Rect2i", label, func(v: Array) -> Variant:
 				return Rect2i(int(v[0]), int(v[1]), int(v[2]), int(v[3])))
 		TYPE_COLOR:
 			# Color 接受 RGB（3）或 RGBA（4）。3-element 时 a 默认 1。
-			return _coerce_numeric_array(arr, [3, 4], "Color", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [3, 4], "Color", label, func(v: Array) -> Variant:
 				if v.size() == 3:
 					return Color(v[0], v[1], v[2])
 				return Color(v[0], v[1], v[2], v[3]))
 		TYPE_PLANE:
 			# Plane(normal_x, normal_y, normal_z, d) —— 平面方程系数。
 			# 注意：normal 不会自动归一化；非单位 normal 会让距离 / 投影计算失真。
-			return _coerce_numeric_array(arr, [4], "Plane", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [4], "Plane", label, func(v: Array) -> Variant:
 				return Plane(v[0], v[1], v[2], v[3]))
 		TYPE_QUATERNION:
 			# Quaternion(x, y, z, w) —— 注意 w 在末位，与 Godot ctor 一致。
 			# 注意：不会自动归一化；非单位四元数会让旋转 / slerp 失真。
-			return _coerce_numeric_array(arr, [4], "Quaternion", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [4], "Quaternion", label, func(v: Array) -> Variant:
 				return Quaternion(v[0], v[1], v[2], v[3]))
 		TYPE_AABB:
 			# AABB(position, size) —— 6 floats: [pos.xyz, size.xyz]
-			return _coerce_numeric_array(arr, [6], "AABB", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [6], "AABB", label, func(v: Array) -> Variant:
 				return AABB(Vector3(v[0], v[1], v[2]), Vector3(v[3], v[4], v[5])))
 		TYPE_BASIS:
 			# Basis(x_axis, y_axis, z_axis) —— 9 floats axis-vector 顺序：
 			# v[0..2]=x_axis、v[3..5]=y_axis、v[6..8]=z_axis（每 3 个 = 一个 Basis 轴）。
-			return _coerce_numeric_array(arr, [9], "Basis", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [9], "Basis", label, func(v: Array) -> Variant:
 				return Basis(
 					Vector3(v[0], v[1], v[2]),
 					Vector3(v[3], v[4], v[5]),
@@ -367,14 +408,14 @@ func _coerce_array_to_declared_type(node: Node, property: String, arr: Array) ->
 		TYPE_TRANSFORM2D:
 			# Transform2D(x_axis, y_axis, origin) —— 6 floats axis-vector 顺序：
 			# v[0..1]=x_axis、v[2..3]=y_axis、v[4..5]=origin。
-			return _coerce_numeric_array(arr, [6], "Transform2D", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [6], "Transform2D", label, func(v: Array) -> Variant:
 				return Transform2D(
 					Vector2(v[0], v[1]),
 					Vector2(v[2], v[3]),
 					Vector2(v[4], v[5])))
 		TYPE_TRANSFORM3D:
 			# Transform3D(basis, origin) —— 12 floats: [basis 9 axis-vector 顺序, origin 3]
-			return _coerce_numeric_array(arr, [12], "Transform3D", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [12], "Transform3D", label, func(v: Array) -> Variant:
 				return Transform3D(
 					Basis(
 						Vector3(v[0], v[1], v[2]),
@@ -383,35 +424,28 @@ func _coerce_array_to_declared_type(node: Node, property: String, arr: Array) ->
 					Vector3(v[9], v[10], v[11])))
 		TYPE_PROJECTION:
 			# Projection(x, y, z, w) —— 16 floats axis-vector 顺序：每 4 个 = 一个 Vector4 轴。
-			return _coerce_numeric_array(arr, [16], "Projection", property, func(v: Array) -> Variant:
+			return _coerce_numeric_array(arr, [16], "Projection", label, func(v: Array) -> Variant:
 				return Projection(
 					Vector4(v[0], v[1], v[2], v[3]),
 					Vector4(v[4], v[5], v[6], v[7]),
 					Vector4(v[8], v[9], v[10], v[11]),
 					Vector4(v[12], v[13], v[14], v[15])))
-	# 防御性 fallback：声明类型不是上面的"复合 Variant"也不在已知 passthrough-safe
-	# 名单里时，主动 fail-loud。目的是防止未来 Godot 加新 compound Variant（且
-	# Object.set 同样 silent-corrupt-on-Array）时重蹈 #52。
-	# passthrough-safe = 基本类型 / Object / 集合 / Packed*Array —— 它们要么 Godot
-	# Object.set 自己拒收 Array（写入失败但不 silent），要么本就接受 Array 输入。
-	if declared_type in _ARRAY_PASSTHROUGH_SAFE_TYPES:
-		return {}
-	return _err(CliControlErrorCodes.INVALID_PARAMS,
-		"value type mismatch for '%s': Array coercion not implemented for declared type %d. If this is a known-safe passthrough, add it to _ARRAY_PASSTHROUGH_SAFE_TYPES; otherwise add a coerce branch."
-			% [property, declared_type])
+	# 声明类型不是上面任一复合 Variant → 返 {}，由调用方决定 passthrough / fail-loud
+	# （property set 侧走 _ARRAY_PASSTHROUGH_SAFE_TYPES；call 实参侧走 _CALL_ARG_ARRAY_OK_TYPES）。
+	return {}
 
 
 ## 校验 Array 长度 / 元素全为数字，OK 则调 ctor 构造目标 Variant。
 ## `expected_lens` 是允许长度列表（Color 接 [3, 4]，其他类型固定一个长度）。
-func _coerce_numeric_array(arr: Array, expected_lens: Array[int], type_name: String, property: String, ctor: Callable) -> Dictionary:
+func _coerce_numeric_array(arr: Array, expected_lens: Array[int], type_name: String, label: String, ctor: Callable) -> Dictionary:
 	if not arr.size() in expected_lens:
 		return _err(CliControlErrorCodes.INVALID_PARAMS,
 			"value type mismatch for '%s': expected %s as numeric array of length %s, got length %d"
-				% [property, type_name, _format_length_list(expected_lens), arr.size()])
+				% [label, type_name, _format_length_list(expected_lens), arr.size()])
 	if not _is_all_numeric(arr):
 		return _err(CliControlErrorCodes.INVALID_PARAMS,
 			"value type mismatch for '%s': expected %s as numeric array, got non-numeric element"
-				% [property, type_name])
+				% [label, type_name])
 	return {"value": ctor.call(arr)}
 
 
@@ -441,11 +475,110 @@ func handle_call_method(params: Dictionary) -> Dictionary:
 	if not node.has_method(method):
 		return _err(CliControlErrorCodes.METHOD_NOT_FOUND, "Method not found: %s" % method)
 	var args: Array = params.get("args", []) as Array
-	# 注意：GDScript 没有 try-catch，callv 参数不匹配会产生引擎错误而非可捕获异常
-	var result: Variant = node.callv(method, args)
+	# #167：GDScript 没 try-catch，callv 参数不匹配只会喷引擎错误（"Cannot convert
+	# argument ..."）并返回 null，RPC 仍假 ok:true / result:null —— 调用方以为方法生效
+	# 实则没跑（#164 的 live WANDER 演示就栽在这）。连 daemon 前先按方法声明签名
+	# （get_method_list）做 arg 数量校验 + Array→复合 Variant coerce + 类型守卫，对不上
+	# 即 fail-loud，绝不放假阳性过去。
+	var prepared: Dictionary = _prepare_call_args(node, method, args)
+	if prepared.has("error"):
+		return prepared
+	var result: Variant = node.callv(method, prepared["args"] as Array)
 	return {"result": result}
 
 
+## 按方法声明签名校验 + coerce 实参（#167）。返回 {"args": <coerced Array>}（可直接喂 callv）
+## 或 {"error": ...}（fail-loud）。拿不到签名（has_method 真但 get_method_list 无此条目——
+## 极少数引擎内建）→ 原样透传保旧行为（无签名可校验，不强行拦）。
+func _prepare_call_args(node: Node, method: String, args: Array) -> Dictionary:
+	var method_info: Dictionary = _find_method_info(node, method)
+	if method_info.is_empty():
+		return {"args": args}
+	var declared_args: Array = method_info.get("args", []) as Array
+	var default_args: Array = method_info.get("default_args", []) as Array
+	var is_vararg: bool = (int(method_info.get("flags", 0)) & METHOD_FLAG_VARARG) != 0
+	# default_args 是尾部可选参数的默认值 → 必填数 = 声明数 − 默认值数。
+	var required: int = declared_args.size() - default_args.size()
+	if args.size() < required:
+		return _err(CliControlErrorCodes.INVALID_PARAMS,
+			"argument count mismatch for '%s': expected at least %d, got %d"
+				% [method, required, args.size()])
+	# vararg 方法（rpc / 内建变参）尾部可接任意多实参 → 只校验下界，不卡上界。
+	if not is_vararg and args.size() > declared_args.size():
+		return _err(CliControlErrorCodes.INVALID_PARAMS,
+			"argument count mismatch for '%s': expected at most %d, got %d"
+				% [method, declared_args.size(), args.size()])
+	var coerced_args: Array = []
+	for i in range(args.size()):
+		var arg: Variant = args[i]
+		# 超出声明参数个数的尾巴是 vararg 透传段，没有声明类型，原样喂 callv。
+		if i >= declared_args.size():
+			coerced_args.append(arg)
+			continue
+		var declared_type: int = int((declared_args[i] as Dictionary).get("type", TYPE_NIL))
+		var coerced: Dictionary = _coerce_call_arg(declared_type, arg, "arg %d of %s" % [i, method])
+		if coerced.has("error"):
+			return coerced
+		if coerced.has("value"):
+			coerced_args.append(coerced["value"])
+		else:
+			coerced_args.append(arg)
+	return {"args": coerced_args}
+
+
+func _find_method_info(node: Node, method: String) -> Dictionary:
+	for mi: Dictionary in node.get_method_list():
+		if str(mi.get("name", "")) == method:
+			return mi
+	return {}
+
+
+## 单个 call 实参的类型守卫 + Array→复合 Variant coerce（#167 / #183）。
+## 非 Array 实参（标量 / Dictionary / Object）：按 _call_arg_convertible 判定——可隐式转换
+## 则返 {} 透传，否则 fail-loud（#183，String→int / 数字→StringName 等标量错类型的补集）。
+## Array 实参命中复合声明类型：返复合 coerce 结果（{"value":...} 或长度·元素错的 {"error":...}）。
+## Array 实参 + 声明类型接受 Array（untyped / Array / Packed*，见 _CALL_ARG_ARRAY_OK_TYPES）：返 {} 透传。
+## Array 实参 + 标量 / Object / Dictionary 等：callv 必 "Cannot convert" 静默失败 → fail-loud。
+func _coerce_call_arg(declared_type: int, arg: Variant, label: String) -> Dictionary:
+	if not (arg is Array):
+		# #183：callv 对类型不匹配的标量实参只喷 "Cannot convert argument" 并返回 null，
+		# RPC 仍假 ok:true / result:null（#167 只关了 Array 侧）。可隐式转换则透传，否则拦。
+		if _call_arg_convertible(typeof(arg), declared_type):
+			return {}
+		return _err(CliControlErrorCodes.INVALID_PARAMS,
+			"value type mismatch for '%s': cannot convert %s to declared parameter type %s"
+				% [label, type_string(typeof(arg)), type_string(declared_type)])
+	var coerced: Dictionary = _coerce_compound_array(declared_type, arg, label)
+	if not coerced.is_empty():
+		return coerced
+	if declared_type in _CALL_ARG_ARRAY_OK_TYPES:
+		return {}
+	return _err(CliControlErrorCodes.INVALID_PARAMS,
+		"value type mismatch for '%s': cannot convert JSON Array to declared parameter type %d (a non-Array value is required)"
+			% [label, declared_type])
+
+
+## 标量实参 → 声明形参类型的可转换性判定（#183），镜像 Godot Variant::can_convert_strict
+## 中与 JSON 标量实参相关的子集：true = callv 能隐式转换（透传安全），false = callv 必
+## "Cannot convert" 静默失败（须 fail-loud）。白名单刻意 ⊆ can_convert_strict（在 JSON 实参
+## 场景下），宁可漏拦不误杀合法调用。
+## 范围边界：JSON 实参只产 Nil / bool / 数字 / String / Array / Dictionary。null(TYPE_NIL)
+## 实参的可达性随形参 nullable 而异（Object 形参 / 有默认值时 callv 接受），精确判定需更多
+## 签名信息，故保守透传、不在本 issue 新增对 null 的拦截（与改动前一致，零回归）。
+func _call_arg_convertible(from_type: int, declared_type: int) -> bool:
+	if declared_type == TYPE_NIL:
+		return true  # untyped(Variant) 形参接受任何实参
+	if from_type == declared_type:
+		return true
+	if from_type == TYPE_NIL:
+		return true  # 见上：null 实参保守透传，不新增拦截
+	if from_type in _NUMERIC_ARG_TYPES and declared_type in _NUMERIC_ARG_TYPES:
+		return true  # 数值组 bool/int/float 互转（callv 宽化）
+	if from_type in _STRINGY_ARG_TYPES and declared_type in _STRINGY_ARG_TYPES:
+		return true  # 字符串组 String/StringName/NodePath 互转
+	return false
+
+
 ## emit-signal 逃生门（#157 item4）：默认禁（1015），daemon 带 --allow-emit-signal 才放行。
 ## 门控最先短路（功能没开不解析节点/信号、不泄露存在性）。emit_signal 仍在方法黑名单里，
 ## 本 handler 是唯一的、被门控的发信号入口；通用 call 面 emit_signal 始终被拒。

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/addons/godot_cli_control/plugin.cfg

@@ -3,5 +3,5 @@
 name="Godot CLI Control"
 description="WebSocket bridge for headless / scripted control of Godot scenes (click / property / input simulation / screenshot / record)."
 author="kesar"
-version="0.1.0"
+version="0.4.2"
 script="plugin.gd"

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/addons/godot_cli_control/tests/gut/test_low_level_api.gd

@@ -65,6 +65,31 @@ class _SubPathLeafFixture extends Node:
 	var open_dict: Dictionary = {"foo": 7}
 
 
+# issue #167：handle_call_method 的 typed-arg coerce / fail-loud 用 fixture。
+# 各方法的形参带类型声明，get_method_list() 会汇报对应 TYPE_*，从而走 _coerce_call_arg。
+class _CallFixture extends Node:
+	var last_rect: Rect2 = Rect2()
+	var rect_called: bool = false
+	# 复合 Variant 形参：Array → Rect2 应被 coerce。命名避开方法黑名单（≠ "set"）。
+	func set_wander_rect(rect: Rect2) -> String:
+		last_rect = rect
+		rect_called = true
+		return "ok"
+	# 标量形参：Array 实参无法转换 → fail-loud。
+	func takes_int(n: int) -> int:
+		return n * 2
+	# String 形参（#183 标量侧）：数字 / bool 实参 callv "Cannot convert" → fail-loud；
+	# String 实参透传。
+	func takes_string(s: String) -> String:
+		return s + "!"
+	# 带默认值的可选尾参：required=1，给 1 个实参应放行（b 取默认 5）。
+	func takes_two(a: int, b: int = 5) -> int:
+		return a + b
+	# untyped(Variant) 形参：Array 实参应原样透传，不被误拦。
+	func takes_any(v):
+		return v
+
+
 var _api: Node
 var _target: Node
 
@@ -690,6 +715,213 @@ func test_call_method_nonexistent_returns_1003() -> void:
 	assert_eq(int(result.error.code), 1003)
 
 
+# ── handle_call_method typed-arg coerce / fail-loud（issue #167） ──────
+
+func test_call_method_coerces_array_to_rect2() -> void:
+	# 核心修复：typed Rect2 形参收到 JSON Array → coerce 成 Rect2 并真正调用，
+	# 不再静默 ok:true/result:null（#164 live WANDER 演示的假阳性）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "WanderTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "set_wander_rect",
+		"args": [[1, 2, 3, 4]],
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(str(result.get("result")), "ok")
+	assert_true(fixture.rect_called)
+	assert_eq(fixture.last_rect, Rect2(1, 2, 3, 4))
+
+
+func test_call_method_rect2_wrong_length_fails_loud() -> void:
+	# Rect2 期望 4 个元素，给 3 → -32602，且方法**没**被调用（不能假成功）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "BadLenWanderTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "set_wander_rect",
+		"args": [[1, 2, 3]],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_string_contains(str(result.error.message), "Rect2")
+	assert_false(fixture.rect_called)
+
+
+func test_call_method_rect2_non_numeric_element_fails_loud() -> void:
+	# Rect2 元素须全数字，含字符串 → -32602，方法不被调用。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "BadElemWanderTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "set_wander_rect",
+		"args": [[1, 2, "x", 4]],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_string_contains(str(result.error.message), "Rect2")
+	assert_false(fixture.rect_called)
+
+
+func test_call_method_too_few_args_fails_loud() -> void:
+	# takes_int 必填 1 个，给 0 → -32602（连 callv 都不发，避免引擎错误 + 假 ok:true）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "TooFewTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_int",
+		"args": [],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_string_contains(str(result.error.message), "argument count")
+
+
+func test_call_method_too_many_args_fails_loud() -> void:
+	# takes_int 声明 1 个（非 vararg），给 2 → -32602。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "TooManyTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_int",
+		"args": [1, 2],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_string_contains(str(result.error.message), "argument count")
+
+
+func test_call_method_optional_arg_omitted_ok() -> void:
+	# takes_two(a, b=5)：只给 a=3 应放行，b 取默认 → 返 8。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "OptionalArgTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_two",
+		"args": [3],
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(int(result.get("result")), 8)
+
+
+func test_call_method_array_to_scalar_param_fails_loud() -> void:
+	# 标量 int 形参收到 Array → callv 会 "Cannot convert" 静默失败，故 pre-empt 成 -32602。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "ArrayToScalarTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_int",
+		"args": [[1, 2]],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+
+
+func test_call_method_untyped_param_passes_array_through() -> void:
+	# 防过度拦截：untyped(Variant) 形参的 Array 实参应原样透传，方法收到该数组。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "UntypedArgTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_any",
+		"args": [[1, 2, 3]],
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(result.get("result"), [1, 2, 3])
+
+
+# ── handle_call_method 标量实参 fail-loud / 宽化（issue #183） ──────
+
+func test_call_method_string_to_int_param_fails_loud() -> void:
+	# 复现 set_z_index '"abc"'：String 实参喂 int 形参 → callv "Cannot convert" 静默失败，
+	# pre-empt 成 -32602，方法不被调用（result 缺席，不假 ok:true）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "StrToIntTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_int",
+		"args": ["abc"],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_string_contains(str(result.error.message), "value type mismatch")
+	assert_does_not_have(result, "result")
+
+
+func test_call_method_number_to_string_param_fails_loud() -> void:
+	# 复现 set_name 42：数字实参喂 String 形参 → fail-loud，不假 ok:true。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "NumToStrTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_string",
+		"args": [42],
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_does_not_have(result, "result")
+
+
+func test_call_method_float_to_int_param_widens_ok() -> void:
+	# 防误杀：数值组互转（float→int）是 callv 合法宽化，须透传并真正调用（3.0→3 → 返 6）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "FloatToIntTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_int",
+		"args": [3.0],
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(int(result.get("result")), 6)
+
+
+func test_call_method_bool_to_int_param_ok() -> void:
+	# 防误杀：bool→int 同属数值组，透传（true→1 → 返 2）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "BoolToIntTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_int",
+		"args": [true],
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(int(result.get("result")), 2)
+
+
+func test_call_method_string_to_string_param_ok() -> void:
+	# 防误杀：String→String 精确匹配，透传并调用（"hi"→"hi!"）。
+	var fixture: _CallFixture = _CallFixture.new()
+	fixture.name = "StrToStrTarget"
+	add_child_autofree(fixture)
+	var result: Dictionary = _api.handle_call_method({
+		"path": str(fixture.get_path()),
+		"method": "takes_string",
+		"args": ["hi"],
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(str(result.get("result")), "hi!")
+
+
+func test_prepare_call_args_vararg_not_count_rejected() -> void:
+	# vararg 方法（Node.rpc 是变参）尾部可接任意多实参，数量校验不能误拦。
+	# 直接打 _prepare_call_args（不实际 callv，避免 rpc 副作用），断言无 error、实参保留。
+	var prepared: Dictionary = _api._prepare_call_args(_target, "rpc", ["some_method", 1, 2])
+	assert_does_not_have(prepared, "error")
+	assert_eq((prepared.get("args") as Array).size(), 3)
+
+
 # ── _build_tree 节点总数上限（防 outbound buffer 超限） ───────────────
 
 func test_build_tree_short_circuits_above_node_limit() -> void:

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/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.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.4.2'
+__version_tuple__ = version_tuple = (0, 4, 2)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.4.0 → godot_cli_control-0.4.2}/python/godot_cli_control/templates/skill/SKILL.md

@@ -240,7 +240,7 @@ Three numeric ranges cohabit in `error.code`. Knowing which is which lets you de
 |---|---|
 | `-32600` | Malformed request (missing / non-string `method`). Bug in client; should never reach an agent. |
 | `-32601` | Unknown method name. Bug; means client + plugin versions drifted. |
-| `-32602` | Invalid params: missing required field, blocked property/method (security blacklist), out-of-range value, value-type mismatch on `set` (e.g. `Vector2` property given an array of wrong length / non-numeric elements), node-isn't-clickable (e.g. you `click`'d a `Node2D`), or `hold` given `duration ≤ 0` (use `press` for an indefinite hold). Don't retry; the request shape is wrong. |
+| `-32602` | Invalid params: missing required field, blocked property/method (security blacklist), out-of-range value, value-type mismatch on `set` (e.g. `Vector2` property given an array of wrong length / non-numeric elements), value-type or argument-count mismatch on `call` (typed-parameter coercion failure, a JSON array given to a scalar/Object parameter, a scalar of the wrong type for the declared parameter — e.g. a string for an `int` param or a number for a `String`/`StringName` — or the wrong number of args), node-isn't-clickable (e.g. you `click`'d a `Node2D`), or `hold` given `duration ≤ 0` (use `press` for an indefinite hold). Don't retry; the request shape is wrong. |
 
 **Client-side (CLI / GameClient) — `-1xxx`:**
 
@@ -363,6 +363,8 @@ 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.
 
+**`call` typed arguments use the same coercion (+ arg-count / type checks).** When you `call <node> <method>` and pass a JSON array for a parameter the method declares as a compound Variant (`Rect2`, `Vector2`, `Color`, …), the server reads the method signature (`get_method_list()`) and coerces it exactly like `set` above — e.g. `call /root/Mob enable_wander '[0, 0, 640, 480]'` reaches `func enable_wander(rect: Rect2)` as a real `Rect2`. Mismatches now **fail loud with `-32602`** instead of the old silent `ok: true / result: null`: wrong array length or a non-numeric element (`"value type mismatch ..."`), a JSON array handed to a scalar / Object parameter (`"cannot convert JSON Array ..."`), or the wrong number of arguments (`"argument count mismatch ..."`, which honors optional/default parameters and varargs). Scalar arguments are now type-checked too (#183): a scalar passes through when the engine can implicitly convert it to the declared type (numeric group `bool`/`int`/`float`; string group `String`/`StringName`/`NodePath`), but a mismatch the engine would reject — a string handed to an `int` parameter, a number handed to a `String`/`StringName` parameter — **fails loud with `-32602`** (`"value type mismatch ..."`) rather than the old silent success. This closes the footgun where `callv` printed `Cannot convert argument ...` to the engine log but the RPC still reported success.
+
 **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.
 
 **Sub-path leaf typo also fails loud (symmetric with `get`).** `set <node> position:zz 5` is rejected with `1002` listing the valid leaves, instead of silently dropping the write and returning `{"success": true}` (Godot's `set_indexed` no-ops an unknown leaf — an "I thought I wrote it but the value never changed" footgun). Closed compound types and per-level nesting are exactly the same set as the `get` side; open/dynamic types (Dictionary, Array, Object) still pass through unchecked.
@@ -456,6 +458,29 @@ Key constraints:
 
 **Project-level defaults** (`.cli_control/config.json`, optional): set `{"idle_timeout": "30m"}` so `daemon start` / `run` auto-quit after idle without re-typing `--idle-timeout` every time. It's read only when you don't pass `--idle-timeout` (default `0`); an explicit flag wins. Bad JSON / a malformed duration there surfaces as a `-1003` usage error (exit 64).
 
+#### Recipe: warm-then-record (filming a pre-evolved world)
+
+To record a demo that begins from a *long-evolved* world (e.g. many in-game years of simulation), you **cannot** fast-forward inside the recording: under `--record` Movie Maker renders a fixed `--fps × time_scale` frames per game-second, so raising `Engine.time_scale` only fast-forwards the *captured footage* instead of cheaply skipping ahead. Use a two-daemon **split-record** flow — evolve + save the world in a non-recording daemon, then load + perform in a recording one.
+
+1. **Warm up (non-recording daemon).** Start a normal daemon (`--headless` is fine for pure simulation) and push the world to the target state with `time-scale N` or, better, the game's own sim-speed control. Poll a game-side progress value to know when you have arrived — e.g. `wait-property /root/GameState day == <target>` (substitute your game's own node/field).
+2. **Persist + stop.** Call the game's save entry point to flush the evolved world to a (sandbox) save slot — `call /root/WorldService save_session` (substitute your own) — then `daemon stop` the warm-up daemon.
+3. **Load + record (recording daemon).** Start a `--record` daemon and `run` a script that loads the saved world, waits for it to settle, then drives the camera/player at `time_scale = 1`:
+   ```python
+   def run(bridge):
+       bridge.call("/root/SceneRouter", "continue_game")            # load saved world (game-side API)
+       bridge.wait_node("/root/World")                              # continue_game settles after `await world.ready`
+       bridge.set("/root/World/Player", "global_position", [x, y])  # reset the start AFTER the load settles
+       # ... scripted walk / clicks, captured to the movie ...
+   ```
+
+Known gotchas (all hit in real downstream demo work):
+
+- **Headless `time_scale` overshoots.** Headless runs uncapped, so a high `time_scale` blows past the target in a single tick. Prefer a GUI daemon (frame-rate capped) and poll a game-side counter to stop precisely, or warm up in small `time-scale` steps, re-checking progress between each.
+- **SIGTERM close-save can clobber your save.** If the game saves on quit, the graceful exit `daemon stop` performs may overwrite the slot with the *warm-up* player position. Confirm the save landed before stopping, disable on-quit save during warm-up, or treat the recording-side `continue_game` load as the source of truth and reset the start there.
+- **`continue_game` settles asynchronously.** The loaded world places entities only after `await world.ready`, not synchronously on the call. In the recording script, `wait` / `wait-node` / `wait-property` for the world to be ready **before** overriding the start point — a position set too early is overwritten when the load resolves.
+
+Boundary: to fast-forward *within* a recording, drive the game's **own** sim-speed (which leaves Movie Maker's fixed `--fps × time_scale` frame budget untouched), not engine `time_scale` (which fast-forwards the footage).
+
 ## CLI reference
 
 <!-- BEGIN cli_help (auto-generated by godot-cli-control init) -->
@@ -618,6 +643,7 @@ pytest_plugins = ["godot_cli_control.pytest_plugin"]
 - **`wait-signal` must be armed before the action that fires it.** Every `godot-cli-control` invocation is a fresh process — if you fire the signal before `wait-signal` connects, you'll always timeout. **Preferred (issue #155):** use `--trigger` to arm and fire on the *same* connection: `godot-cli-control wait-signal /root/Area door_opened 3 --trigger 'tap interact'` — the server connects the signal handler first (armed), then your trigger runs, then the result returns. No race, no shell gymnastics. The result envelope includes `trigger_result` with the trigger subcommand's return value (only present when the trigger actually ran). **When using `--trigger`, `timeout` covers only the signal wait, not the trigger's execution time** (issue #172) — the client tells the server to start the deadline *after* your trigger finishes, so slow triggers like `combo` or `drag` no longer eat into the budget. **Fallback (if you can't use --trigger):** `godot-cli-control wait-signal /root/A my_signal & godot-cli-control tap jump; wait` — background the wait *before* triggering. `--trigger` only accepts a single RPC subcommand; for multi-step triggers use `combo` as the `--trigger` subcommand (e.g. `--trigger 'combo --steps-json ...'`).
 - **Replace magic `wait-time` sleeps with `wait-prop` or `wait-frames`.** Fixed `wait-time 0.3` guesses are fragile — they're too long when the game is fast, too short under load. Prefer: `wait-prop /root/Player on_floor true` (wait for state) or `wait-frames 4` (wait for a specific number of frames to render). These are more reliable and often 2-10× faster.
 - **`get` on a compound Variant returns an array + type — you can round-trip it straight into `set`.** `get /root/Player position` returns `{"value": [-2480.0, 1400.0], "type": "Vector2"}`. That `value` array is the exact format `set` accepts: `set /root/Player position '[-2480.0, 1400.0]'`. No conversion needed.
+- **`call` into a method with typed params just works — and fails loud if it can't.** A JSON array passed to a `Rect2` / `Vector2` / `Color` (etc.) parameter is coerced from the method signature (`call /root/Mob enable_wander '[0,0,640,480]'` → `enable_wander(rect: Rect2)`), the same as `set`. If the array is the wrong length, has a non-numeric element, is handed to a scalar parameter, or you pass the wrong number of args, you get `-32602` — **not** a fake `ok: true / result: null`. So a successful-looking `call` that does nothing is no longer possible for typed methods: trust the success envelope.
 - **Arrays/Dicts nested inside compound Variants encode as arrays but carry no `type` field — use a sub-path to read a typed leaf.** For example, a `Dictionary` property that happens to contain a `Vector3` will give you an untyped array. If you need the type, use `get <node> mydict:somekey` to read the leaf directly and get its type.
 - **Sub-path leaf typo on a closed compound type fails loud — on both `get` and `set`.** Closed types are Vector2/3/4 (incl. `i` variants), Color, Rect2/Rect2i, Transform2D/Transform3D, Basis, Plane, Quaternion, AABB, and Projection — a typo'd leaf returns `1002` listing the valid leaves, e.g. `get /root/Node position:typo` → `{"ok": false, "error": {"code": 1002, "message": "Sub-path leaf not found: position:typo (valid leaves: x, y)"}}`. `set /root/Node position:zz 5` is rejected the same way instead of silently dropping the write and returning `{"success": true}`. Nested paths validate per level, so `get /root/Sprite transform:basis:typo` also fails loud. Only **open/dynamic types** (Dictionary, Array, Object) still return `{"value": null}` (or silently pass a `set` through) for an unknown leaf — their keys/members can't be enumerated, so validating would risk false positives. On `get`, `1002` is also returned if the part before `":"` doesn't exist as a top-level property.
 - **Python API (`bridge.get_property` / `bridge.get_properties`) returns bare values only — no `type` field.** These convenience methods strip the `type` from the server response to reduce boilerplate. When you need the `type` field (e.g. to distinguish `Vector2` from a plain 2-element array), go through `client.request("get_property", {"path": ..., "property": ...})` directly.