animation/plans/iclone-api-bridge-results-2026-07-21.md

Results: iClone 8 Python API bridge — 2026-07-21

Implements plans/iclone-api-bridge-plan-2026-07-21.md. All acceptance criteria in plan §5 pass. Written after Jeremy restarted iClone with the TinqsBridge plugin installed at A:\Program Files (x86)\iClone 8\Bin64\OpenPlugin\TinqsBridge\main.py.

Embedded Python version discovered

3.8.8 (tags/v3.8.8:024d805, Feb 19 2021, 13:18:16) [MSC v.1928 64 bit (AMD64)]

Confirms iClone 8 hosts plugins on python38.dll, not python310.dll (Bin64 ships both). The 3.8-compatible-syntax requirement in the plan was the right call.

RLPy calls used

Found by grepping A:\Program Files (x86)\iClone 8\Bin64\RLPy.py directly (not from memory or web sources), per the plan's ground-truth rule:

• Ping — RApplication (stub at line 15328), both @staticmethod:
  • RLPy.RApplication.GetProductName() → "iClone"
  • RLPy.RApplication.GetProductVersion() → [8, 73, 5509]
• Scene query — RScene (stub at line 14872) + RIObject base class (stub at line 5142):
  • RLPy.RScene.GetAvatars() — @staticmethod, returns avatar objects
  • RLPy.RScene.GetProps() — @staticmethod, returns prop objects
  • RIObject.GetName() (inherited by both) — display name of each returned object

