vvvv gamma Fundamentals

What Is vvvv gamma

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

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

dotnet build

• 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

dotnet build

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#

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

Key Data Types

Spread<T>

ImmutableArray<T>

SpreadBuilder<T>

ImmutableArray<T>.Builder

float

int

Vector2/3/4

Stride.Core.Mathematics

Color4

Stride.Core.Mathematics

File Types

.vl

.sdsl

.cs

.csproj

.nuspec

Ecosystem Overview

.vl

<PackageReference>

.csproj

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);