Code structure¶
This page maps the TiXL repository: which folder holds what, and where to look for a given task. It is a starting point for finding your way around, not a full architecture description. For more depth, read SOLUTION_OVERVIEW.md.
Everything lives in one repository, tixl3d/tixl, with a single solution file, t3.sln. To get it running, follow Set up a development environment.
The big picture¶
TiXL has three layers:
Core/is the runtime: the operator model, evaluation, resources, rendering, animation and audio. The editor, the player and every operator package use it.Editor/is the authoring application: the graph, parameter window, timeline, project hub, and all other user interface.Operators/contains the content: packages of operators that are compiled and loaded at runtime, just like your own projects.
Player/ runs exported projects without the editor. The remaining projects are support libraries that these four use.
Dependencies only point downward: Editor and Player use Core, and operators use Core. Core never depends on the editor. Put a change in the narrowest place that works: runtime behavior in Core, editor-only tooling in Editor, effects and content in an operator package.
Top-level folders¶
| Folder | Contents |
|---|---|
Core/ |
Runtime engine shared by editor, player and operators |
Editor/ |
The TiXL editor application |
Player/ |
Playback host for exported projects |
Operators/ |
Operator packages: Lib, TypeOperators, Examples, Skills and integrations |
Logging/ |
Logging and diagnostics |
Serialization/ |
JSON serialization helpers |
SystemUi/ |
Platform-neutral interfaces for dialogs, windows and clipboard |
MsForms/, SilkWindows/, ImguiWindows/ |
Window creation, input and the ImGui bridge |
IoServices/ |
MIDI, OSC, game pads and other live I/O |
VideoServices/ |
FFmpeg-based video decoding and export |
ProjectUpdater/ |
Converts projects and operators from older versions |
EditorResources/ |
Fonts, icons and shaders used by the editor UI |
Dependencies/, Vendor/ |
Prebuilt third-party libraries |
Installer/ |
Installer and packaging scripts per platform |
Core.Tests/, VideoServices.Tests/, Tests/ |
Unit tests and editor integration tests |
Spikes/ |
Small throw-away experiments. Not part of the product |
.Defaults/ |
Default content copied into new installations: project template, layouts, themes, the Skill Quest map |
.help/ |
User documentation, embedded help, release notes and the help index. See Documentation structure |
.tests-manual/ |
Manual test sets for releases |
.agentic/ |
Instructions and plans for coding agents |
.github/ |
CI workflows, build actions and issue templates |
The Linux and macOS port replaces the DirectX-only windowing with a graphics abstraction. On that branch you will also find Graphics/ (the backend-neutral GPU interface), Graphics.D3D11/ and Graphics.Vulkan/ (the two backends), Graphics.Compat/ (compatibility for older operator code), SdlPlatform/ (windows and input through SDL) and Native/ (native audio code).
Core¶
| Folder | What you'll find |
|---|---|
Core/Operator/ |
Symbol, Instance, slots, connections, EvaluationContext: the operator model and its evaluation |
Core/Compilation/ |
Loading operator assemblies and discovering operator types |
Core/Model/ |
Symbol packages and project metadata |
Core/Resource/ |
Resource manager, shader compilation, assets and package resources |
Core/Rendering/, Core/DataTypes/ |
Rendering helpers and the data types that flow between operators (points, meshes, textures, …) |
Core/Animation/ |
Curves, keyframes and the animator |
Core/Audio/ |
Audio playback, analysis and beat timing |
Core/IO/, Core/Video/, Core/Output/ |
Input devices, video and output handling |
Core/Settings/ |
Settings shared by editor and player |
Editor¶
| Folder | What you'll find |
|---|---|
Editor/Program.cs |
Startup |
Editor/Compilation/ |
Loading and recompiling projects and packages in the editor |
Editor/UiModel/ |
The editor's model of symbols and projects, and Commands/ for every undoable change |
Editor/Gui/MagGraph/ |
The graph editor (the "magnetic graph"): model, interaction, drawing |
Editor/Gui/Windows/ |
Parameter window, output window, timeline, settings, render export, asset library and other windows |
Editor/Gui/Hub/ |
Project hub and Skill Quest panel |
Editor/Gui/Interaction/ |
Shared interaction: keyboard actions, snapping, transform gizmos, MIDI control |
Editor/Gui/InputUi/, Editor/Gui/OutputUi/, Editor/Gui/OpUis/ |
How parameters, outputs and special operators are drawn |
Editor/Gui/Styling/ |
Colors, fonts, icons and shared widgets (CustomComponents) |
Editor/Gui/Help/ |
Operator help, embedded help, release notes and video links |
Editor/Gui/Graph/Legacy/ |
The previous graph editor. Kept for compatibility; not a reference for new code |
Editor/Skills/ |
Skill Quest runtime |
Editor/Migrations/ |
Upgrading projects from older TiXL versions |
Operators¶
Each folder under Operators/ is a package, laid out the same way as a user project:
Symbols/holds the operators, each as a.csfile (code), a.t3file (the graph) and a.t3uifile (layout, descriptions, parameter settings). Subfolders follow the namespace.Assets/holds shaders, images, meshes and other files the operators load.Utils/holds helper classes shared by several operators.
| Package | Contents |
|---|---|
Operators/Lib/ |
The operator library. Namespaces in Symbols/: image, point, particle, mesh, render, field, numbers, string, flow, data, io, geometry |
Operators/Lib/Assets/shaders/ |
HLSL shaders for the library, grouped by area (img, points, particles, sdf, …) |
Operators/TypeOperators/ |
Basic operators for TiXL's own data types |
Operators/Examples/ |
Examples for library operators (Symbols/Lib/), HowTos, templates and tutorials |
Operators/Skills/ |
Skill Quest levels |
Operators/Io/, Operators/Video/, Operators/Ndi/, Operators/Spout/, Operators/Mediapipe/, Operators/Unsplash/ |
Integrations with external devices, protocols and services |
Where to look for…¶
| Task | Start in |
|---|---|
| An operator gives wrong results | Its .cs in Operators/Lib/Symbols/…, then its shader in Operators/Lib/Assets/shaders/ |
| Improving an operator description | The operator's .t3ui, or edit it in the editor's help panel |
| A new example | Operators/Examples/Symbols/Lib/, mirroring the operator's namespace |
| A crash on startup or project load | Editor/Program.cs, Editor/Compilation/ProjectSetup.cs, Core/Compilation/ |
| Graph editing behaves strangely | Editor/Gui/MagGraph/Interaction/ |
| A parameter is drawn wrongly | Editor/Gui/InputUi/ and Editor/Gui/Windows/ParameterWindow.cs |
| Something can't be undone | Editor/UiModel/Commands/ |
| Timeline or keyframes | Editor/Gui/Windows/TimeLine/, Core/Animation/ |
| Shader compilation errors | Core/Resource/ShaderCompiling/ |
| MIDI, OSC or other input | IoServices/, Operators/Lib/Symbols/io/ |
| Video playback or export | VideoServices/, Editor/Gui/Windows/RenderExport/ |
| Exported executable misbehaves | Player/ |
| Opening an old project fails | Editor/Migrations/, ProjectUpdater/ |
| Colors, fonts or icons | Editor/Gui/Styling/ |
Where your own projects are¶
Your projects are not part of the repository. They live in your documents folder, and each project is its own operator package with the same Symbols/ and Assets/ layout. See Files and folders.