satoruhiga/claude-touchdesigner/td-guide

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 all .md files in reference/ (REQUIRED for all tasks)
2. Verify parameter names using op.TDAPI.GetParameterList()
3. Ask yourself: "Do I have sufficient reliable information to proceed?"
4. 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

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)

1. 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.

Skill Maintenance

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

1. Propose updates to the relevant .md files in this skill
2. Show the user the proposed changes before applying
3. Update SKILL.md or reference/*.md as appropriate

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