EMBODY / LATERAL VELOCITY

# your network,
on disk.

Your entire project lives inside a single binary file. You can't separate one experiment from another, can't hand a piece of it to someone, can't let your AI read just the part it needs. Embody breaks the project into individual files — one per operator, mirroring your network hierarchy — that rebuild themselves every time you open the project.

Download the .tox → Read the docs

THE SHIFT

## one file vs. many.

Everything you build lives inside a single project file. Every experiment, every version, every branched idea — together, inseparable. Embody breaks the project into individual files you can own, diff, and restore independently.

### binary `.toe`

- Opaque — requires TouchDesigner to inspect
- Binary diff — "file changed"
- Invisible to AI agents
- Revert = restore the entire file
- Merge conflicts are unresolvable
- One save format for the whole project

### externalized files

- Readable in any text editor
- Line-by-line diff — see exactly what changed
- AI agents can read and understand your network
- Revert = `git checkout` a specific change
- Merge conflicts are readable and fixable
- Files are the source of truth — `.toe` is working state

EXTERNALIZATION

## everything gets a file.

Tag any operator. Embody writes it to a file on disk and tracks it. On the next project open, every externalized operator rebuilds itself from that file — automatically, without any intervention.

■

### TOX strategy

COMPs saved as portable `.tox` files. Fast to restore, works with any COMP complexity — UI components, third-party tools, anything.

■

### TDN strategy

COMPs mirrored to TDN JSON on every save — human-readable, diffable, reviewable in pull requests, and readable by your agent in one call. Your `.toe` stays the source of truth; the `.tdn` rides alongside.

■

### DAT formats

Scripts and data externalize as `.py`, `.json`, `.xml`, `.csv` — whatever matches the DAT's content type. Auto-detected.

■

### mirrored hierarchy

The folder structure on disk mirrors your network hierarchy. Find any externalized file without guessing where it lives.

■

### auto-restore on open

Every project open runs three restore phases — TOX COMPs, TDN COMPs, DAT file parameters — fully automatic. Nothing to trigger manually.

■

### build metadata

Every externalized COMP gets `Buildnumber`, `Touchbuild`, and `Builddate` injected automatically. A permanent record of when and where it was built.

SYNC MODEL

## only what changed.

Embody watches every externalized operator for parameter changes. When something changes, the operator is marked dirty. When you press `Ctrl+Shift+U`, only dirty operators write to disk — no unnecessary file writes, no spurious git changes.

tag an operator `lCtrl lCtrl`
write dirty ops to disk `Ctrl+Shift+U`
open manager `Ctrl+Shift+E`
restore from disk automatic on project open
tracking table `externalizations.tsv`
tracking fields path, type, file, dirty, build

- Parameter change detection — every parameter value is tracked. Touch any parameter on an externalized op and it's immediately marked dirty in the table.
- Selective writes — only dirty operators write on Update. A project with 40 externalized ops and one change writes one file, not 40.
- Content comparison — if a write produces identical content to the existing file, the write is skipped entirely. Git timestamps stay clean.
- Single source of truth — `externalizations.tsv` tracks what's externalized, where the file lives, and whether it's current. Nothing happens outside of it.

RELIABILITY

## nothing lost.

Embody manages files on your behalf. Every decision about what to write, what to keep, and what to skip is explicit and reversible.

### won't delete your work

Embody only manages files it created. Remove a tag and the file stays on disk. Files Embody didn't create are never modified.

### export on save

The default. Your `.toe` stays authoritative. On every save, changed TDN COMPs write a `.tdn` alongside it — for git diffs, code review, and AI reads. The live network is never stripped.

### roundtrip (experimental)

Opt-in. Children are stripped from the `.toe` on save and reconstructed from `.tdn` on open — text becomes the source of truth. For teams who want the JSON to win.

### no silent overwrites

If two operators point to the same external file, Embody prompts before writing. You decide — not the tool.

### skip-if-identical

If a write produces the same content as the existing file, it's skipped entirely. No spurious git changes, no noise commits.

### works across machines

Paths normalized to forward slashes, timestamps stored in UTC. A project externalized on Windows opens cleanly on macOS.

VERSION CONTROL

## embody + git.

A git repository is optional — Embody works in any project folder. But once your operators live in files, version control stops being something you wish you had and starts being something that just works.

- Readable diffs — `git diff` shows exactly which parameters changed on which operators between two commits. Not "file changed." The actual change.
- Branching by idea — each experimental direction is a branch. Merging brings working parts back together without manual copy-paste in the TD network editor.
- Pull request reviews — reviewers can comment on specific parameter changes, script edits, and network structure without opening TouchDesigner.
- Bisect — `git bisect` can find the commit that introduced a visual or performance regression. Every change is discrete and readable.
- AI context — your AI assistant can run `git diff` against your externalized files and understand exactly what changed between sessions, without you summarizing it.

The source of truth. The `.toe` is a working file. The externalized files on disk are what you actually own.

THE WORKFLOW

## part of the loop.

Embody is the lateral layer — it keeps your work versioned and restorable. It works with the other two layers to close the full loop.

### Envoy

forward velocity.

Your AI agent builds inside the live session. When it's done, it externalizes what it built using Embody's MCP tools — the work is immediately tracked and version-controlled.

### TDN

the substrate.

Choose TDN as your externalization strategy for COMPs you want to diff. Every save writes the network as human-readable JSON — operators, parameters, connections, all in text.

### Git

the record.

Commit the externalized files. Every Update produces a clean, reviewable diff. Branch off ideas. Revert bad experiments. Your entire creative history, in version control.

Lateral velocity. Every experiment is a branch. Every save is a diff. Every restore is automatic. You move sideways as fast as you move forward.

USAGE

## four steps to flow.

1. 01

   ### download

   Grab the Embody `.tox` from GitHub Releases and drop it into your TouchDesigner project. That's the install.

2. 02

   ### tag an operator

   Double-tap `lCtrl` on any COMP or DAT. The operator is registered in `externalizations.tsv` with an auto-detected externalization strategy.

3. 03

   ### update

   Press `Ctrl+Shift+U`. Embody writes all dirty operators to their external files. The files on disk are now the source of truth.

4. 04

   ### reopen

   Close and reopen the project. Every externalized operator rebuilds automatically from disk — no manual steps, no intervention required.

Requires TouchDesigner 2025.32280 or later. Works on macOS and Windows.

DOCUMENTATION

## go deeper.

### getting started

Download, install, and externalize your first operator in under five minutes.

→

### externalization

Tags, strategies, the sync cycle, and how Embody manages the files it creates.

→

### manager UI

The Embody panel — operator list, dirty state, build info, and bulk operations.

→

### supported formats

Every file format Embody writes — which operators use them and why.

→