vvvv gamma Fundamentals

What Is vvvv gamma

vvvv gamma is a visual programming environment for .NET 8. It combines node-based patching with C# code generation, targeting Stride (3D engine) and .NET APIs. Programs are built by connecting nodes with links in a visual editor.

vvvv is a live programming environment — programs run continuously while you build them. Both visual patch edits and C# code changes take effect immediately without restarting. vvvv compiles C# source files itself via Roslyn into in-memory assemblies on every save.

Document Structure

.vl files — vvvv gamma documents (XML-based, version controlled)
Each document contains Patches (visual programs) and Definitions (types, operations)
Documents can reference NuGet packages and other .vl files
The Patch Explorer shows the document's type hierarchy

Execution Model

Frame-based evaluation — the mainloop evaluates the entire graph every frame (~60 FPS)
Data flows left-to-right, top-to-bottom through links between nodes
Process nodes maintain state between frames (constructor → Update loop → Dispose)
Operation nodes are pure functions evaluated each frame
vvvv evaluates all connected nodes, skips disconnected subgraphs

Live Compilation Model

vvvv runs your program continuously while you edit it. There is no edit-compile-run cycle for patches and shaders. For C#, live reload depends on how the code is referenced.

Patch Changes

Edits to visual patches apply immediately
Node state (instance fields) is preserved across edits
New nodes and links become active on the next frame

Shader Changes

.sdsl shader files always live-reload when saved
vvvv recompiles shaders in the background and swaps them in the running program

C# — Two Workflows

C# code can be integrated via source project reference or pre-compiled binary. The choice depends on project size and development phase.

Source project reference (live reload):

When a .vl document references a .csproj source project, vvvv compiles .cs files itself via Roslyn into in-memory assemblies. No dotnet build or external toolchain is involved.

On .cs file save, vvvv detects the change and recompiles in the background
Status indicator: gray = building symbols, orange = emitting C#
On successful compilation, affected nodes restart their lifecycle:
1. Dispose() called on old instance
2. New constructor runs (with fresh NodeContext)
3. Update() resumes on the next frame
Static fields reset on reload — the entire in-memory assembly is replaced
On compilation error, the program continues running with the last valid code

Binary reference (no live reload):

When a .vl document references a pre-compiled DLL or NuGet package, the assembly is loaded once at startup. To pick up changes, you must rebuild the DLL externally (e.g., dotnet build) and restart vvvv. This workflow is common for larger projects and stable libraries where live reload is not needed.

Node Categories

Process Nodes

Have Create (constructor), Update (per-frame), and Dispose lifecycle
Written in C# with [ProcessNode] attribute
Maintain internal state between frames
Use change detection to avoid redundant work

Operation Nodes

Pure functions: same input always produces same output
Written as static C# methods (auto-discovered by vvvv)
No state between frames
No [ProcessNode] attribute needed

Adaptive Nodes

Nodes that adapt their implementation based on connected input types
Example: + works with int, float, Vector3, string, etc.
Resolved at link-time, not runtime

Pins, Pads, and Links

Pins — inputs and outputs on nodes and regions
Pads — visual nodes for reading/writing Properties inside operation patches; all pads with the same name refer to the same property
Links — connections between pins that define data flow and execution order
Spreading — when a Spread<T> connects to a single-value input, the node auto-iterates

When to Patch vs Write C#

Use Patching	Use C# Code
Prototyping, data flow	Custom nodes, performance-critical code
Visual connections, UI composition	Complex algorithms
Real-time parameter tweaking	.NET library interop
Dataflow routing and spreading	Native/unmanaged resource management

Channels — Reactive Data Flow

IChannel<T> — observable value container
IChannel<T>.Value — read/write the current value
Channel.IsValid() — check if connected
Channels persist state across sessions
Enable two-way data binding between UI and patch

For C# channel integration patterns (IChannelHub, PublicChannelHelper, [CanBePublished]), see vvvv-channels.

Key Data Types

Type	C# Equivalent	Usage
`Spread<T>`	`ImmutableArray<T>`	vvvv's immutable collection
`SpreadBuilder<T>`	`ImmutableArray<T>.Builder`	Build spreads efficiently
Float32, Int32, etc.	`float`, `int`	Primitives
`Vector2/3/4`	`Stride.Core.Mathematics`	Spatial math
`Color4`	`Stride.Core.Mathematics`	RGBA color

File Types

Extension	Purpose
`.vl`	vvvv gamma documents (XML-based)
`.sdsl`	Stride shader files (SDSL language)
`.cs`	C# source files for custom nodes
`.csproj`	.NET project files
`.nuspec`	NuGet package spec

Ecosystem Overview

vvvv's functionality extends through NuGet packages that bundle .vl documents, C# nodes, and shaders.

Domain	Key Packages
3D Rendering	VL.Stride (Stride engine), VL.Fuse (GPU visual programming)
2D Rendering	VL.Skia, ImGui, Avalonia, CEF/HTML
Hardware I/O	DMX/Art-Net, ILDA lasers, depth cameras (Azure Kinect, ZED), robotics (KUKA, Spot), Ultraleap, LiDAR
Networking	OSC, MIDI, MQTT, Redis, WebSocket, HTTP, TCP/UDP, ZeroMQ, Modbus, Ableton Link
Computer Vision	OpenCV, MediaPipe, YOLO (v8–v11), ONNX Runtime
Audio	NAudio, VST hosting, SuperCollider bridge
General .NET	Any of 100,000+ standard NuGet packages via .csproj reference

To add a package: reference it in your .vl document's Dependencies, or add a <PackageReference> to your .csproj. See vvvv-dotnet for .csproj details.

AppHost & Runtime Detection

// Detect if running as exported .exe vs editor
bool isExported = nodeContext.AppHost.IsExported;

// Register per-app singleton services
nodeContext.AppHost.Services.RegisterService(myService);

For detailed reference, see reference.md.

vvvv-fundamentals