Engine COMP 完全ガイド | 使い方・パラメータ解説【TouchDesigner】

記事更新の通知はXでアナウンス٩(๑❛ᴗ❛๑)
→ @maru6o6をフォロー

概要 📖 – 部品を別プロセスで動かす
- 主な用途 🎯
- データフロー 🔄
パラメータ解説 ⚙️
実践アイデア 💡
関連オペレータ 🔗
Info COMP情報 📊
トラブルシューティング ⚠️
- よくある問題と解決策 🔧
参考資料 📚
- その他 🔗
- 公式リソース 📖

概要 📖 – 部品を別プロセスで動かす

Engine COMPは、.tox ファイルを別プロセスの TouchEngine インスタンスでロード・実行し、メインプロジェクトから入出力を介して扱うコンポーネント COMPです。別プロセス実行のためクラッシュ分離・マルチプロセス並列化・ホットリロードといった本番運用上の利点を得られ、不安定な .tox や重い計算を安全にメインプロジェクトから切り離して扱えます。

主な用途 🎯

クラッシュ分離のため不安定な .tox コンポーネントを別プロセスで実行し、メインプロジェクトの巻き添えクラッシュを防ぐ
マルチプロセス並列化で重い処理を別 TouchEngine インスタンスに逃がし、メインプロセスのフレームレート低下を回避
ホットリロード機能で .tox を編集・保存するたびに動作中のメインプロジェクトへ即時反映 (Reload on Crash + Reload で安全な開発サイクル)
サードパーティ製モジュールを信頼境界の外側で実行するサンドボックスとして利用
本番展示での冗長化として複数 Engine COMP に同一 .tox を割り当て、片方がクラッシュしても瞬時に切替可能な構成を組む

データフロー 🔄

メインプロジェクト
 ↓
Engine COMP (Tox File 指定)
 ↓
TouchEngine 別プロセス起動
 ↓
.tox 内部のロジック実行
 ↓
入出力フレームバッファ経由でメインプロジェクトへ結果を返す

Tips

初心者の方は、以下日本語書籍も手元にあると安心です。

リンク

まる。

実際の案件事例まで踏み込んで紹介されていて、効率よくスキルアップするなら必携の二冊です！

パラメータ解説 ⚙️

Engine Page ⚙️

Tox File `.file` 📂

TouchEngine がロードする .tox ファイルへのパス:

Tox File: file — TouchEngine インスタンスにロードする .tox ファイルへのパス (絶対パスまたは .toe 基準の相対パス)

Unload / Reload `.unloadreload` 🔄

ロード済みコンポーネントの破棄・再ロード:

Unload: unload — 現在ロード中のコンポーネントを TouchEngine から破棄するパルスボタン
Reload: reload — 現在ロード中のコンポーネントを再ロード (編集中の .tox 変更を即時反映)

Reload on Crash `.reloadoncrash` 🛡️

TouchEngine クラッシュ時の自動再起動設定:

Reload on Crash: reloadoncrash — TouchEngine インスタンスが何らかの理由で終了した場合に自動で再起動するチェックボックス (本番展示での冗長化に必須)

Asset Paths `.assetpaths` 🗂️

コンポーネント内部からの相対パス解決方法:

Asset Paths: assetpaths — TouchEngine 内でロードされたコンポーネント内部からの相対ファイルパスをどう解決するか (メニュー)

Callbacks DAT `.callbacks` 📝

TouchEngine イベント通知を受け取る Callbacks DAT:

Callbacks DAT: callbacks — TouchEngine インスタンスのイベント (ロード完了 / エラー / クラッシュ等) で呼ばれるコールバック DAT のパス

Tune Page 🎚️

Clock `.clock` ⏱️

TouchEngine インスタンスとメインプロジェクトの時間軸接続方式

項目	内部名	説明
Synchronized	`.synced`	Engine COMP と TouchEngine インスタンス間で時間軸を厳密に同期
Independent	`.independent`	TouchEngine インスタンスが自身の内部クロックで独立動作

Match Local Component Rate `.matchrate` 🔁

メインプロジェクトと TouchEngine のレート一致設定:

Match Local Component Rate: matchrate — オンの場合、Engine COMP と同じレートで TouchEngine 内のコンポーネントをクック

Frames per Second `.fps` 🎞️

TouchEngine 内コンポーネントのクックレート:

