operator-gotchas

<!-- Generated by Embody/Envoy - Do not remove this comment - sha:f6e2651145a68461 --> # 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`. 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`).