touchdesigner

TouchDesigner 指南

使用此技能通过 MCP API 创建、修改或调试 TouchDesigner 网络。

---

严重提示：你的先验知识并不可靠

TouchDesigner 是一个可视化编程环境。你预训练得到的 TD 知识很可能是错误的。

假设自己的记忆完全不可靠。 务必先收集准确信息：

• 本文档和参考文件
• Context7 中的官方 TD API 文档
• op.TDAPI.GetParameterList() 中的参数名称

开始任何任务之前

输出“先收集信息”，并在实施前收集可靠信息。

1. 阅读 reference/ 中的所有 .md 文件（所有任务都必须执行）
2. 使用 op.TDAPI.GetParameterList() 验证参数名称
3. 问问自己：“我是否掌握了足够可靠的信息，可以继续了？”
4. 只有在答案为是时，才开始实施

---

必须：先阅读所有参考文件

在开始任何实施工作之前，必须阅读 reference/ 中的所有 .md 文件。

这些文件包含有关算子创建、布局、错误处理和最佳实践的关键模式，这些内容与标准 TD API 不同。

---

op.TDAPI——务必使用以下工具

必须使用 op.TDAPI 实用工具，而不是原始 TD API。

创建算子

# 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

串联算子

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

检查错误

# 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

设置前验证参数

# 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/basics.md（必读）
算子系列、数据转换	reference/operator-families.md
Geometry COMP、实例化	reference/geometry-comp.md
渲染、Camera、Light	reference/rendering.md
GLSL TOP/MAT、着色器	reference/glsl.md
反馈循环、模拟	reference/operator-tips.md

---

外部资源

在需要查询以下内容时，使用 Context7 查找官方 TouchDesigner API 文档：

• 算子类型及其参数
• Python API 详情（td 模块、Op 类等）
• 内置函数和类

此技能提供 TD 特定的模式和最佳实践。Context7 提供官方 API 参考。

开始实施前

编码前应考虑多种方案。

1. 列出 2～3 种实现目标的方法
2. 评估每种方法的优缺点：
   • 简洁性（更少的转换、统一的系列）
   • 性能（GPU 与 CPU、数据流效率）
   • 可扩展性（后续是否易于修改）
   • 可读性（网络是否清晰）
3. 根据评估选择最有效的方法

示例：“创建球形实例化粒子”

方案	优点	缺点
A：Sphere SOP → soptoCHOP → Geo + POP	常见模式	混合系列，需要额外转换
B：Sphere POP → Null → Geo(In/Out POP)	POP 系列统一、数据流直接	不够熟悉
C：Sphere POP → poptoCHOP → instancing	定位灵活	需要额外的转换步骤

→ 选择 B：系列统一、数据流高效、网络结构清晰

必须遵守的规则

1. 创建算子后始终设置 viewer = True（符合 UI 默认值）
2. 复杂操作后始终检查错误：op('/path').errors(recurse=True)
3. 任何引用连接前都使用 Null 作为中间节点
4. 创建前先确认布局，避免算子重叠
5. 引用附近算子时使用相对路径（同级或相近层级）
6. Geometry COMP：在父级创建形状——不要在 COMP 内创建几何体；应在父级准备好后通过 In/Out 传入

可用的 MCP 工具

• td_execute：在 TD 中运行 Python 代码
• td_pane：获取当前网络编辑器状态
• td_selection：获取选中的算子
• td_operators：列出指定路径下的算子

插件资源

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

算子家族（快速参考）

家族	用途	数据类型
SOP	表面／几何体	3D 几何体（CPU）
POP	点／粒子	3D 点（GPU）
TOP	纹理	2D 图像
CHOP	通道	基于时间的数据
DAT	数据	表格、文本
COMP	组件	容器、场景

有关家族的详细信息、算子列表和跨家族模式，请参阅 reference/operator-families.md。

---

技能维护

当用户对这项技能提供反馈（更正、改进、缺失的模式等）时：

1. 提出对这项技能中相关 .md 文件的更新
2. 在应用更改之前向用户展示拟议的更改
3. 根据需要更新 SKILL.md 或 reference/*.md

这样可以确保技能保持准确，并根据实际使用情况不断改进。