Frames per Second: fps — TouchEngine 内のコンポーネントをクックするフレームレート (Match Local Component Rate がオフのときのみ有効)

Wait for Render `.wait` ⏳

重いフレームのドロップ vs 待機挙動:

Wait for Render: wait — TouchEngine 内のフレームクックに時間がかかった際、Engine COMP がドロップせず待機するかを切替。Out Buffer Frames の値の影響を受ける (例: 4 の場合は 4 フレーム前の完了を待つ)

Render Timeout `.timeout` ⏰

フレーム待機の打ち切り時間 (ミリ秒):

Render Timeout: timeout — Wait for Render が有効な状態でフレーム完了を待つ最大ミリ秒。この時間を超えると TouchEngine は待機を諦める

In Buffer `.inbuffer` 📥

TouchEngine への入力フレームキュー設定:

In Buffer Auto: inauto — 入力フレームのキュー数を自動管理
In Buffer Frames: inframes — TouchEngine インスタンスへ渡す前にキューする入力フレーム数 (TouchEngine 側の time-slice 揺らぎを吸収するため CHOP 入力には先行供給が必要)

Out Buffer `.outbuffer` 📤

TouchEngine からの出力フレームキュー設定:

Out Buffer Auto: outauto — 出力フレームのキュー数を自動管理
Out Buffer Frames: outframes — TouchEngine インスタンスから受け取った後にキューする出力フレーム数 (Engine COMP 側の time-slice 揺らぎを吸収するため CHOP 出力には先行バッファが必要)

InitStart Page 🚀

Pre-Roll `.preroll` ⏪

初期化時のウォームアップ実行時間:

Pre-Roll: preroll — 初期化時に ready state へ移行する前に実行するウォームアップ時間

Pre-Roll Units `.prerollunits` 📏

Pre-Roll 値の単位

項目	内部名	説明
F	`.frames`	Pre-Roll をフレーム数で測定
S	`.seconds`	Pre-Roll を秒で測定

Ready when `.readywhen` ✅

Engine COMP が ready state に遷移する条件

項目	内部名	説明
Output Buffered	`.buffered`	TouchEngine がコンポーネントをロードし、入出力バッファを満たすフレームのクックが完了したときに ready 状態へ遷移

Start when Initialized `.startoninit` ▶️

初期化完了時の自動再生開始設定:

Start when Initialized: startoninit — オンの場合、初期化が完了して ready 状態になった瞬間に再生を自動開始

Initialize / Start / Play `.controlpulses` 🎮

TouchEngine インスタンスの制御パルス:

Initialize: initialize — .tox ファイルを再ロードし TouchEngine インスタンスを再起動するパルス
Start: start — TouchEngine インスタンス内コンポーネントの再生を開始するパルス
Play: play — TouchEngine インスタンス内のクック動作のオン/オフ切替
Go to Done: gotodone — Engine COMP を done 状態へ強制遷移させるパルス

On Done `.ondone` 🏁

Engine COMP が done 状態になった際に実行する処理

項目	内部名	説明
Do Nothing	`.donothing`	状態変更以外は何もせず TouchEngine が継続実行
Pause	`.pause`	ロード中コンポーネントの再生を一時停止
Unload	`.unload`	ロード中コンポーネントを破棄
Re-Initialize	`.reinit`	ロード中コンポーネントを破棄してから再初期化
Re-Start	`.restart`	コンポーネントはロードしたまま再生を再開
Quit Engine Process	`.quit`	TouchEngine プロセスを完全停止

Advanced Page 🔧

On Engine COMP Create `.oncompcreate` 🌱

Engine COMP 作成時 (プロジェクトロード時など) の動作

項目	内部名	説明
Do Nothing	`.nothing`	Engine COMP 作成時は何もしない
Launch Engine	`.launch`	Engine COMP 作成と同時に TouchEngine プロセスを起動 (指定コンポーネントはロードしない)
Load and Initialize	`.initialize`	TouchEngine プロセスを起動し指定コンポーネントもロード・初期化して ready 状態へ

Launch / Quit Engine Process `.engineprocess` 🔌

TouchEngine プロセスの起動・停止:

Launch Engine Process: launch — TouchEngine プロセスが起動していない場合に起動するパルス
Quit Engine Process: quit — TouchEngine プロセスを停止するパルス

