animation/docs/iclone-bridge.md

iClone bridge

A terminal-to-iClone bridge: drive iClone 8 from the shell (query the scene, run RLPy code, trigger exports) without clicking through the UI.

iClone 8's Python API (RLPy) only runs inside iClone -- there is no external/network API. TinqsBridge is a small auto-load iClone plugin that opens a localhost TCP socket server inside iClone and executes whatever Python source is sent to it, on iClone's own Qt main thread.

Pieces

• tools/iclone_bridge/TinqsBridge/main.py -- the plugin source of truth (lives in this repo, gets copied into iClone).
• tools/install_iclone_bridge.ps1 -- copies the plugin into iClone's auto-load folder.
• tools/iclone_bridge.py -- the terminal client (Python 3.12, stdlib only).

Install / update

powershell -File tools\install_iclone_bridge.ps1

This copies tools/iclone_bridge/TinqsBridge/ to A:\Program Files (x86)\iClone 8\Bin64\OpenPlugin\TinqsBridge\, overwriting any existing copy. It is idempotent and only ever touches the TinqsBridge subfolder -- other plugins under OpenPlugin\ (AIStudio, MotionLIVE, VideoMocap) are never touched.

iClone must be restarted after every install/update to load the new plugin code -- there is no live-reload of main.py on disk. (You can hot-swap runtime behavior once the bridge is up, by --exec-ing new code through it -- see "Persistent namespace" below -- but that only affects the running session, not what gets loaded on the next restart.)

If iClone prompts with a Windows Firewall dialog for a 127.0.0.1 bind, allow it -- the bind is localhost-only either way.

CLI usage

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 checks the bridge is alive and prints the product name, iClone version, and the embedded Python version (via RApplication + sys.version).
• --exec CODE runs a snippet of Python source inside iClone.
• --file PATH runs a .py file's contents inside iClone.
• --port (default 18800) must match TINQS_ICLONE_BRIDGE_PORT if you've overridden it for the iClone process's environment.
• --timeout (default 30 seconds) is the client socket timeout.

On a connection failure the client exits 1 with a hint to check that iClone is running and was restarted after install. On an exec-level error (an exception raised by your code inside iClone) it also exits 1, printing the traceback captured from iClone.

Example: list scene objects

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

The result convention

Whatever code you send is exec()'d inside iClone. If it sets a variable named result, that becomes the JSON result field of the response (falling back to repr() if it isn't JSON-serializable -- RLPy objects generally aren't). If your code doesn't set result, the response's result is null. stdout/stderr printed during execution are captured and returned as the response's stdout field.

Persistent namespace

All code you send runs against one shared namespace dict that persists for the life of the iClone session (until iClone is restarted or the plugin reloaded). This means:

python tools/iclone_bridge.py --exec "x = 41"
python tools/iclone_bridge.py --exec "result = x + 1"   # -> 42

variables and imports from one --exec/--file call are visible to the next one. RLPy is pre-imported into the namespace. Each new client connection is a fresh TCP connection, but the iClone-side namespace is not reset per-connection.

Error resilience

An exception in your code (e.g. 1/0) produces ok: false with the full traceback in error -- the bridge itself keeps running and will serve the next request normally; you don't need to restart iClone after a bad --exec.

Log file

%TEMP%\tinqs_iclone_bridge.log -- append-only, timestamped lines for: plugin startup, the bind result (and port), each request's id + ok/error status, and shutdown. If --ping can't connect, or the plugin doesn't seem to be running after a restart, check this file first. If it's not being created at all, the plugin likely failed to load -- check iClone's Script > Console Log window too.

Threading rule (read this before extending the plugin)

RLPy is not thread-safe and must only be touched on iClone's Qt main thread. In main.py:

• The socket-accept thread and per-connection handler threads (_accept_loop, _handle_conn) only move bytes and put/get on a queue.Queue. They never call RLPy or touch Qt objects.
• A QTimer created in initialize_plugin() (which itself runs on the main thread) polls that queue every ~50 ms and does all the actual exec() / RLPy work in _drain_queue() / _execute().

If you add new functionality to the plugin, keep any RLPy-touching code inside that QTimer callback path. Calling RLPy from a socket thread can crash or corrupt iClone.

Long-running code freezes iClone's UI

Submitted code runs synchronously on the Qt main thread. iClone's UI (and the bridge itself, since the same timer that answers other requests is blocked) will freeze for the duration of your --exec/--file call. This is fine for anything that takes a few seconds (an FBX export blocks the UI anyway) but avoid submitting code with long sleeps or unbounded loops.

Environment variable

• TINQS_ICLONE_BRIDGE_PORT -- set in iClone's process environment before launch to override the default port 18800. Pass the matching --port to the client.

Security note

The bridge executes arbitrary Python with full RLPy access. It only binds to 127.0.0.1 -- there is no authentication beyond "only processes on this machine can connect." Do not change the bind address.