operator-gotchas

Operator Gotchas

Per-operator traps, verified live on TD 2025.33230 (2026-09-25) unless marked as a field note. Before touching an unfamiliar operator, describe_op_type(op_type, pattern=...) returns its real parameter names, creation defaults and menu values, and set_parameter rejects a bad menu value and names the valid ones. A guessed name costs a round trip; a wrong guess that happens to exist costs a show.

Universal

• Reference nulls, not live ops. An expression or OP parameter that names a Null survives inserting or deleting the ops before it; one that names the working op breaks the moment a filter goes in front. End every chain in a Null and point everything at that.
• OP-reference parameters hold a path string and do not follow a rename of their target (a Select TOP pointed at a renamed Constant TOP read None). After any rename, sweep par.val, par.expr and par.bindExpr for the old name (td-python.md).
• Menu values are the lowercase token, never the label: ortho not orthographic, deg not degrees, aa8 not aa8high, chanpercol not Channel per Column.
• Par.default can disagree with what a fresh operator actually holds (a Text DAT's language declares input but a new one reads text); describe_op_type reports the creation value and flags the divergence.
• Time-dependent operators cook only when something demands their output: a viewer, a Render or Out TOP, a Null with its viewer on, a CHOP Execute DAT. A silent chain is usually undemanded, not broken (td-python.md, Cook Model).

TOPs

• compositeTOP: operand defaults to multiply. With over, input 0 is the FOREGROUND (on top) and later inputs sit underneath, the reverse of a layer stack.
• constantTOP is white with alpha 1 by default; set colorr/g/b=0 and alpha=0 for an empty seed. It exposes type=texture3d but has no customdepth, so it cannot seed a real volume; use a small glslTOP (/glsl-shaders).
• feedbackTOP: top names the Null that closes the loop, resetpulse resets. Keep format identical through the loop (rgba16float or rgba32float for anything outside 0-1) and pin outputresolution=custom inside it. Field note (TDMCPSkills): on reset it takes the input's resolution, afterwards the target's, so a mismatch changes resolution after the first frame.
• selectTOP: top is a path string (see Universal: a rename breaks it).
• depthTOP: pixelformat=rgba16float + depthspace=reranged gives usable 0-1 depth.
• moviefileinTOP: paths resolve relative to the .toe; a file change or reloadpulse lands only across a real frame advance (/td-api-reference, Cook Model Gotchas). playmode is locked, specify, sequential or timecodeop; cuepulse + cuepoint jump.
• renderTOP: camera defaults to cam1, geometry and lights to *; antialias is aa1..aa32; bgcolora 0 keeps the background transparent for compositing; set a float format before bloom or tone-mapping or every value clips at 1.0 (/visual-aesthetics).
• rgba8fixed, the default output format everywhere, clamps to 0-1. Data textures, feedback, random values and HDR need rgba16float or rgba32float.
• choptoTOP: dataformat packs channels (r, one channel per row by default; rgba packs four) and needs a float format for data bakes.
• glslTOP has 3 input connectors; use glslmultiTOP for more (/glsl-shaders).