Close
Asset

Embody: Automate Externalization

As TouchDesigner projects grow in complexity, managing and collaborating on them can become increasingly challenging. One of the primary hurdles is the monolithic .toe file format, which encapsulates the entire project in a single binary file. While convenient for small projects, this approach poses significant limitations for version control and collaborative workflows. Enter Embody—a powerful tool designed to automate the externalization of components and scripts in TouchDesigner, streamlining your workflow and enhancing collaboration.

The Challenge with TouchDesigner Projects

TouchDesigner stores projects in a .toe (TOuch Environment) file, a binary format that bundles all project components. This setup, while straightforward, makes it difficult to:

  • Collaborate Efficiently: Merging changes from multiple collaborators is cumbersome with binary files.
  • Version Control: Tracking changes and maintaining version history is challenging without text-based files.
  • Manage Large Projects: As projects scale, navigating and editing within a single file becomes inefficient.

Developers often resort to manually externalizing components by saving them as .tox files or exporting scripts and data as .py, .glsl, or .json files. However, this manual process is repetitive, error-prone, and hard to manage, especially in large networks.

 

What is Embody?

Embody is a TouchDesigner extension that automates the externalization of COMP and DAT operators. By tagging the operators you wish to externalize, Embody handles the creation, maintenance, and updating of external files, supporting a variety of formats such as .tox, .py, .json, .xml, .html, .glsl, and more.

 

Key Features

  • Automated Externalization: No more manual saving of components and scripts. Embody does it all for you upon saving your project or updating Embody.
  • Tag-Based System: Easily tag operators for externalization using simple keyboard shortcuts.
  • Folder Structure Mirroring: Externalized files are saved in a folder structure that mirrors your project network, keeping your files organized.
  • Support for Various File Formats: Beyond .tox files, Embody supports externalizing scripts and data in multiple formats, including Python, GLSL, JSON, and more.
  • Synchronization: Ensures that your external files are always up-to-date with your project.
  • Manager UI: Provides an interface to view and manage all your externalized operators, check their status, and update them as needed.
  • Reset Functionality: Allows you to disable Embody and remove externalizations when needed.
  • Multi-Platform Support: Developed and tested on both Windows and macOS.

Getting Started with Embody

1. Download and Add Embody

  • Visit the Embody GitHub Repository.
  • Navigate to the /release folder and download the latest Embody.tox file.
  • Open your TouchDesigner project and drag-and-drop the Embody.tox file into your network.

2. Initialize Embody

  • Upon adding Embody, you'll be prompted to re-initialize or keep the last saved state.
  • For new projects, select re-initialize.
  • Embody will place all externalizations within your project folder. You can customize this storage location in Embody's Folder parameter.

3. Tag Operators for Externalization

  • Select the operator you wish to externalize.
  • Press the left control key twice (LCTRL + LCTRL) to add the externalization tag.
  • Embody supports tagging for:
    • COMPs: All except engine, time, and annotate COMPs.
    • DATs: Text DAT, Table DAT, Execute DAT, and various other execute DATs.
  • Supported file formats include .tox, .py, .json, .xml, .html, .glsl, and more.

4. Enable and Update Externalizations

  • Press Ctrl/Cmd + Shift + U or click the Enable/Update button in Embody.
  • Embody externalizes tagged operators, creating a folder structure that mirrors your project network.
  • For example, externalizing base2 within base1 results in the path: {project folder}/base1/base2.tox.

 

Workflow with Embody

  • Automatic Updates: When you save your project (Ctrl/Cmd + S), Embody automatically updates any modified (dirty) components.
  • Selective Updates: Press Ctrl/Cmd + Shift + U to update only dirty components without saving the entire project.
  • Manager UI: Press Ctrl/Cmd + Shift + E to open the Embody Manager UI, where you can view all externalized operators, their status, and update them as needed.
  • Resetting Embody: If you need to reset or disable Embody, you can pulse the Disable button. This action will remove externalizations and clear external references.

 

Benefits of Using Embody

  • Enhanced Collaboration: With components and scripts externalized into text-based files, integrating with version control systems like Git becomes seamless.
  • Improved Project Organization: External files are neatly organized in a folder structure that mirrors your project, making navigation and management easier.
  • Time Savings: Automating the externalization process reduces repetitive tasks, allowing you to focus on developing your project.
  • Flexibility: Easily share and reuse components across different projects.

 

Keyboard Shortcuts and Tips

  • Ctrl/Cmd + Shift + E: Open the Embody Manager UI.
  • LCTRL + LCTRL (both Windows and macOS): Tag the selected operator for externalization.
  • Ctrl/Cmd + Shift + U: Enable or update externalizations.
  • Customize Externalization Folder: Change the default externalizations folder in Embody's parameters to suit your project's needs.
  • Monitor Externalizations: Use the Manager UI to keep track of which components are externalized and their current status.

 

Advanced Features

  • Full Project Externalization: Embody can externalize your entire project automatically, excluding system components, clones, and replicants.
  • Handling Renamed Components: Embody detects when components are deleted, renamed or moved and updates the external files accordingly.
  • Conflict Resolution: The tool checks for duplicate external file paths and helps you resolve conflicts.
  • Custom Tags and Formats: Define custom tags for different operator types and specify the file formats for externalization.

 

Contributors and Acknowledgments

Embody is a collaborative effort that has evolved thanks to the contributions of several developers:

  • Original Developer: Tim Franklin
  • Refactored By: Dylan Roscover
  • Inspiration and Guidance From: Elburz Sorkhabi, Matthew Ragan, and Wieland Hilker

Their combined expertise has resulted in a tool that significantly enhances the TouchDesigner development experience.

 

Conclusion

Embody addresses a critical need in the TouchDesigner community by simplifying the externalization process. Whether you're a solo developer looking to keep your projects organized or part of a team that requires efficient collaboration tools, Embody offers a robust solution.

By automating the tedious aspects of externalization, you can focus on what matters most—creating engaging and innovative visual experiences with TouchDesigner.

Asset Downloads

Comments