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.

Release hooks: a TEXT DAT named pre_release that is a DIRECT child of the target runs on a STAGED COPY in /sys/quiet — the live comp is never touched, file-sync is disabled on the copy (no write-through to source files), extensions are NOT initialized there and par callbacks don't fire (shape via direct par/DAT/op edits, or use hook_mode='live' for extension logic). A raise aborts the export and keeps the copy as <name>_release_failed for same-session inspection (/sys is not saved; post_release skipped). A direct-child Text DAT named post_release runs on the ORIGINAL after the save whenever pre_release completed — even when the save failed. Both hook DATs are deleted from the copy, so hook code never ships in the artifact. args[0] = resolved save path; post_release also gets args[1] = success. Hooks run synchronously on the main thread — keep them fast, defer uploads. Nested exports from inside a hook run plain (no hooks, no second copy). hook_mode='live' restores in-place semantics (mutations persist, hooks ship dormant in the tox); run_hooks=False skips hooks and ships them as-is (the self-updater's backup uses it). Exports whose target is — or contains — the live Embody COMP are never copy-staged (Embody-self runs live-mode; hooks on a container holding Embody are skipped with a warning in copy mode). op.Embody.ReleaseAll(root=None, out_dir=None) (or the Release All pulse) batch-exports every component that is BOTH Embody-tracked AND hook-bearing — tracked-and-hooked is the opt-in (third-party comps ship with their authors' hook DATs and are never batch-released); per-component failures log and continue.

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').