Skip to content

TouchDesigner Development

This section covers TouchDesigner Python development patterns, best practices, and common pitfalls. While not specific to Embody, these patterns are essential for working effectively with TouchDesigner — especially when using Envoy and AI assistants.

Essential Concepts

  • Extensions — TouchDesigner's extension system for attaching Python classes to COMPs
  • Parameters — Accessing, setting, and creating parameters correctly
  • Threading — Running background tasks without blocking TD's UI
  • Common Mistakes — The most frequent pitfalls and how to avoid them

Quick Reference

Pull-Based Cook Model

TouchDesigner uses a pull-based cook system — operators only cook when something downstream demands their output. Changing a parameter makes the node "dirty" but does NOT trigger an immediate cook.

  • Always-cook operators: Output nodes (Movie File Out TOP, Audio Device Out CHOP, etc.) and Render TOPs cook every frame
  • Performance implication: Nodes with no viewer and no downstream output skip cooking — minimize visible viewers

op() vs opex()

# op() returns None if not found — silent failure:
node = op('/nonexistent/path')
node.par.tx = 5  # AttributeError: 'NoneType' has no attribute 'par'

# opex() raises an exception immediately:
node = opex('/nonexistent/path')  # Raises tdError with clear message

# ops() returns a LIST of matching operators (supports wildcards):
all_noises = ops('noise*')  # [noise1, noise2, noise3, ...]

Use opex() when the operator must exist. Use op() only when None is an acceptable result.

debug() vs print()

debug('value is', x)  # Output: "myScript line 42: value is 42" (with source info)
print('value is', x)  # Output: "value is 42" (no source info)

Always prefer debug() — it includes the source DAT name and line number.

Pre-Installed Python Packages

Available without installation: numpy, cv2 (OpenCV), requests, yaml (PyYAML), cryptography, attrs

Auto-imported (no import needed): math, re, sys, collections, enum, inspect, traceback, warnings

TD Documentation