Extensions

TouchDesigner's extension system attaches Python classes to COMPs, providing organized, reusable behavior.

Basics

An extension is a Python class defined in a text DAT, attached to a COMP via the Extension parameter. Methods can be "promoted" to be callable directly on the COMP.

class MyExtension:
    def __init__(self, ownerComp):
        self.ownerComp = ownerComp

    def DoSomething(self):
        """Promoted method (uppercase) — callable as op.myComp.DoSomething()"""
        pass

    def helperMethod(self):
        """Non-promoted method — callable as op.myComp.ext.MyExtension.helperMethod()"""
        pass

Lifecycle Methods

onDestroyTD(self)

Called on the old extension instance before TD reinitializes with a new one. Essential for clean teardown.

def onDestroyTD(self):
    """Clean up before reinitialization."""
    # Cancel timers, close connections, remove callbacks
    pass

Warning

Without onDestroyTD, old extension instances linger in memory due to Python garbage collection issues (circular references, cached callbacks). Always implement it.

onInitTD(self)

Called at the end of the frame after the extension initialized. Use for post-init setup that needs a fully-cooked network.

def onInitTD(self):
    """Called after the frame the extension was created."""
    # Safe to access other extensions and cooked operators here
    pass

Initialization and TDN Import Timing

Critical: onInitTD runs BEFORE TDN import

If your extension lives inside a TDN-strategy COMP (or the extension's ownerComp is one), onInitTD fires before TDN reconstruction completes. Any state your extension sets up — created operators, parameter values, stored data, internal network structure — is overwritten when the TDN import runs.

Why this happens

Embody uses TDN (TouchDesigner Network) files to externalize COMP contents as diffable JSON. On project open and after every save, Embody reconstructs TDN COMPs by calling ImportNetwork with clear_first=True — this deletes all children inside the COMP and recreates them from the .tdn file.

The timing sequence on project open:

1. COMP shell is created — the COMP exists but its children haven't been imported yet
2. Extension initializes — __init__ runs, then onInitTD fires at end of frame
3. TDN import runs (frame 60) — deletes all children, recreates network from .tdn file
4. Extension state is lost — anything onInitTD set up inside the COMP is gone

A similar sequence occurs on every Ctrl+S due to the strip/restore cycle: children are stripped before save, then re-imported afterward. Extensions may reinitialize during this process.

The fix: defer initialization

Use run() with delayFrames to push your setup code past the TDN import:

class MyFeatureExt:
    def __init__(self, ownerComp):
        self.ownerComp = ownerComp

    def onInitTD(self):
        # DON'T set up state here — it will be overwritten by TDN import.
        # Instead, defer to after the import completes:
        run('args[0].postInit()', self, delayFrames=5)

    def postInit(self):
        """Runs after TDN import is complete. Safe to set up state here."""
        # Create operators, set parameters, build internal state
        child = self.ownerComp.op('my_child')
        if child:
            child.par.value0 = self.computeInitialValue()

Guidelines

Rule	Reason
Always defer initialization inside TDN COMPs	onInitTD fires before import — any setup is overwritten
Make deferred init idempotent	It may run multiple times: project open, every save, manual reimport
Null-check operators in deferred init	During strip phase, children are temporarily gone
Use store() on the COMP for persistent state	Storage on the COMP itself survives TDN import (it's preserved in phase 6a)
Use a delay of at least 5 frames	The import runs across multiple phases; 5 frames provides sufficient margin

How to tell if you're inside a TDN COMP

Check whether your COMP (or an ancestor) has a TDN entry in the externalizations table. In Claude Code, call get_externalizations and look for a tdn strategy on the COMP path. If your extension is a child of a TDN-strategy COMP, this timing issue applies to you.

Extensions outside TDN COMPs are unaffected

If your extension's ownerComp is not managed by TDN (e.g., it's a TOX-strategy COMP or not externalized at all), onInitTD behaves normally — no deferral needed.

Extension Referencing

# Promoted methods (uppercase) — called directly on the component:
op.Embody.Update()
op.Embody.Save()

# Non-promoted methods (lowercase) — through ext:
op.Embody.ext.Embody.getExternalizedOps()

# Check if extension exists:
if hasattr(op.myComp.ext, 'MyExtension'):
    op.myComp.ext.MyExtension.doSomething()

Never cache extension references

Extension instances become stale when TD reinitializes them (e.g., when source code changes on disk). Always call inline:

# CORRECT — always call inline:
self.ownerComp.ext.Embody.SomeMethod()

# WRONG — cached reference goes stale:
ext = self.ownerComp.ext.Embody
ext.SomeMethod()  # May call the dead old instance

extensionsReady Guard

Parameter expressions that reference extension-promoted attributes must guard against initialization timing:

# In a parameter expression:
parent().MyExtensionProperty if parent().extensionsReady else 0

Without this, TD raises "Cannot use an extension during its initialization."

Creating Extensions via MCP

Use the create_extension Envoy tool to create a fully wired extension:

create_extension(
    parent_path="/project1",
    class_name="MyExtension",
    code="class MyExtension:\n    def __init__(self, ownerComp):\n        self.ownerComp = ownerComp"
)

This creates a baseCOMP with a text DAT containing the extension class, properly wired up and initialized.

Naming Convention

Extension classes and their source DATs must follow the NameExt convention:

• EmbodyExt — class name EmbodyExt, DAT name EmbodyExt
• EnvoyExt — class name EnvoyExt, DAT name EnvoyExt
• TestRunnerExt — class name TestRunnerExt, DAT name TestRunnerExt