td-builder-howto

Guides building, editing, and debugging TouchDesigner networks via the td-builder MCP servers.

1|Updated Jun 4, 2026
One-click install
npx skills add https://github.com/TrueFiasco/TD_Builder_alpha --skill td-builder-howto-truefiasco
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: td-builder-howto
Source: https://github.com/TrueFiasco/TD_Builder_alpha/tree/main/Agents/td-builder-howto
Command: npx skills add https://github.com/TrueFiasco/TD_Builder_alpha --skill td-builder-howto-truefiasco

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Working with TouchDesigner through the td-builder MCP servers involves silent failure modes — invisible GLSL compile errors, frozen sessions from modal save dialogs, stacked nodes at (0,0), and broken absolute paths — that cost hours of debugging. This Skill encodes the non-negotiable rules and recovery recipes so an AI agent avoids these traps before they happen. ## Core Features & Use Cases - Failure-mode prevention: Enforces rules for exec-scope scripting, GLSL compile verification via get_glsl_status, dialog-proof checkpointing with save_td_project, mandatory node placement, and relative-path references. - Tool selection guidance: Maps each job (create node, set params, capture output, KB lookup) to the correct td-builder or td-builder-live tool, with a KB-first mandate before configuring any operator. - Error diagnosis cheat sheet: Maps symptoms (stale point data, silent Execute DAT callbacks, uniforms reading as 0) to their real root causes and fixes. - Use Case: An agent asked to build a feedback POP simulation in a live TouchDesigner session loads this Skill first, queries the KB for exemplars, pulses init/start/play params correctly, and checkpoints the project before risky operations. ## Quick Start Load this Skill before making any td-builder or td-builder-live MCP tool call when building or debugging a TouchDesigner network.

Frequently Asked Questions about td-builder-howto

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug GLSL shader compile errors in TouchDesigner?

GLSL compile errors do not appear in node.errors(). Call get_glsl_status(node_path), which reads the shader's Info DAT and folds in op.warnings(), returning compile_failed, compiler_errors, and warnings in one call after any shader edit.

How do I save a TouchDesigner project from an MCP script without freezing?

Never call project.save() from execute_python_script — a modal dialog blocks TD's single main thread and hangs the live connection. Ask the user to press Ctrl+S, then call the dialog-proof save_td_project tool and verify source_mtime advanced.

Why does my TouchDesigner Execute DAT callback never fire?

An empty op or pars scope on the Execute DAT matches nothing and fails silently with no error. Use '..' to watch the parent, ensure pars is non-empty, and note the pulse-enable toggle is named onpulse, not pulse.

Why does my GLSL uniform read as 0 even though the shader compiled?

A clean compile plus non-empty op.warnings() is a silent failure, usually a uniform assigned on the wrong UI page. Also, GLSL TOPs do not auto-declare Vectors-page uniforms — declare them explicitly in the shader source.

Can I build TouchDesigner networks offline without TD running?

Yes. Use the offline td-builder tools: td_validate.py to validate a .toe.dir, td_convert.py for format conversion, and td_build.py to build a .tox offline, then import it into the live session.

Why does reading point data through a Delete POP return stale values?

Reads through a Delete POP are stale by one cook. Either call op.cook(force=True) twice before reading, or read the upstream POP directly before the Delete.