Working in TDXCollab

TDXCollab does not scan your whole project every frame. It watches the networks your network editors show, so its cost grows with what you are looking at, not with the size of the project. The price is a simple rule: a change in a network nobody is looking at is not seen, and so not sent.

What is watched

• The networks your network editors show inside the zone, focused or not: the operators in them, their parameters, flags, wires and DAT text. With split panes, the first four networks shown at once completely (Split panes).
• The Collab Zone COMP's own parameters, wherever your editor is.
• Animation COMPs, edited in the Animation Editor, wherever your panes are.
• The project's FPS and timeline.
• Whatever you mark Always Sync, wherever your editors are.

A network is watched one level deep: the operators you see. A parameter on a COMP inside one of those operators belongs to the network inside it, which you are not showing.

What slips past

These change the zone without a network editor showing the change:

• A component's own UI. A palette tool, a widget, a container with controls: its knobs are parameters on a COMP inside it. You turn them from its viewer, its panel or its parameter dialog while your editor shows the network around it, so nothing is watching.
• A floating parameter window of an operator in a network you have since left.
• Scripts, Execute DATs, expressions and tools that change an operator in a network nobody shows.
• Creates and deletes inside an always-synced COMP while no editor shows that COMP.

The copies then differ without anyone noticing, until both of you open that network and the drift check reports it.

Always Sync

For anything you change from somewhere other than its own network, drop it on the TDXCollab chip and choose Always Sync: an operator, a COMP and what is directly inside it, or one parameter. It is then sent wherever your editors are, and the drift check compares it too (Always Sync).

The everyday case: before you play a component from its panel or viewer, mark it Always Sync.

The check follows the same rule

The drift check also compares only what both of you view. No warning means the networks you both looked at match, not the whole zone. A warning right after you both enter a network can be about a difference made long before (What the check sees). Sync Zone is the one thing that covers the whole zone, seen or not.

The habit

Work with the network open. When you change something you cannot see in a network editor, ask whether it is marked Always Sync.

Nothing a network produces is sent: no pixels, no samples, no geometry, no audio. Each side cooks its own copy, so the same network gives the same result as far as the inputs are the same. They often are not.

What differs between machines

• Inputs from outside: cameras, microphones, MIDI, streams, files: each machine's own.
• Time: the timeline's play, pause and frame sync, but each machine runs on its own clock and drops its own frames. Anything driven by the clock or by real time drifts a little apart.
• The machine: GPU, fonts, licence limits, plugins.
• Frozen data: a locked TOP, CHOP or SOP keeps the data it froze on your side. The Lock flag syncs, its contents do not. A locked Text or Table DAT's text does.

Outputs stay outputs

A value that is an output (a parameter bound to a CHOP channel or to a component's attribute) is left to each side to compute: TDXCollab syncs the source and lets the output follow.

Code runs on every computer

Python in the zone (Execute DATs, callbacks, expressions, extensions) runs in every partner's TouchDesigner, because every partner has the zone. Think about where its effects land:

• What reacts to the network runs everywhere. A pulse is sent, so what it triggers happens on every side. An expression or a callback that follows a parameter follows it on every copy.
• What reacts to you runs where you are. A key, a click on a panel, your MIDI controller: their callbacks fire on your side only, and only what they change in the watched network travels.
• Effects outside TouchDesigner multiply. A script in the zone that sends OSC, writes a file, calls a web address or drives DMX does it once per computer in the session.
• A DAT a running network writes into gets its own content on each side, and shows as a difference. Keep it outside the zone, or mark it Not checked (Differences nobody made).

This is also why Full Edit is a matter of trust: Python a partner puts into the zone runs in your TouchDesigner (Roles).

Two copies that should be equal and are not have drifted. It happens in every long session, and it is not a failure: TDXCollab checks for it, says so, and puts the copies back together with one choice. What helps is knowing why it happens.

Why copies drift

• Edits while you were apart: made while disconnected, never sent later.
• Changes nobody watched: a component's own UI, a script or a tool working in a network nobody shows (Only what is shown is watched).
• The same operator at the same moment (Two people, one thing).
• Differences nobody made: a DAT a running network writes into, a DAT synced to a file, a path that names a different file on each computer (Two TouchDesigners, two copies).
• A role's edits: what a partner changes outside their role stays on their side, and their copy differs until they take the host's.

How you find out

Each side fingerprints the operators it views, a few each frame, and the host compares every partner's copy with its own. A change of the last 3 seconds is not counted, as it can still be on its way. A difference that lasts is reported on both sides, in the status bar and the log, naming the operators and what differs in each.

• The host gets a pop-up once per new difference (with Ask on Drift on).
• A partner's chip turns orange and their Status says their copy differs from the host's.

Only what both of you view is compared: no pop-up means what you both looked at matches.

Bringing them back

The host decides. Its choice, first, is just the operators that differ, with their wires and docked operators; nothing else in the network changes. Then whole copies: the host's own, or a partner's, which replaces everyone else's zone. A partner can always take the host's version into their own zone (When copies differ).

• Resolve Drift opens the choice again at any time.
• Sync Zone sends one whole zone to everyone, seen or not (Sync Zone).
• Resync on Connect and joining as a copy of the host's zone start a reconnect or a join from the same copy.

Right after joining, taking the host's whole copy is quickest.

Nothing is lost

A zone that is replaced is kept beside the new one, switched off, named after what replaced it. Snapshot Zone keeps one by hand before a risky change. Restore brings it back, on your side only (Kept zones). Save your project before a session anyway: kept zones live in the project you have open.

Differences you want

What may differ on purpose, a scratch COMP or a parameter a local script keeps changing, mark Not checked: it still syncs, but never shows as drift and is never repaired (Not checked). What should never be shared at all is Keep Local.