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

Plan: iClone 8 Python API bridge — control iClone from the terminal

Status: ready for implementation · Author: Fable 5 session 2026-07-21 · Implementer: GLM session

0. Context (you have no other context — read this fully)

You are on Jeremy's Windows 11 PC. This repo (C:\Users\Jeremy\tinqs\animation) is the animation bridge for the ariki-game project: animations are authored in iClone 8, exported as FBX into exchange/, and retargeted with tools/cc_retarget.py. Today that pipeline is entirely manual on the iClone side (Jeremy clicks Export in the UI).

Goal: establish a programmatic connection to iClone 8 so terminal agents (Claude, GLM, scripts) can drive it — load motions, query the scene, trigger FBX exports — without Jeremy clicking through the UI each time.

Why a bridge is needed: iClone 8 has an embedded Python API (RLPy module) but no external/network API of any kind. Scripts only run inside iClone, loaded either from the Script menu or as auto-loading plugins. The standard pattern (used by MotionLIVE etc.) is a plugin that runs a localhost socket server inside iClone and executes commands sent to it. That is what you will build.

Verified environment facts (checked 2026-07-21 — trust these)

• iClone 8 install: A:\Program Files (x86)\iClone 8\ (note: A: drive, not C:).
• Plugin auto-load folder: A:\Program Files (x86)\iClone 8\Bin64\OpenPlugin\ — verified writable without elevation. Currently contains only stock plugins (AIStudio, MotionLIVE, VideoMocap). Do not touch those.
• API stub for reference: A:\Program Files (x86)\iClone 8\Bin64\RLPy.py — this file lists every RLPy class/method with docstrings. It is your API ground truth; grep it before using any RLPy call. Do not trust API names from memory or old forum posts.
• Embedded Python: Bin64 contains BOTH python38.dll and python310.dll — do not assume which one hosts plugins. Write the plugin in 3.8-compatible syntax (no match, no X | Y unions, no 3.9+ stdlib) and report the real version via the bridge itself (sys.version) in your results.
• Qt: iClone embeds Qt 5.15 / PySide2 (shiboken2 available in-process).
• Client-side Python: 3.12.10 on PATH (python). Client must be stdlib-only.
• iClone was RUNNING when this plan was written. A restart is required to load the new plugin — Jeremy must do the restart himself (he may have unsaved work). Never kill the iClone process.

Reference docs (fetch only if stuck; the RLPy.py stub usually suffices)

• Plugin structure: https://wiki.reallusion.com/IC_Python_API:Your_First_iClone_Python_Plugin
• IC8 API wiki: https://wiki.reallusion.com/IC8_Python_API
• Official samples (QTimer/menu/PySide2 patterns): https://github.com/reallusion/iClone

1. Architecture

┌─ this repo ──────────────────┐        ┌─ inside iClone 8 (Qt main thread) ─────────┐
│ tools/iclone_bridge.py       │  TCP   │ OpenPlugin\TinqsBridge\main.py             │
│  (client, py3.12, stdlib)    │◄──────►│  socket thread: accept + read/write ONLY   │
│                              │ 127.0. │  queue → QTimer(50ms, main thread) drains, │
│ tools/iclone_bridge/         │ 0.1:   │  exec()s code with RLPy in namespace,      │
│  TinqsBridge/main.py (source)│ 18800  │  posts JSON reply back to socket thread    │
│ tools/install_iclone_bridge  │        │                                            │
│  .ps1 (copies to OpenPlugin) │        └────────────────────────────────────────────┘
└──────────────────────────────┘

Non-negotiable threading rule: RLPy is not thread-safe and must only be called on iClone's Qt main thread. The socket thread NEVER touches RLPy. It pushes requests onto a queue.Queue; a PySide2 QTimer created in initialize_plugin() (which runs on the main thread) fires every ~50 ms, drains the queue, executes, and hands the response back (a second queue or per-request threading.Event — your choice).

2. Wire protocol (keep it this simple)

Newline-delimited JSON over TCP, localhost only, one request/response pair at a time.

• Request: {"id": 1, "code": "<python source>"}
• Success: {"id": 1, "ok": true, "result": <json>, "stdout": "<captured prints>"}
• Failure: {"id": 1, "ok": false, "error": "<full traceback>", "stdout": "..."}

Execution semantics:

