TouchDesigner Overview

TouchDesigner is the engine that produces every pixel Lightpath puts on screen. Lightpath wraps a TouchDesigner project, loads outputs and plugins into it dynamically, routes content through them, and exposes their parameters to the web UI.

You author the TouchDesigner side as .tox files following a small contract. There are two kinds:

• Outputs are the destinations — the components that take a final composed texture and push it somewhere physical: a pixel-mapped LED sculpture, a projection mapped surface, a video wall over NDI, etc. One output per physical destination in the install.
• Plugins are the supporting cast. They come in three flavors:
  • Sources generate textures — patterns, audio reactivity, media playback, shader visuals.
  • Effects transform textures — blurs, color shifts, masks, geometric distortions.
  • System plugins don't render anything; they send control signals or expose shared data other plugins react to (sensors, cameras, APIs). One instance per install.

A Lightpath look picks a source, stacks effects on it, and routes the result to one or more outputs.

This page covers the shared concepts — custom parameters, file paths — that apply to both outputs and plugins. The dedicated guides drill into each:

• Making an Output
• Making Plugins

Custom parameters

Lightpath surfaces TouchDesigner custom parameters to the user interface, but only ones on specific parameter pages. There are three pages it cares about: Look, Config, and Status.

Look parameters

Any parameter on a page named Look is exposed per-look. Operators tune these in the look editor; each look stores its own values. Switching looks switches the values.

Use Look params for things an operator should be able to vary across looks — pattern speed, blur radius, mix amount, color shift, fit mode.

Note: Look parameters are not available for System plugins, since they are install-level instances. Their state doesn't change per look, so a Look page wouldn't have anywhere to land.

Config parameters

Any parameter on a page named Config is exposed at the project level — one value for the whole project, same across every look, every schedule event, every operator action.

Use Config params for things tied to the install rather than the look — network targets, monitor indexes, sample rates, file paths, default behaviors.

Config parameters show up in several places:

• Outputs page — each output's edit panel surfaces that output's config params alongside its other settings. Edit values and save new defaults that restore on project load.
• Plugins page — same pattern for sources, effects, and system plugins: each plugin's config params live next to the plugin itself.
• Actions — an action step can change a config param value.
• Logic — rules can read config param values as conditions.
• Kiosk — config params can appear as user-facing controls on the Kiosk page.

Status parameters

Any parameter on a page named Status is exposed to Lightpath as read-only state. The values stream live from TouchDesigner and appear in the TouchDesigner device on the Devices page — grouped by the component that exposes them — so operators can see at a glance what each component is doing.

Use Status params for things Lightpath should observe, not control — connection state of a remote service, last-received message timestamps, error counts, signal-presence booleans, current mode strings. They're read-only in the UI; nothing the user does in Lightpath writes back to them.

Status params also feed the Alerts system: every Status parameter becomes a selectable target in the alert rule editor, so you can notify operators when (for example) a connection goes offline or an error count climbs.

Status pages work on outputs and system plugins — the singleton components in a project. Source and effect plugins don't support Status pages, since each look can wire them in different combinations and there's no single "the source's status" to point at.

Internal parameters

Any parameter on a page named Internal stays inside TouchDesigner — Lightpath ignores it. Use Internal for plumbing the operator should never see: resolution, internal timing knobs, debug toggles, things your component needs to function but no one should tune from the Lightpath UI.

Sources must put their resolution on Internal. The Lightpath convention is Resolution1 (width) and Resolution2 (height) Int parameters on a page called Internal. Drive your source's internal cook rate off these so the rest of Lightpath can size your source correctly. Effects and outputs don't have this requirement, but the Internal page is where you'd put any internal sizing they need.

Thumbnail mode

Sources, effects, and outputs all appear in pickers with a still thumbnail. Lightpath generates these automatically — you don't have to do anything for thumbnails to work. But many effects (blurs, color shifts, displacement, etc.) are pass-through at default values, so the captured thumbnail looks identical to the input and tells the operator nothing.

Fix that by exposing a Thumbnail Toggle parameter on the Internal page. Lightpath sets it to On when capturing the thumbnail and back to Off when done. Wire your interesting parameters off this toggle with TouchDesigner parameter expressions so the capture showcases what your component does:

# On a Blur effect's Filter Size parameter (expression mode):
20 if parent().par.Thumbnail else 1

# On a Color effect's Hue Shift parameter:
0.3 if parent().par.Thumbnail else 0.0

The toggle is the single switch you key your showcase values off of. Sources usually don't need it (most generate visible content at defaults). Effects almost always do. Outputs use it when the thumbnail should show a different rendering mode than the live LED output.

If you don't expose a Thumbnail parameter, Lightpath skips the toggle and captures at your defaults — fine for sources that already look good, less useful for effects that don't.

Which components support which pages

Refreshing the parameter schema

Lightpath detects schema changes — parameters added or removed on a .tox while it's running — and re-scans automatically. Value changes are streamed live; you don't need to do anything for either.

In the rare case Lightpath and TouchDesigner look out of sync (a rename that auto-detection missed, a refresh that didn't land), the TouchDesigner settings page has a Sync data button in the Process Status section that forces a full re-scan.

Accessing project files

When your output or plugin needs to reference external assets — 3D models, images, spreadsheets, etc. — store them inside your project folder and reference them via the project path shortcut.

If you add a 3D model at my_cool_project/outputs/My_Output/model.obj, you can load it in TouchDesigner with the path:

project/outputs/My_Output/model.obj

This path resolves correctly across machines and project locations because TouchDesigner reads it relative to the loaded project root. Don't use absolute filesystem paths — they break the moment the project moves.

Saving toxes

Lightpath includes two keyboard shortcuts for saving .tox files from inside the TouchDesigner editor. Both flash the network background green when the save completes — quick visual confirmation that the file was written.

• alt+e — Save the currently selected COMP to its externaltox path. If the COMP has never been saved (no externaltox set), a folder picker opens once; the chosen <folder>/<comp name>.tox becomes the COMP's externaltox for every subsequent save.
• alt+shift+e — Save the COMP whose network you're currently inside — i.e. the parent of the network editor's view. Same save semantics as alt+e. Useful when you're working inside a component and want to save the component itself without dropping back out to its parent.

Where to go next

• Making an Output — wire a new fixture, video wall, projector, or screen into Lightpath.
• Making Plugins — author a source, effect, or system plugin that any output can use.