VL File Format (.vl)

Overview

A .vl file is an XML document encoding a visual dataflow program for vvvv gamma. Key elements:

• - Document — root element, contains dependencies and one top-level Patch
• Patch — container for visual elements (Nodes, Pads, Links, Canvases)
• Node — operation calls, type definitions, or regions
• Pin — input/output on a Node (defined at definition site)
• Pad — visual data element (IOBox) for displaying/editing values
• Link — connects two endpoints by referencing their IDs
• Canvas — visual grouping container (no logical scope)
• ProcessDefinition — lifecycle definition (Create, Update) via Fragments
• Slot — state field within a type definition

XML Root and Namespaces

CODEBLOCK0

Root attributes: Id (base62 GUID), LanguageVersion (e.g. "2024.6.0"), Version (always "0.128").

ID System

Every element has a unique Id — a 22-character base62-encoded GUID using [0-9A-Za-z]. All IDs must be unique within the document. Generate via GUIDEncoders.GuidTobase62(Guid.NewGuid()).

Link Ids attribute: comma-separated "sourceId,sinkId" (output first, input second).

Element Hierarchy

CODEBLOCK1

Critical: Dependencies are direct children of Document, NOT inside Patch.

Dependencies

CODEBLOCK2

Almost every document needs VL.CoreLib. Use IsForward="true" to re-export types to consumers.

NodeReference System (Choices)

The <p:NodeReference> property defines what a Node IS. It contains <Choice> elements that identify the target symbol.

Operation Call

CODEBLOCK3

• - First Choice: Kind="NodeFlag" with Fixed="true" (shape indicator)
• Second Choice: ProcessAppFlag (stateful) or OperationCallFlag (stateless)

Type Definitions

CODEBLOCK4

Regions

CODEBLOCK5

Regions use StatefulRegion as the FIRST Choice (not NodeFlag). Use ApplicationStatefulRegion for If/ForEach or ProcessStatefulRegion for Cache.

Node Element

CODEBLOCK6

Key attributes: Id, Name, Bounds ("X,Y" or "X,Y,W,H"), Summary, Tags.

Pin Element

CODEBLOCK7

Kind values: InputPin, OutputPin, StateInputPin, StateOutputPin, ApplyPin.

Visibility: Visible (default), Optional, OnCreateDefault, Hidden.

Pad Element (IOBox)

CODEBLOCK8

Note the lowercase i in isIOBox. Common types: Boolean, Int32, Float32, Float64, String, Vector2, Vector3.

Comment Pad

CODEBLOCK9

Link Element

CODEBLOCK10

INLINECODE56 format: "sourceId,sinkId" — output first, input second. Use IsFeedback="true" for feedback loops, IsHidden="true" for reference links.

ProcessDefinition and Fragments

CODEBLOCK11

Fragment Patch attribute references a sibling <Patch> element's Id.

Regions

Regions use 4-value Bounds ("X,Y,W,H") and have ControlPoints at borders:

CODEBLOCK12

Region patch names: If uses Then/Else, ForEach uses Create/Update/Dispose, Cache uses Create/Update.

TypeAnnotation

CODEBLOCK13

Slot Element (State Fields)

CODEBLOCK14

Complete Minimal Example

CODEBLOCK15

Validation Rules

1. 1. All IDs must be unique (22-char base62 GUIDs)
2. INLINECODE71 must be on INLINECODE72
3. INLINECODE73 always required
4. Fragment Patch must reference existing sibling Patch IDs
5. Link Ids: exactly "sourceId,sinkId" — output first
6. INLINECODE77 only for root canvas
7. Every document needs VL.CoreLib dependency
8. Application node is the entry point (Name="Application", ContainerDefinition)
9. Element names are case-sensitive (Patch not patch)
10. INLINECODE81 uses lowercase INLINECODE82
11. Dependencies are children of Document, not INLINECODE84

Common Mistakes

• - Forgetting xmlns:p="property" namespace declaration
• Putting dependencies inside Patch instead of INLINECODE87
• Reversed Link direction (first ID must be source/output)
• Missing ProcessDefinition for process/class type definitions
• Wrong Bounds format (use commas, no spaces: "100,200,65,19")
• Using IsIOBox instead of INLINECODE90

For the complete element reference with all attributes, Choice kinds, and serialization details, see format-reference.md.
For layout conventions, spacing, positioning, and visual organization best practices, see best-practices.md.