Allow UI `.allowui` 🖥️

TouchEngine 内コンポーネントの UI 表示許可:

Allow UI: allowui — オンにすると TouchEngine 内でロードされたコンポーネントが Window COMP を開いたり Perform モードに入ったりできる (実行はトップレベルコンポーネントのパラメータまたはスクリプトから行う)

実践アイデア 💡

Example 1: 重いリアルタイム解析のクラッシュ分離 🛡️

メインプロジェクト → Engine COMP (Tox File=heavy_analyzer.tox, Reload on Crash=ON) → TouchEngine 別プロセス → 解析結果出力 → メインプロジェクトへ

リアルタイム機械学習推論や重い CV 処理のように落ちる可能性のあるロジックを Engine COMP に隔離し、Reload on Crash をオンにすることで万一 TouchEngine 側がクラッシュしても自動で再起動。本番展示・常時稼働インスタレーションでメインプロジェクトが連鎖クラッシュする最悪ケースを防ぐ運用パターン。

解析ロジックを別の .tox として保存 (例: heavy_analyzer.tox)
メインプロジェクトに Engine COMP を配置し Tox File パラメータに保存先パスを指定
Reload on Crash をオンにして TouchEngine 側クラッシュ時の自動再起動を有効化
Callbacks DAT を設定してロード・エラー・クラッシュイベントをログに残す
Engine COMP の出力 CHOP / TOP / DAT をメインプロジェクトのロジックに接続

Example 2: マルチプロセス並列化によるフレームレート維持 🚄

メインプロジェクト (60fps) → Engine COMP A (Clock=Independent, fps=30) → 重い処理 → 結果をメインへ返却 → メインは 60fps を維持

GPU バウンドな重いレンダリングや CPU バウンドなシミュレーションを Engine COMP の Independent クロックで別プロセスに逃がし、独自フレームレートで動かす。メインプロジェクトは入出力バッファ経由で結果を受け取るだけなので、重い処理が原因でメインの 60fps が落ちるリスクを構造的に解消できる。

重い処理を .tox に切り出し Engine COMP の Tox File に指定
Tune Page の Clock を Independent に設定し独立クロック動作にする
Frames per Second で TouchEngine 側の目標 fps を指定 (例: 30fps)
In Buffer Frames / Out Buffer Frames を 4〜8 程度に調整し time-slice 揺らぎを吸収
メインプロジェクトの GPU/CPU 使用率を Performance Monitor で計測し、目標 fps が安定するかを検証

Example 3: ホットリロードによる安全な開発サイクル 🔁

別 TouchDesigner で .tox を編集・保存 → メインプロジェクトの Engine COMP で Reload パルス → TouchEngine 内コンポーネントが即時更新 → メインプロジェクトは継続動作

本番動作中のメインプロジェクトを止めずに、別の TouchDesigner ウィンドウで .tox を編集・保存しメインの Engine COMP で Reload を押すだけで内容を即時反映できる。長時間動かしているインスタレーションの微調整や、ライブパフォーマンス中の VJ パッチ差し替えにも有効。

メインプロジェクトの Engine COMP に開発中の .tox をロードして実行
別ウィンドウで同じ .tox を開き編集・保存
メインプロジェクトの Engine COMP の Reload パルスボタンを押す
TouchEngine 内のコンポーネントが新バージョンに即時差し替わる (メインプロジェクトはクラッシュなく継続)
On Done を Re-Initialize にしておけば done 状態でも自動的に最新版を再ロード可能

Example 4: サードパーティ製モジュールのサンドボックス実行 📦

メインプロジェクト → Engine COMP (Tox File=thirdparty_plugin.tox, Allow UI=OFF) → TouchEngine 別プロセスで完全隔離実行 → 入出力のみメインへ

出所不明なコミュニティ製 .tox やプラグインを動かすとき、Engine COMP の別プロセス境界を信頼境界として使う運用。メインプロジェクトのメモリ空間や Python 環境から隔離されるため、不正な Python 実行や予期しないリソース消費でメイン側を巻き込む事故を構造的に防げる。

信頼性が不明な .tox を Engine COMP の Tox File に指定
Allow UI はオフのままにして Window COMP / Perform モード経由の予期しない UI 制御を阻止
Callbacks DAT でロード状況とエラーを監視できる状態にする
Engine COMP の入出力境界経由でのみメインプロジェクトと連携 (Python オブジェクトの直接参照は発生しない)
問題発生時は Quit Engine Process パルスで TouchEngine プロセスごと即座に停止