• exec(code, ns, ns) — one persistent namespace dict ns shared across all requests for the life of the iClone session, pre-seeded with RLPy imported. Same dict as globals AND locals (avoids the exec-scoping trap where nested functions can't see top-level names).
• If the code sets a variable named result, that is the response result (JSON-serialize; on TypeError fall back to repr()). Otherwise result is null. Clear ns["result"] before each exec so stale values don't leak.
• Capture stdout/stderr during exec (contextlib.redirect_stdout/stderr) into stdout.
• Any exception → ok:false with traceback.format_exc(); the bridge itself must survive and serve the next request.

3. Deliverables

1. tools/iclone_bridge/TinqsBridge/main.py — the plugin (source of truth lives in the repo; the installer copies it out). Requirements:
   • initialize_plugin() (mandatory — iClone refuses to load the plugin without it). Wrap its entire body in try/except that writes traceback.format_exc() to the log file — plugin load failures are otherwise near-silent.
   • TCP server on 127.0.0.1:18800, SO_REUSEADDR, port overridable via env var TINQS_ICLONE_BRIDGE_PORT read inside iClone. If the bind fails, log it clearly and return without crashing the plugin loader.
   • Socket-accept loop on a daemon=True thread; QTimer executor per §1. Keep module-level references to the timer and thread (a GC'd QTimer silently stops).
   • Log to %TEMP%\tinqs_iclone_bridge.log (append, timestamped lines: startup, bind result, each request id + ok/error, shutdown).
   • Optional nice-to-have, skip if it costs you more than ~20 min: a Plugins ▸ Tinqs Bridge menu entry showing status (port, requests served) via RLPy.RUi.AddMenu + shiboken2.wrapInstance (see the GitHub samples). The log file is the required status surface; the menu is garnish.
2. tools/iclone_bridge.py — client, Python 3.12, stdlib only. API: run(code, port=18800, timeout=30.0) -> dict and ping(port, timeout) -> dict. CLI (match the repo's argparse style):

   python tools/iclone_bridge.py --ping
   python tools/iclone_bridge.py --exec "result = 1 + 1"
   python tools/iclone_bridge.py --file some_script.py
   python tools/iclone_bridge.py --port 18801 --timeout 120 --exec "..."
   

   --ping sends a snippet returning {"product": ..., "version": ..., "python": sys.version} — find the real product/version getters by grepping RLPy.py (look at RApplication and RGlobal; do not guess). Exit 0 on ok:true, 1 on ok:false or connection failure, with a readable message either way (mention "is iClone running? was it restarted after install?" on connection-refused).
3. tools/install_iclone_bridge.ps1 — copies tools/iclone_bridge/TinqsBridge/ → A:\Program Files (x86)\iClone 8\Bin64\OpenPlugin\TinqsBridge\ (overwrite), prints what it did and reminds that iClone must be restarted. Idempotent.
4. docs/iclone-bridge.md — short usage doc: what it is, install/update procedure, CLI examples, the result convention, the persistent-namespace behavior, the log file location, the threading rule for anyone extending the plugin, and the "long-running code freezes the iClone UI" warning.
5. Results report plans/iclone-api-bridge-results-2026-07-21.md: actual embedded Python version discovered, RLPy calls used for ping, smoke-test transcript (§5), any deviations from this plan with reasons, and known limitations.

4. Implementation order

1. Grep A:\Program Files (x86)\iClone 8\Bin64\RLPy.py for the calls you need (RApplication, RGlobal, RScene, RFileIO) and note exact signatures.
2. Write plugin + client + installer.
3. Run the installer. Verify the files landed in OpenPlugin.
4. Stop and ask Jeremy to save his iClone work and restart iClone. Do not proceed to smoke tests until he confirms. Never kill or restart the process yourself.
5. Run smoke tests (§5). If the plugin didn't load: check the log file first, then iClone's Script ▸ Console Log window (ask Jeremy to read it out if needed).
6. Write docs + results report.

5. Acceptance criteria (all must pass, transcript goes in the results report)

1. python tools/iclone_bridge.py --ping → ok, prints product name, iClone version, and embedded Python version.
2. Scene query: --exec a snippet listing scene object names via RScene (e.g. avatars + props; exact API from the stub) returns a JSON list without error.
3. Namespace persistence: --exec "x = 41" then --exec "result = x + 1" → 42.
4. Error resilience: --exec "1/0" → ok:false with a ZeroDivisionError traceback, AND a follow-up --ping still succeeds.
5. stdout capture: --exec "print('hi'); result = True" → stdout contains hi.
6. Bridge survives ≥ 2 sequential client connections (each CLI call is a new connection).

6. Guardrails — do NOT

• Do not kill, restart, or send input to the running iClone process. Restarts are Jeremy's job (step 4.4).
• Do not modify anything in OpenPlugin\ other than creating/updating TinqsBridge\.
• Do not modify existing repo tools (cc_retarget.py, loop_qc.py, loop_fix.py, dance_profile.py, etc.), anything in .claude/, docs/ (except the new docs/iclone-bridge.md), or exchange/.
• Do not bind to anything other than 127.0.0.1. This is an arbitrary-code-execution endpoint by design; localhost-only is the security model.
• Do not install any packages — plugin uses iClone's embedded stdlib + PySide2; client uses Python 3.12 stdlib.
• Do not commit or push. Leave everything in the working tree for Jeremy's review.

7. Known traps

• RLPy off the main thread crashes or corrupts iClone. The QTimer pattern in §1 is mandatory; the socket thread only moves bytes.
• QTimer lifetime: keep a module-level reference; also create it in initialize_plugin() (main thread), never in the socket thread.
• initialize_plugin() missing, misnamed, or raising → plugin silently fails to load. Hence the try/except-to-logfile around everything.
• exec scoping: pass the same dict as globals and locals, or nested functions/comprehensions in user code will throw NameError on top-level names.
• Commands run synchronously on the Qt main thread → iClone's UI freezes for the duration. Fine for seconds-long operations (an FBX export blocks anyway); document it.
• JSON can't serialize RLPy objects — always try/except the dumps and fall back to repr.
• Stale port from a previous iClone instance: SO_REUSEADDR + a clear log line beats a cryptic bind exception.
• Windows Firewall shouldn't prompt for a 127.0.0.1 bind, but if a prompt appears Jeremy should allow it (note in docs).
• Socket recv: requests may arrive fragmented — read until \n, decode UTF-8.
• Both python38.dll and python310.dll exist in Bin64 — write for 3.8, verify via ping.
• Old wiki pages mix iClone 7 and 8 APIs; several IC7 calls were renamed/removed. The local RLPy.py stub outranks every web source.
• After the bridge is up once, you can iterate on executor behavior by exec-ing new code through the bridge itself (hot-swap) — but changes to main.py on disk still need an iClone restart to load. Batch your plugin edits to minimize restart requests.