/fundamentals

name: fundamentals
description: This skill should be used when working with TouchDesigner through the touchdesigner-mcp tools — for example when asked to "build a network in TouchDesigner", "create a node", "wire operators together", add or configure a TOP/CHOP/SOP/DAT/COMP/MAT, inspect or edit a .toe or .tox file, set node parameters, or otherwise construct or modify a TouchDesigner project. Provides the conventions the tools expect (node paths, nodeType and parameter naming, family-bound wiring), the cook model that explains what the tools report, the inspect-create-verify workflow, and the procedures for reading families, operator types, and parameter names live from the running TouchDesigner instead of recalling them.
version: 0.1.0

TouchDesigner Fundamentals

What TouchDesigner Is

TouchDesigner is a node-based visual programming environment for real-time procedural content: interactive installations, live visuals, data visualization, and control systems. A TouchDesigner project is a network of **operators** — small processing nodes wired together into a directed graph, cooked continuously at the project's frame rate rather than run once and discarded. Projects save as `.toe` files (a full project) or `.tox` files (a reusable component embeddable inside another project). Treat every task here as manipulating that node graph, either through the touchdesigner-mcp tools connected to a live TouchDesigner instance, or by reasoning about `.tox`/`.toe` structure.

The MCP tools substitute for the two things a human normally does with the mouse: browsing the OP Create dialog (its category tabs mirror the six operator families below) and dragging wires between operators in the network editor. Every action described in this skill has a direct tool equivalent — there is no need to open TouchDesigner's UI to inspect, build, or debug a network reachable through these tools.

Work through the bundled MCP tools rather than assuming network contents by memory: `get_td_info`, `get_td_nodes`, `get_td_node_parameters`, `get_td_node_errors`, `create_td_node`, `update_td_node_parameters`, `delete_td_node`, `exec_node_method`, `execute_python_script`, `get_td_classes`, `get_td_class_details`, `get_td_module_help`, `get_top_image`, and `describe_td_tools`. At runtime these are namespaced (e.g. `mcp__plugin_touchdesigner_touchdesigner__create_td_node`); refer to them by their logical name below and let the runtime prefix resolve automatically. When a tool's exact input shape is unclear, call `describe_td_tools` rather than guessing at parameter names.

Operator Families

Every operator belongs to exactly one **family**, determined by the kind of data flowing through it. Family membership decides which wires are legal and which suffix the operator's `nodeType` carries.

Which families exist, and which operator types belong to each, is a property of the **installed TouchDesigner build** — the roster grows between releases, and a family that did not exist in an older build appears without warning in a newer one. Do not work from a remembered list. Discover the current one with the procedure in `references/operator-guide.md`, which reads it structurally from `td.OP.__subclasses__()` and each class's `family` attribute.

The rules that hold regardless of the roster:

• Operators of the **same family** wire together directly, an output connector into an input connector.
• A wire **never** crosses families. Crossing needs an explicit converter operator, named `<source>to<TARGET>` — look up which ones the build actually ships rather than recalling a pair; the real set is much larger than the few commonly cited.
• Materials attach through the Geometry COMP's `material` parameter, not through a wire.
• CHOP values commonly drive parameters of other families through a parameter export or an expression rather than a wire at all — see Wiring below.

Node Paths and Hierarchy

Every node has an absolute path rooted at the project, e.g. `/project1/container1/noise1`. Nodes always live *inside* a COMP — `/project1` itself is a COMP, and any COMP can contain child operators of any family. Before creating anything, call `get_td_nodes` on the intended parent path to see what already exists; never assume a network's contents from a prior turn or from memory of a similar project.

`parentPath` passed to `create_td_node` must be an existing COMP. Creating into the wrong parent is a frequent mistake in deeply nested networks — re-verify the parent path with `get_td_nodes` immediately before creating, rather than trusting an earlier listing.

Node names must be unique among siblings; if a requested `nodeName` collides with an existing child, TouchDesigner silently renames the new node (typically by appending or incrementing a numeric suffix) rather than raising an error. Never assume the requested name is the name that resulted — read the resolved path back from `create_td_node`'s response, and use that path for every subsequent call against the node.

Creating Nodes: nodeType and Parameter Naming

`create_td_node` takes a `nodeType` matching TouchDesigner's Python class-name convention: lowercase-first, family-suffixed CamelCase — `textTOP` has the shape, `TextTop` and `text_top` do not. The convention is stable; the set of names obeying it is not. Getting a name wrong — an extra or missing letter, wrong case on the suffix — is the single most common tool-call failure, and a plausible-looking name is exactly the kind that fails.

Confirm every unfamiliar `nodeType` before using it. The cheapest check is `getattr(td, '<name>', None)` through `execute_python_script`; `references/operator-guide.md` covers that and the roster-browsing alternatives.

{ "parentPath": "/project1", "nodeType": "textTOP", "nodeName": "title" }

Set parameters through `update_td_node_parameters`'s `properties` map, keyed by TouchDesigner's **lowercase parameter name**, not the capitalized label shown in the UI. The mappin