Info COMP情報 📊

Engine COMP は Info CHOP / Info DAT による詳細情報取得に対応しています。

COMP 固有情報 📦

num_children: コンポーネント内部の子 OP の総数
num_dats: 内部 DAT の数
num_chops: 内部 CHOP の数
num_tops: 内部 TOP の数
num_sops: 内部 SOP の数

汎用オペレータ情報 🔄

total_cooks: プロセス開始からのクック回数
cook_time: 最後のクック時間 (ミリ秒)
cook_frame: 最後にクックされたフレーム番号
warnings: 警告数
errors: エラー数

Engine COMP 固有情報 📊

engine_running: TouchEngine プロセスが起動中なら 1、停止中なら 0
engine_ready: Engine COMP が ready 状態に到達していれば 1
engine_loaded: TouchEngine 内にコンポーネントがロード済みであれば 1
engine_fps: TouchEngine 内コンポーネントの実測クックレート

トラブルシューティング ⚠️

よくある問題と解決策 🔧

❌ Problem: Tox File を指定したのに TouchEngine がロードされない
✅ Solution:

Tox File パスが現在のマシンで実在するか確認 (相対パスは .toe 基準)
Advanced Page の On Engine COMP Create が Do Nothing になっていないか確認 (この場合は手動で Launch Engine Process + Initialize パルスが必要)
Callbacks DAT を設定してロード時のエラーメッセージを確認

❌ Problem: TouchEngine プロセスが頻繁にクラッシュする
✅ Solution:

Reload on Crash をオンにして自動復旧を有効化 (本番運用の冗長化に必須)
.tox 内部のロジックを最小構成から段階的に追加してクラッシュ要因を切り分け
Callbacks DAT でクラッシュイベントをログに残し、再現条件を特定

❌ Problem: 出力フレームがメインプロジェクトに届かない / 遅延する
✅ Solution:

In Buffer Frames / Out Buffer Frames を増やして time-slice 揺らぎを吸収
Wait for Render をオンにしてフレームドロップを抑制 (代わりに遅延が増える)
Render Timeout を適切に設定し待機の打ち切り点を制御

❌ Problem: ホットリロードで Reload を押しても内容が反映されない
✅ Solution:

別ウィンドウで開いている .tox を確実に保存してから Reload パルスを押す
On Done を Re-Initialize に設定しておくと done 状態でも自動で最新版を再ロード
ホットリロード相当の挙動が必要なら Initialize パルスで完全な再初期化を行う

参考資料 📚

その他 🔗

公式リソース 📖

この記事はLLMと共に内容を執筆、更新しています。
最新バージョンとの項目差異など、情報の不一致を見つけた心優しい方はXもしくはInsta、メールなどよりサイト管理者までご連絡ください😎

まる。

お仕事のご依頼はDM又はメールにて。
━━━━━━━━━━━━━━━━━
Python/Touchdesigner/M5Stackをこよなく愛すフルスタックエンジニア。
専門は生理心理学、趣味はヨガやサウナ、EMS電気風呂などヘルスケア全般。
脳波や筋電、心拍を中心とした生体情報のセンシング＆インタラクティブアートづくりがライフワーク。

普段はワントゥーテンという会社で空間演出エンジニアをしています。
リファラル採用お繋ぎできますので、我こそはという尖った方は経歴と希望職種添えてDMください(エンジニア以外、営業職等もOK)。
ご飯行きましょう。

↓日常垢
Instagram：＠malmal0v0

概要 📖 – 部品を別プロセスで動かす

主な用途 🎯

データフロー 🔄

パラメータ解説 ⚙️

Engine Page ⚙️

Tox File .file 📂

Unload / Reload .unloadreload 🔄

Reload on Crash .reloadoncrash 🛡️

Asset Paths .assetpaths 🗂️

Callbacks DAT .callbacks 📝

Tune Page 🎚️

Clock .clock ⏱️

Match Local Component Rate .matchrate 🔁

Frames per Second .fps 🎞️

Wait for Render .wait ⏳

Render Timeout .timeout ⏰

In Buffer .inbuffer 📥

Out Buffer .outbuffer 📤