externalize-operator

name	externalize-operator
description	MUST READ before calling externalize_op or save_externalization. Required workflow steps.

Externalize Operator Workflow

Tagging (includes save)

externalize_op tags the operator AND writes it to disk in one step (it calls Update() internally). No separate save is needed.

1. Tag and externalize: externalize_op on the operator (auto-detects type if omitted)
2. Verify: get_externalization_status to confirm dirty state and file path
3. Inspect: Verify file exists in embody/ via file inspection

Re-exporting After Changes

save_externalization force re-exports an already-externalized operator. Use it after modifying an operator in TD when you need to update its file on disk.

Creating Python Files for TouchDesigner

When creating Python files (scripts, extensions, test files, callbacks):

1. Create the textDAT in TouchDesigner first (via MCP create_op or in TD UI)
2. Write the Python code into the DAT (via MCP set_dat_content)
3. Tag the DAT for externalization (externalize_op) — Embody writes the .py file to disk

NEVER manually set the file and syncfile parameters — Embody handles all file path management.

Exporting a Portable Tox

Export any COMP as a self-contained .tox with all Embody metadata stripped:

• Via MCP: execute_python with op.Embody.ExportPortableTox(target=op('/path/to/comp'), save_path='/output/path.tox')
• Via UI: Manager UI > Actions popup > "Export portable tox"

The exported .tox works in any TD project with no missing file errors.

Checking Status

• get_externalizations — list all externalized operators with status
• get_externalization_status — get dirty state, build number, timestamp, file path for a specific operator

TDN Export — Palette COMP Handling

When exporting a TDN-strategy COMP whose network contains TD palette components (e.g. abletonLink, Widget components, anything under Samples/Palette/), Embody consults the Tdnpalettehandling par on the Embody COMP's TDN page:

• Ask (default): On first encounter of each palette COMP, a four-button dialog appears — Black Box (this COMP), Full Export (this COMP), Black Box for All, Full Export for All. The per-COMP choice is stored via comp.store('_tdn_palette_handling', ...) so repeated exports don't re-prompt.
• Black Box: reference the palette only, emit "palette_clone": true, skip internal children. Correct for stock palette COMPs.
• Full Export: export all children as if the COMP were a regular user COMP. Use only when palette internals have been heavily customized.

Check and override programmatically: op.Embody.par.Tdnpalettehandling = 'blackbox' | 'fullexport' | 'ask', or force a specific COMP: op('/path/to/comp').store('_tdn_palette_handling', 'fullexport').