TouchDesigner Guide

Use this skill when creating, modifying, or debugging TouchDesigner networks via the MCP API.

CRITICAL: Your Prior Knowledge is Unreliable

TouchDesigner is a visual programming environment. Your pre-trained knowledge about TD is very likely incorrect.

Assume your memory is completely unreliable. Always gather accurate information first:

• This document and reference files
• Context7 for official TD API documentation
• op.TDAPI.GetParameterList() for parameter names

Before Starting ANY Task

Output "Gathering information first" and collect reliable information before implementation.

1. Read reference/basics.md (REQUIRED for all tasks)
2. Read topic-specific reference files as needed
3. Verify parameter names using op.TDAPI.GetParameterList()
4. Ask yourself: "Do I have sufficient reliable information to proceed?"
5. Only if yes, start implementation

REQUIRED: Read basics.md First

You MUST read reference/basics.md before any implementation.

This file contains essential patterns for operator creation, layout, and error handling that differ from standard TD API.

op.TDAPI - ALWAYS USE THESE

You MUST use op.TDAPI utilities instead of raw TD API.

Create Operators

# ALWAYS use CreateOp (auto sets viewer=True, handles docked operators)
new_op = op.TDAPI.CreateOp(base, gridSOP, 'grid1', x=0, y=0)

# DON'T use raw API directly
# new_op = base.create(gridSOP, 'grid1')  # WRONG - misses viewer, docked handling

Chain Operators

# Auto-connects and layouts with 200px spacing
chain = op.TDAPI.ChainOperators([grid, noise, null])

Check Errors

# Pass op() object, NOT string path
op.TDAPI.CheckErrors(op('/project1/base1'), recurse=True)

# IMPORTANT: Error cache updates on frame boundaries
# After fixing, check in SEPARATE td_execute call:
#   td_execute 1: Fix the error
#   td_execute 2: cook + CheckErrors

Verify Parameters Before Setting

# TD parameter names are unpredictable (e.g., radius vs radx/rady/radz)
# ALWAYS check first using GetParameterList:
params = op.TDAPI.GetParameterList('sphereSOP')
print(params)  # ['radx', 'rady', 'radz', ...]

Reference Files

External Resources

Use Context7 to look up official TouchDesigner API documentation when you need:

• Operator types and their parameters
• Python API details (td module, Op class, etc.)
• Built-in functions and classes

This skill provides TD-specific patterns and best practices. Context7 provides official API reference.

Before Implementation

Consider multiple approaches before coding.

1. List 2-3 different ways to achieve the goal
2. Evaluate each approach's pros and cons:
   • Simplicity (fewer conversions, family unity)
   • Performance (GPU vs CPU, data flow efficiency)
   • Extensibility (easy to modify later)
   • Readability (network clarity)
3. Choose the most effective approach based on the evaluation

Example: "Create instanced particles in a sphere shape"

→ Choose B: unified family, efficient data flow, clean network structure

Required Rules

1. Always set viewer = True after creating operators (matches UI default)
2. Always check errors after complex operations: op('/path').errors(recurse=True)
3. Use Null as intermediary before any reference connection
4. Verify layout before creating to avoid overlapping operators
5. Use relative paths for references to nearby operators (same level or close hierarchy)
6. Geometry COMP: create shapes at parent level - Don't create geometry inside COMP; prepare at parent and pass via In/Out

MCP Tools Available

• td_execute: Run Python code in TD
• td_pane: Get current network editor state
• td_selection: Get selected operators
• td_operators: List operators at path

Plugin Assets

• TOX: ${SKILL_BASE}/../../toe/TouchDesignerAPI.tox

Operator Families (Quick Reference)

For detailed family info, operator lists, and cross-family patterns, see reference/operator-families.md.