The .toe format

Native .toe decoding is provided for research purposes only. It exists to study interoperability with project files you own, is not affiliated with or endorsed by Derivative Inc., and may change with any TouchDesigner release. Derivative has announced an official JSON project format; WebToe's ProjectLoader interface is ready to load it beside this decoder. Your own TouchDesigner's toeexpand, through the bridge, remains the reference and the automatic fallback.

Source: packages/io/src/toeBinary.ts · tests: tests/toe-native.test.ts

#What it does

A dropped or linked .toe / .tox is decoded in the browser into exactly the file set toeexpand writes: node files (.n), parameters (.parm), DAT bodies and layout. The same importer the bridge path uses then builds the network.

#Measured

Validated against toeexpand (TouchDesigner 2025.33070) on 125 production project files, 3 KB to 151 MB, saved by builds from 2021.16410 to 2025:

#Format

All integers are big-endian unless noted.

file = SEGMENT+

kind "10"   "10" | u32 payloadLen | u32 rawLen | payload
kind "12"   "12" | u32 chunks | u32 8 | u32 payloadLen₀ | u32 rawLen₀ | payload₀
            then for each further chunk: u32 payloadLenᵢ | u32 rawLenᵢ | payloadᵢ
            (large archives, ≤ 128 MiB of output per chunk; chunk headers are not encrypted)

payload = TEA-ECB( zlib stream ), padded to a multiple of 8 bytes
          payloadLen counts the padding; rawLen is the inflated size

TEA is the standard Tiny Encryption Algorithm: 32 rounds, delta 0x9E3779B9, little-endian 32-bit word pairs, ECB over 8-byte blocks, 128-bit key (little-endian words) 9241fa3a 59f32012 c612aa09 a98123d4. The zlib stream is stock RFC 1950.

Inflated payloads concatenate, in order across chunks and segments, into one archive of records. A record may straddle a chunk boundary:

0x34  file   [tag] [u8 nameLen] [u32 contentLen] [name ] [content]
0x36  push   [tag] [0x34] [u8 nameLen] [name ]      enter a subdirectory
0x35  pop    [tag]                                    leave it

A file record named TRAILER!!! closes the archive.

#Rules that matter

1. The directory stack persists across segments. Resetting it per segment silently flattens large projects.
2. Every chunk is checked. Its inflated size must equal rawLen, and the next segment must start where the lengths say. A segment whose fields do not check out (an unseen variant) is recovered without them: zlib streams are walked on the TEA block grid, each one's end found by its Adler-32 trailer and confirmed by what follows. No file in the corpus needed it.
3. Filenames. TouchDesigner allows sibling operators whose names differ only in case (geo_I and geo_i). toeexpand writes to the file system, so on macOS and Windows those collide: it appends .2, .3 and merges directories. The native decoder keeps the original names. Nine corpus files match toeexpand only once its case-insensitive collisions are emulated in the comparison.
4. Browser inflate. The 8-byte padding after each zlib stream makes DecompressionStream error, and in Chrome that error discards output not yet read. WebToe feeds the last 8 bytes one write at a time, so the error arrives only after every chunk of real output has been read.

#In the editor

The import report states which path was used and how long it took.

#Provenance

The format description was established by studying project files and TouchDesigner's own command-line tools, and is validated byte for byte against toeexpand output. WebToe contains no Derivative code, binaries or assets.