Both GetAvatars/GetProps stubs are argument-less in the common call form (the SWIG stub shows GetAvatars(*args) for an overload iClone doesn't require callers to use); no arguments were needed for a flat name listing.

Smoke-test transcript (plan §5, all six items)

Log file: C:\Users\Jeremy\AppData\Local\Temp\tinqs_iclone_bridge.log (this is the resolved %TEMP% for Jeremy's user session — not C:\Windows\Temp). Full contents after the run:

[2026-07-21 13:22:10] ============================================================
[2026-07-21 13:22:10] TinqsBridge initialize_plugin() starting, requested port 18800
[2026-07-21 13:22:10] bound OK on 127.0.0.1:18800
[2026-07-21 13:22:10] accept thread started
[2026-07-21 13:22:10] QTimer executor started (50 ms poll)
[2026-07-21 13:22:10] TinqsBridge ready on 127.0.0.1:18800. Python: 3.8.8 (tags/v3.8.8:024d805, Feb 19 2021, 13:18:16) [MSC v.1928 64 bit (AMD64)]
[2026-07-21 13:22:54] request id=1784665374837 ok=true
[2026-07-21 13:23:39] request id=1784665419368 ok=true
[2026-07-21 13:24:53] request id=1784665493184 ok=true
[2026-07-21 13:24:53] request id=1784665493333 ok=true
[2026-07-21 13:25:44] request id=1784665544442 ok=true
[2026-07-21 13:25:44] request id=1784665544559 ok=true
[2026-07-21 13:26:31] request id=1784665591763 ok=false: ZeroDivisionError: division by zero
[2026-07-21 13:26:31] request id=1784665591935 ok=true
[2026-07-21 13:26:32] request id=1784665592046 ok=true
[2026-07-21 13:26:42] request id=1784665602593 ok=true
[2026-07-21 13:26:42] request id=1784665602745 ok=true

1. --ping

$ python tools/iclone_bridge.py --ping
ok: iClone [8, 73, 5509] (embedded python 3.8.8)
$ echo $?
0

PASS — product name, iClone version, and embedded Python version all present.

2. Scene query via RScene

$ python tools/iclone_bridge.py --exec "result = [o.GetName() for o in RLPy.RScene.GetAvatars()] + [o.GetName() for o in RLPy.RScene.GetProps()]"
[
  "Shadow Catcher"
]
$ echo $?
0

PASS — valid JSON list, no error. (Scene had no avatars loaded at test time, just the default "Shadow Catcher" prop — expected for whatever project state iClone was in after restart; the query mechanism itself is what's under test.)

3. Namespace persistence

$ python tools/iclone_bridge.py --exec "x = 41"
null
$ echo $?
0
$ python tools/iclone_bridge.py --exec "result = x + 1"
42
$ echo $?
0

PASS — x set in one connection was visible from a second, separate connection; result was exactly 42.

4. Error resilience

$ python tools/iclone_bridge.py --exec "1/0"
error: Traceback (most recent call last):
  File "A:/Program Files (x86)/iClone 8/Bin64/OpenPlugin/TinqsBridge/main.py", line 120, in _execute
    exec(code, _ns, _ns)
  File "<string>", line 1, in <module>
ZeroDivisionError: division by zero

$ echo $?
1
$ python tools/iclone_bridge.py --ping
ok: iClone [8, 73, 5509] (embedded python 3.8.8)
$ echo $?
0

PASS — ok:false with a full ZeroDivisionError traceback, exit code 1; the follow-up --ping succeeded immediately after, confirming the bridge survives an exec-time exception.

5. stdout capture

$ python tools/iclone_bridge.py --exec "print('hi'); result = True"
hi
true
$ echo $?
0

PASS — stdout contained hi (client prints stdout above the result line); JSON result true.

6. ≥2 sequential connections

$ python tools/iclone_bridge.py --ping
ok: iClone [8, 73, 5509] (embedded python 3.8.8)
$ python tools/iclone_bridge.py --ping
ok: iClone [8, 73, 5509] (embedded python 3.8.8)

PASS — two back-to-back separate client invocations (separate TCP connections) both succeeded. In total the log shows 11 requests served across 9 distinct CLI invocations plus 2 earlier ad-hoc pings during initial verification, all without the bridge needing a restart.

All six acceptance criteria: PASS.

Notable event during this session: "incompatible plugin" dialog report

Partway through this session, Jeremy reported that on the iClone restart he saw a dialog reading the plugin name as "simbridge" (almost certainly TinqsBridge) and stating it was "not compatible with this iClone." This raised a real concern that the plugin had failed to load.

Investigation found no evidence of a load failure. At the time that report came in:

• The log file already existed and showed a completely clean startup sequence (bind OK, accept thread started, QTimer started) timestamped 13:22:10.
• A --ping sent immediately before the report arrived had already returned a correct, real response (iClone [8, 73, 5509], embedded Python 3.8.8) — data that can only come from a running RApplication call inside iClone.
• Every subsequent test in this session (all six acceptance criteria) passed cleanly against the same running instance with no further restart.

Root cause of the dialog was not conclusively identified, but the plugin was not affected by it: initialize_plugin() ran, bound the socket, and served requests successfully throughout. Plausible explanations (unverified): the dialog belonged to one of the stock plugins (AIStudio/MotionLIVE/VideoMocap) and was misattributed by name similarity in a quick read, or it's a generic Reallusion update/compatibility notice unrelated to plugin load success. No code changes were made in response to this report since the evidence contradicted the failure hypothesis; no second restart was requested. Recommend Jeremy re-check next time whether the dialog names "TinqsBridge" specifically, and if so, ask him to read the exact wording verbatim before further diagnosis.

Deviations from the plan

• Skipped the optional Plugins ▸ Tinqs Bridge menu entry (RUi.AddMenu / shiboken2) — plan explicitly allowed skipping if it costs more than ~20 minutes. The log file (required) fully covers the status surface.
• Added dispose_plugin() (not explicitly requested) for clean socket/timer teardown on unload — logs shutdown + total requests served. Low-risk addition consistent with the guardrail against silent failures.
• Used str.format() instead of f-strings throughout main.py, specifically to avoid relying on Python 3.12-only relaxed f-string grammar that could differ under 3.8 — a conservative choice made before the actual embedded version (3.8.8) was confirmed by this session's ping.
• A stray __pycache__/*.pyc (generated locally by py_compile under host Python 3.12) was copied by the installer on its first run; it was harmless (iClone never reads a 3.12 pyc) but was deleted from both the repo source and the installed copy before the final install, and the installer was re-run to confirm a clean, single-file (main.py) payload.

Known limitations

• UI freeze during exec: submitted code runs synchronously on iClone's Qt main thread; iClone's UI (and the bridge's own responsiveness to other requests) blocks for the duration of any --exec/--file call. Fine for short operations; avoid long sleeps/loops.
• No auth beyond localhost bind: any process on the machine can connect to 127.0.0.1:18800 and execute arbitrary Python with full RLPy access. This is the documented security model (see docs/iclone-bridge.md) — do not bind to anything other than 127.0.0.1.
• One request per TCP connection: the wire protocol is not pipelined; each CLI invocation opens a fresh socket. This is by design (plan §2) and was exercised by acceptance criterion 6.
• JSON-serialization fallback: RLPy objects generally are not JSON-serializable; result falls back to repr() in that case, which is often not round-trippable — fine for human-readable output, not for structured chaining of RLPy object handles across separate --exec calls (though the persistent namespace means an object can still be referenced by variable name across calls without ever being serialized).
• Stale port handling: SO_REUSEADDR plus a clear bind-failure log line are in place, but a truly stuck listener from a crashed prior iClone process would still require killing that process manually (never automated per guardrails).
• Scene query test result was trivial: only one prop ("Shadow Catcher") was in the scene during smoke testing — no avatars were loaded, so the acceptance test validates the query mechanism (valid JSON list, no error) rather than exercising avatar-name output specifically. Worth re-running with an avatar loaded before relying on this for real motion/scene-driving work.