godot-cli-control 0.2.18__tar.gz → 0.3.0__tar.gz

{godot_cli_control-0.2.18 → godot_cli_control-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.18
+Version: 0.3.0
 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
@@ -120,6 +120,15 @@ def test_jump(godot_daemon, bridge):
 - `bridge` (function-scoped) gives a fresh `GameBridge`; on teardown it best-effort restores global engine state — `unpause()`, `time_scale` back to its setup-time snapshot, `release_all()` — so a `hold`/`pause`/speed-up left behind by one case can't bleed into the next, then closes the connection.
 - `fresh_scene` (function-scoped, opt-in) calls `scene_reload()` at setup so the case starts on a pristine scene. Node references cached before the reload are invalid afterwards.
 - `no_push_errors` (function-scoped, opt-in) records an `errors` marker at setup and fails the case if any new `push_error` was emitted during it (warnings don't fail). Requires Godot 4.5+ (Logger API) — older engines raise `RpcError` 1012 at setup, loudly.
+- `godot_instances` (scope configurable, default function) is a multi-instance factory for multiplayer e2e — start a named server **and** clients inside one test and get connected `GameBridge` objects back; teardown stops everything the fixture started (and only that):
+
+  ```python
+  def test_join(godot_instances):
+      server = godot_instances.start("server")
+      client = godot_instances.start("client1")
+  ```
+
+  `start(name)` is idempotent get-or-start (`headless`/`time_scale` follow the global options, overridable per call; `port` always defaults to 0 = OS-assigned); `stop(name)` stops one instance mid-test (restartable); `daemon(name)` exposes the underlying `Daemon`. `--godot-cli-instances-scope session` shares one set of instances across the whole suite (faster, no state isolation between tests).
 - On a test failure (non-headless daemon only) a best-effort screenshot is saved to `.cli_control/failures/<nodeid>.png` and the path is attached to the pytest report.
 
 CLI options:
@@ -129,6 +138,7 @@ CLI options:
 --godot-cli-no-headless      # open a real Godot window
 --godot-cli-project-root=DIR # default: pytest rootdir
 --godot-cli-time-scale=X     # Engine.time_scale applied at daemon startup (e.g. 5 to speed up the suite)
+--godot-cli-instances-scope=function|session  # godot_instances fixture scope (default: function)
 ```
 
 ## CLI

{godot_cli_control-0.2.18 → godot_cli_control-0.3.0}/addons/godot_cli_control/CHANGELOG.md

@@ -6,6 +6,27 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-07
+
+### Added
+- **同项目多实例（命名实例）**：`daemon start --name <inst>`（默认 `default`）可在同一项目下并行启动多个 Godot daemon；顶层 `--instance <name>` 对所有 RPC / run / daemon 子命令通用，daemon 子命令的 `--name` 是等价写法。
+- **状态布局迁移 `.cli_control/instances/<name>/`**：daemon 的 pid / port / log 文件从项目根平铺改为按实例子目录存放。legacy 平铺路径（旧格式 `<hash>.json` 注册记录 + `.cli_control/port` 等）仅作只读 fallback 兼容，升级期间无需手工迁移；停掉旧 daemon 后文件自动收敛。硬编码读 `.cli_control/port` 的脚本应改读 `.cli_control/instances/default/port`，或改用 `GameClient()`/`GameBridge()` 自动发现（支持 `instance=` 参数）以免再次硬编码。
+- **`daemon ls` 新增 instance 列**：JSON 每条 `result.daemons[]` 含 `"instance"` 字段；text 输出格式改为 `pid\tport\tinstance\tproject_root\tstarted_at`。
+- **`daemon stop --all --project <path>`**：限定停某个项目下的全部实例（原 `--all` 不带 `--project` 仍停全局所有项目的所有实例）。
+- **daemon 各子命令的 JSON envelope result 带 `"instance"` 字段**：`start` / `stop` / `status` / `logs` 均在 result 中增加 `"instance"` 键，便于 agent 确认操作目标。
+- **`GameBridge(instance=...)` / `GameClient(instance=...)`**：`port=None` 时 `instance` 参数生效，自动查找对应命名实例的端口；显式 `port` 优先（向后兼容）。
+- **pytest 多实例工厂 fixture `godot_instances`**（#143）：联机 e2e 在单测里同时拿 server / client bridge——`godot_instances.start("server")` 幂等启动命名实例并返回已连接 `GameBridge`，teardown 自动停掉本 fixture 起的全部实例（已在跑的只连不杀）；`stop(name)` 支持中途显式停（掉线场景）后重启，`daemon(name)` 暴露底层 `Daemon`。新增 pytest 选项 `--godot-cli-instances-scope=function|session`（默认 function 每用例隔离；session 整套共享省启动时间）。
+- **`--instance all` 一条命令广播全部活实例**（#145）：任一 RPC 子命令对 cwd 项目全部活实例并发执行，聚合信封 `{"instances":[{instance, ok, result|error, rc}...], "rc": 0|3}`（entry 复刻单命令信封）；退出码全 0→0、任一非 0→3（沿 `daemon stop --all` 先例）。字符串参数中的 `{instance}` 逐实例替换；广播 `screenshot` 的路径缺 `{instance}` 时 preflight 报 -1003/64。`all` 成为保留实例名（`daemon start --name all` 拒绝）；`run`/`daemon` 子命令不支持广播。
+
+### Changed
+- **多实例选靶语义（处处一致）**：0 个在跑 → 选 default（legacy fallback）；1 个在跑 → 自动选中；≥2 个在跑且未指定 `--instance` / `--name` → `-1003` / exit 64，message 列出在跑实例名（`"multiple instances running: ... — pass --instance <name>"`）。显式 `--instance nope` 但该实例未在跑 → `-1003` / exit 64，message 附当前在跑实例列表。`--instance` 与 `--port` 互斥。
+- **选中实例 live 但 port 文件尚不可读（daemon 启动中的瞬态）→ `-1003` / exit 64 并提示稍后重试**（#144）：此前静默回退默认端口、连接失败干等 30s，agent 拿不到「正在启动，请重试」的信号。
+
+### Fixed
+- **`daemon stop --all --project <path>` 对没有任何 daemon 在跑的项目不再伪造 `default` 条目**（#144）：text 输出 `(no running daemons)`、JSON `{"stopped": [], "rc": 0}`，与 `--all` 全局空注册表的形状一致。
+- **旧版本 CLI 启动的录像 daemon 用新版 `daemon stop` 停止时录像正常转码**（#144）：此前 legacy 平铺路径的 `movie_path` 无人消费，录像静默残留；legacy `last_exit_code` 死文件也一并清理。
+- **kill -9 留下的死实例目录 `.cli_control/instances/<name>/` 在状态文件清空后自动回收**（#144）：`godot.log` 等诊断文件在场时目录保留不动。
+
 ## [0.2.17] - 2026-06-06
 
 ### Fixed

{godot_cli_control-0.2.18 → godot_cli_control-0.3.0}/addons/godot_cli_control/README.md

@@ -122,7 +122,7 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 
 > **Event pipeline**: `press` / `tap` / `hold` / `combo` inject an `InputEventAction` through the engine's event pipeline — both polling (`is_action_pressed`, `get_vector`) **and** event callbacks (`_input`, `_unhandled_input`) see the input. `InputEventAction` carries no mouse coordinates; position-dependent `_gui_input` widgets need `click` instead.
 
-> **No-arg `GameClient()` / `GameBridge()`**: with no `port` argument they auto-discover the daemon's port from `.cli_control/port` (falling back to `9877`), so a single-connection script connects to a running daemon without hardcoding a port.
+> **No-arg `GameClient()` / `GameBridge()`**: with no `port` argument they auto-discover the daemon's port from `.cli_control/instances/<name>/port` (falling back to `9877`). Pass `instance="server"` to target a named instance when multiple are running (explicit `port` always wins over `instance`). A no-arg call in a single-instance environment still works as before.
 
 ### Variant encoding depth limit
 
@@ -151,7 +151,7 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 | `-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`) |
 | `-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, or script missing `run(bridge)`). Always exits **64** (#82 / #111). |
+| `-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). |
 | `-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 |
 | `-1006` | client | Infra pre-condition failure (`daemon start`/`stop`/`run` auto-start failed at OS level — port conflict, Godot binary not found, etc.). Always exits **2** (#92). |
@@ -165,12 +165,14 @@ The daemon is the long-lived Godot process the CLI talks to (one per project roo
 
 | Command | What it does |
 |---|---|
-| `daemon start [--headless\|--gui] [--record] [--time-scale N]` | Launch Godot with the bridge listening. Headless vs GUI is auto-detected from the TTY; `--record` forces GUI (Movie Maker needs a real renderer) and is **rejected with `--headless`** (exit 2). `--time-scale N` sets `Engine.time_scale` from frame 0 (range `(0, 100]`). |
-| `daemon stop` | Stop this project's daemon. Exit 2 if it stopped cleanly but the `.avi`→`.mp4` ffmpeg transcode failed (raw `.avi` kept; see `.cli_control/ffmpeg.log`). |
+| `daemon start [--headless\|--gui] [--record] [--time-scale N] [--name <inst>]` | Launch Godot with the bridge listening. `--name` sets the instance name (default `default`); use different names to run multiple Godot daemons for the same project in parallel. Headless vs GUI is auto-detected from the TTY; `--record` forces GUI (Movie Maker needs a real renderer) and is **rejected with `--headless`** (exit 2). `--time-scale N` sets `Engine.time_scale` from frame 0 (range `(0, 100]`). |
+| `daemon stop [--name <inst>]` | Stop this project's daemon. With `--name`, stop the named instance. Exit 2 if it stopped cleanly but the `.avi`→`.mp4` ffmpeg transcode failed (raw `.avi` kept; see `.cli_control/ffmpeg.log`). |
 | `daemon stop --all` | Stop every registered daemon across all projects. **Exit 3** if at least one failed; per-record `rc` (and an `error` field on failures) is in `result.stopped[]`. |
-| `daemon stop --project <path>` | Stop the daemon for one specific project root. |
-| `daemon status` | Exit 0 = running, 1 = stopped. When stopped, the payload may carry `last_log` / `last_exit_code` to diagnose a crash. |
-| `daemon ls` | List every registered daemon (project root, pid, port). |
+| `daemon stop --all --project <path>` | Stop all instances of one specific project. |
+| `daemon stop --project <path>` | Stop the daemon for one specific project root (single-instance shorthand). |
+| `daemon status [--name <inst>]` | Exit 0 = running, 1 = stopped. Response includes `"instance"` field. When stopped, the payload may carry `last_log` / `last_exit_code` to diagnose a crash. |
+| `daemon ls` | List every registered daemon (project root, pid, port, **instance**). Text columns: `pid\tport\tinstance\tproject_root\tstarted_at`. |
+| `daemon logs [--name <inst>] [--tail N]` | Print last N lines of godot.log for the given instance. |
 
 **Project-level defaults**: drop a `.cli_control/config.json` with `{"idle_timeout": "30m"}` to give `daemon start` / `run` a default idle-timeout without passing `--idle-timeout` each time. It's consulted only when the flag is omitted (default `0`); an explicit `--idle-timeout` always wins. A long-running `wait-time` / `combo` / recording is bounded client-side by a 600s wall-time fail-safe — override it for legitimately long operations with `GODOT_CLI_LONG_OP_TIMEOUT=<seconds>`.
 

{godot_cli_control-0.2.18 → godot_cli_control-0.3.0}/python/README.md

@@ -83,6 +83,15 @@ def test_jump(godot_daemon, bridge):
 - `bridge` (function-scoped) gives a fresh `GameBridge`; on teardown it best-effort restores global engine state — `unpause()`, `time_scale` back to its setup-time snapshot, `release_all()` — so a `hold`/`pause`/speed-up left behind by one case can't bleed into the next, then closes the connection.
 - `fresh_scene` (function-scoped, opt-in) calls `scene_reload()` at setup so the case starts on a pristine scene. Node references cached before the reload are invalid afterwards.
 - `no_push_errors` (function-scoped, opt-in) records an `errors` marker at setup and fails the case if any new `push_error` was emitted during it (warnings don't fail). Requires Godot 4.5+ (Logger API) — older engines raise `RpcError` 1012 at setup, loudly.
+- `godot_instances` (scope configurable, default function) is a multi-instance factory for multiplayer e2e — start a named server **and** clients inside one test and get connected `GameBridge` objects back; teardown stops everything the fixture started (and only that):
+
+  ```python
+  def test_join(godot_instances):
+      server = godot_instances.start("server")
+      client = godot_instances.start("client1")
+  ```
+
+  `start(name)` is idempotent get-or-start (`headless`/`time_scale` follow the global options, overridable per call; `port` always defaults to 0 = OS-assigned); `stop(name)` stops one instance mid-test (restartable); `daemon(name)` exposes the underlying `Daemon`. `--godot-cli-instances-scope session` shares one set of instances across the whole suite (faster, no state isolation between tests).
 - On a test failure (non-headless daemon only) a best-effort screenshot is saved to `.cli_control/failures/<nodeid>.png` and the path is attached to the pytest report.
 
 CLI options:
@@ -92,6 +101,7 @@ CLI options:
 --godot-cli-no-headless      # open a real Godot window
 --godot-cli-project-root=DIR # default: pytest rootdir
 --godot-cli-time-scale=X     # Engine.time_scale applied at daemon startup (e.g. 5 to speed up the suite)
+--godot-cli-instances-scope=function|session  # godot_instances fixture scope (default: function)
 ```
 
 ## CLI

{godot_cli_control-0.2.18 → godot_cli_control-0.3.0}/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.18'
-__version_tuple__ = version_tuple = (0, 2, 18)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.18 → godot_cli_control-0.3.0}/python/godot_cli_control/bridge.py

@@ -21,15 +21,23 @@ from .client import GameClient
 class GameBridge:
     """同步接口，内部通过事件循环调用异步 GameClient。"""
 
-    def __init__(self, port: int | None = None) -> None:
-        # port=None → GameClient 从 .cli_control/port auto-discover（issue #91）。
+    def __init__(self, port: int | None = None, instance: str | None = None) -> None:
+        # port=None → GameClient 从 .cli_control/ auto-discover（issue #91）。
         # daemon 默认 OS 自动分配端口，所以 ``GameBridge()`` 无参数也能连上正在
         # 跑的 daemon，与 README 的单连接脚本示例一致。
+        # instance：命名实例名（如 "server"），透传给 GameClient.instance；
+        # 显式 port 优先，instance 仅在 port=None 时生效（见 client.py）。
         self._loop = asyncio.new_event_loop()
-        self._client = GameClient(port=port)
-        self._loop.run_until_complete(
-            self._client.connect(retries=15, backoff=1.0, total_timeout=60.0)
-        )
+        # 构造/连接失败时回收 loop —— 多实例歧义（InstanceAmbiguityError）在
+        # __init__ 抛出是预期用法路径，不能让每次报错都泄漏一个 event loop。
+        try:
+            self._client = GameClient(port=port, instance=instance)
+            self._loop.run_until_complete(
+                self._client.connect(retries=15, backoff=1.0, total_timeout=60.0)
+            )
+        except BaseException:
+            self._loop.close()
+            raise
 
     def close(self) -> None:
         self._loop.run_until_complete(self._client.disconnect())