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.

• Read all .md files in reference/ (REQUIRED for all tasks)

• Verify parameter names using op.TDAPI.GetParameterList()

• Ask yourself: "Do I have sufficient reliable information to proceed?"

• Only if yes, start implementation

REQUIRED: Read All Reference Files First

You MUST read all .md files in reference/ before any implementation.

These files contain essential patterns for operator creation, layout, error handling, and best practices 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

When working on... Read...

ALL tasks reference/basics.md (REQUIRED)

Operator families, data conversion reference/operator-families.md

Geometry COMP, Instancing reference/geometry-comp.md

Rendering, Camera, Light reference/rendering.md

GLSL TOP/MAT, shaders reference/glsl.md

Feedback loops, simulations reference/operator-tips.md

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.

• List 2-3 different ways to achieve the goal

• 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)

• Choose the most effective approach based on the evaluation

Example: "Create instanced particles in a sphere shape"

Approach Pros Cons

A: Sphere SOP → soptoCHOP → Geo + POP Familiar pattern Mixed families, extra conversion

B: Sphere POP → Null → Geo(In/Out POP) POP unified, direct data flow Less familiar

C: Sphere POP → poptoCHOP → instancing Flexible positioning Extra conversion step

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

Required Rules

• Always set viewer = True after creating operators (matches UI default)

• Always check errors after complex operations: op('/path').errors(recurse=True)

• Use Null as intermediary before any reference connection

• Verify layout before creating to avoid overlapping operators

• Use relative paths for references to nearby operators (same level or close hierarchy)

• 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)

Family Purpose Data Type

SOP Surface/Geometry 3D geometry (CPU)

POP Point/Particle 3D points (GPU)

TOP Texture 2D images

CHOP Channel Time-based data

DAT Data Tables, text

COMP Component Containers, scenes

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

Skill Maintenance

When the user provides feedback about this skill (corrections, improvements, missing patterns, etc.):

• Propose updates to the relevant .md files in this skill

• Show the user the proposed changes before applying

• Update SKILL.md or reference/*.md as appropriate

This ensures the skill stays accurate and improves over time based on real usage.