dylanroscover / operator-gotchas

<!-- Generated by Embody/Envoy - Do not remove this comment - sha:25bf8f0d0830692c -->

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

CHOPs

• selectCHOP: the remote reference is chops (plural); channames, renamefrom and renameto take TD patterns (*, ?, [xyz], [0-2], a|b, ~exclude). Use it to fan one source out to many consumers without long wires.
• parameterCHOP (ops defaults to ..): custom is ON and builtin is OFF by default, so reading tx needs builtin on, and a parameters filter alone does nothing while the category toggle is off.
• lagCHOP: lag1 (rise) and lag2 (fall) in lagunit seconds; there is no lag. filterCHOP: type (gauss default), width, widthunit (seconds by default).
• mathCHOP: chopop/chanop combine across inputs or channels (add, sub, mul, div, avg, min, max, len); preop/postop act per value (negate, pos, root, square, inverse); preoff, gain and postoff apply as (value + preoff) * gain + postoff; integer rounds.
• logicCHOP convert: only bound reads boundmin/boundmax; gt, ge, lt, le, eq, ne compare between inputs, not against a threshold. "Value above a threshold" is Math CHOP preoff=-threshold into Logic convert=pos.
• functionCHOP: func (sqrt, abs, sign, trig, ...), angunit is deg, rad or cycle. lookupCHOP: input 0 is the index, input 1 the table, index1/index2 the index range. shuffleCHOP method=spliteveryn with nval de-interleaves samples into channels. resampleCHOP rate fixes a rate mismatch before a Merge or Math.
• nullCHOP cooktype=selective on a chain end that only needs to update on change.
• timerCHOP ships with cycle OFF and cyclelimit ON at maxcycles 4: a periodic timer needs cycle on and the limit off or it stops after four. length 10 s; ondone is donothing, reinit, restart or restartnoinit; segments come from segdat with segmethod serial or parallel and deferpars on while they play; lengthtype=infinite disables the fraction; callbacks is its docked DAT.
• constantCHOP: const0name (default chan1) / const0value is a sequence, and set_parameter on const5name grows it.
• switchCHOP index is an Int; switchTOP index is a Float with a blend toggle.
• speedCHOP integrates its input (a rate becomes a position). Field note (TDMCPSkills): triggerCHOP will not re-fire while the input stays high; detect edges in a CHOP Execute DAT onOffToOn instead.
• The audio input is audiodeviceinCHOP (there is no audiodevinCHOP); long files play from audiofileinCHOP; analysis is audiospectrumCHOP (fftsize, frequencylog), analyzeCHOP (function=rmspower), beatCHOP.
• Never drive a long-running show's motion from absTime.seconds: the accumulated value loses float precision on the GPU (noise goes blocky, motion steps). Use cyclic sources (LFO sin/cos into a 4D noise offset, beatCHOP, timerCHOP) or absTime.frame modulo a period.

DATs and callbacks

• Every execute DAT has ONE source parameter and is silently inert without it: chopexecuteDAT.chop, datexecuteDAT.dat, parameterexecuteDAT.op (with pars a pattern; empty watches nothing), panelexecuteDAT.panels (plural). active and the callback toggle you rely on (offtoon, valuechange, tablechange, ...) must both be on.
• parameterexecuteDAT ships with builtin AND custom ON; turn builtin off for a custom-parameter dispatcher (/parameter-design).
• executeDAT ships with every hook OFF (framestart, frameend, start, create, exit); a frame driver that was never enabled demands nothing.
• A CHOP Execute DAT makes its watched CHOP cook every frame whether or not anything else pulls it.
• A Text DAT's language (python, glsl, json, yaml, xml, text) is what gives a code DAT colouring and error checking; a hand-created one reads text, while create_op and create_extension make it python; for any other content pass create_op(language=...), which also picks the matching file type when the DAT is auto-externalized. Embody's externalize_op sets file and syncfile; never set them yourself.
• webclientDAT: reqmethod, url, request pulse, timeout in ms (60000 default), authtype, output (text or table), and a docked _callbacks DAT whose onResponse runs on the main thread (/td-api-reference, Background Work). jsonDAT: filter is a JSONPath ($), output is results, result or source.
• Table cells are strings: op('t')[1, 2] + 1 auto-casts, .val + 1 raises (/td-api-reference).

MATs, lights, cameras

• pbrMAT: metallic AND roughness default to 1.0, so untouched it renders as rough chrome; set metallic=0 for dielectrics and vary roughness. It needs an environmentlightCOMP (envlightmap) plus a Light COMP or it renders near-black. POP geometry under PBR needs normalPOP tangents (/pop-networks).
• pointspriteMAT: pointsize in pixels, colormap, blending on for transparency (blendop), sizingmodel constatten (with attennear, attenfar, attensizenear, attensizefar) or perspective. Points render as single pixels under any other MAT.
• lineMAT: linecoloratt defaults to Color, linewidthatt to LineWidth; widthnear/widthfar attenuate with distance; widthaffectedbyfov OFF keeps pixel widths when the camera is normalized.
• glslMAT: blending off by default; srcblend/destblend (one, zero, sa, omsa, ...) plus the alpha pair srcblenda/destblenda; cullface is userender, neither, backfaces or frontfaces; wireframe is off, tesselated or topology.
• lightCOMP: lighttype point, cone or distant; dimmer; coneangle/conedelta; shadowtype off, hard2d, soft2d; attenuated. cameraCOMP: projection perspective or ortho; fov 45; near 0.1 and far 1000 (a computed camera distance can clip -- raise far); lookat; fog off, linear, exp, exp2 with fogcolorr/g/b and fogdensity.
• A fresh geometryCOMP holds torus1 with its render flag ON: delete it or it renders behind your scene (/create-operator).

Instancing (Geometry COMP, Instance pages)

• instancing=1, instanceop = the data OP (CHOP, DAT, TOP or POP); instancecountmode oplength (default) or manual; a DAT with a header row needs instancefirstrow=names.
• Channel selectors are strings that must match a channel name, DAT column or POP attribute exactly: instancetx/ty/tz, instancerx/ry/rz, instancesx/sy/sz, instancer/g/b/a (instancecolormode replace, multiply, add, subtract), instanceactive. Per-group OP overrides: instancetop (translate), instancerop (rotate), instancesop (scale), instancecolorop, instancetexcoordop.
• POP data goes in directly: instanceop = a nullPOP, selectors P(0), P(1), P(2), Color(0), ... No poptoCHOP round trip, no GPU-to-CPU copy.
• Rotate-to-vector: instancerottoop + instancerottox/y/z, instancerottoforward (negz default; posy for tubes), instancerottoorder (rottoxform, rotaterotto, rottorotate), up vector from instancerotupop + instancerotupx/y/z.
• Textures per instance: instancetexs (a TOP list), instancetexindexop + instancetexindex, instancetexmode replace or transform.
• OP-reference parameters inside a Geometry COMP resolve from INSIDE it: reach the COMP's siblings through a parent-shortcut expression, never ../name (parameters.md).

In and Out

• A COMP has no input connector until an in* operator exists inside it; with several, set connectorder explicitly (default order is creation order). Wire a default source into an inTOP/inCHOP's own input: it is used when nothing is connected outside.
• outTOP label defaults to $ON (its own name). A specimen's output is an Out TOP named out1.

Topics cross-checked against Derivative's TDMCPSkills family skills with permission; every unmarked claim was probed live on 2025.33230, and three of theirs were corrected here (chops, panels, audiodeviceinCHOP).