Vvvv Fileformat

Describes the .vl XML file format used by vvvv gamma — document structure, element hierarchy, ID system (base62 GUIDs), NodeReference/Choice patterns, Pins, Pads (IOBoxes), Links, ProcessDefinition/Fragment lifecycle, regions (If/ForEach/Cache), type definitions, TypeAnnotations, and property serialization. Use when generating, parsing, or modifying .vl files programmatically, or when understanding the structure of vvvv patches at the XML level.

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

xml

<?xml version="1.0" encoding="utf-8"?>
<Document xmlns:p="property" xmlns:r="reflection" Id="C2vqbtoStWoOI1eKIKZBBM"
          LanguageVersion="2024.6.0" Version="0.128">
  <!-- dependencies and patch -->
</Document>

Prefix	URI	Purpose
p	property	Required. Complex properties as child elements (<p:NodeReference>)
r	reflection	Optional. Only when using r:IsNull="true" for explicit null values

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

text

Document
├── NugetDependency (0..n)
├── DocumentDependency (0..n)
├── PlatformDependency (0..n)
└── Patch (exactly 1, top-level)
    ├── Canvas (DefaultCategory, CanvasType="FullCategory")
    └── Node (Name="Application")
        └── Patch (inner)
            ├── Canvas (CanvasType="Group")
            │   ├── Node (operation calls)
            │   ├── Pad (IOBoxes)
            │   └── ...
            ├── Patch (Name="Create")
            ├── Patch (Name="Update")
            ├── ProcessDefinition
            │   ├── Fragment → Create patch
            │   └── Fragment → Update patch
            └── Link (0..n)

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

Dependencies

xml

<NugetDependency Id="..." Location="VL.CoreLib" Version="2024.6.0" />
<DocumentDependency Id="..." Location="./MyOtherFile.vl" />
<PlatformDependency Id="..." Location="VL.Core.dll" />

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

xml

<p:NodeReference LastCategoryFullName="Primitive.Math" LastDependency="CoreLibBasics.vl">
  <Choice Kind="NodeFlag" Name="Node" Fixed="true" />
  <Choice Kind="OperationCallFlag" Name="+" />
</p:NodeReference>

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

Type Definitions

xml

<!-- Process -->
<Choice Kind="ContainerDefinition" Name="Process" />
<CategoryReference Kind="Category" Name="Primitive" />

<!-- Class / Record / Interface / Forward -->
<Choice Kind="ClassDefinition" Name="Class" />
<Choice Kind="RecordDefinition" Name="Record" />
<Choice Kind="InterfaceDefinition" Name="Interface" />
<Choice Kind="ForwardDefinition" Name="Forward" />

Regions

xml

<Choice Kind="StatefulRegion" Name="Region (Stateful)" Fixed="true" />
<CategoryReference Kind="Category" Name="Primitive" />
<Choice Kind="ApplicationStatefulRegion" Name="If" />  <!-- or ForEach, Cache -->

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

Node Element

xml

<Node Name="MyNode" Bounds="300,200,65,19" Id="...">
  <p:NodeReference>...</p:NodeReference>
  <Pin Id="..." Name="Input" Kind="InputPin" />
  <Pin Id="..." Name="Output" Kind="OutputPin" />
</Node>

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

Pin Element

xml

<Pin Id="..." Name="Value" Kind="InputPin" DefaultValue="42" />
<Pin Id="..." Name="Result" Kind="OutputPin" />

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

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

Pad Element (IOBox)

xml

<Pad Id="..." Bounds="200,160,80,20" ShowValueBox="true" isIOBox="true" Value="3.14"
     Comment="My Value">
  <p:TypeAnnotation LastCategoryFullName="Primitive" LastDependency="CoreLibBasics.vl">
    <Choice Kind="TypeFlag" Name="Float32" />
  </p:TypeAnnotation>
</Pad>

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

Comment Pad

xml

<Pad Id="..." Bounds="100,100,400,25" ShowValueBox="true" isIOBox="true"
     Value="Title text here">
  <p:TypeAnnotation><Choice Kind="TypeFlag" Name="String" /></p:TypeAnnotation>
  <p:ValueBoxSettings>
    <p:fontsize p:Type="Int32">14</p:fontsize>
    <p:stringtype p:Assembly="VL.Core" p:Type="VL.Core.StringType">Comment</p:stringtype>
  </p:ValueBoxSettings>
</Pad>

Link Element

xml

<Link Id="..." Ids="outputPinId,inputPinId" />

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

ProcessDefinition and Fragments

xml

<Patch Id="innerPatchId">
  <Canvas Id="..." CanvasType="Group" />
  <Patch Id="createId" Name="Create" />
  <Patch Id="updateId" Name="Update" />
  <ProcessDefinition Id="...">
    <Fragment Id="..." Patch="createId" Enabled="true" />
    <Fragment Id="..." Patch="updateId" Enabled="true" />
  </ProcessDefinition>
</Patch>

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:

xml

<Node Bounds="100,200,400,300" Id="...">
  <p:NodeReference LastCategoryFullName="Primitive" LastDependency="Builtin">
    <Choice Kind="StatefulRegion" Name="Region (Stateful)" Fixed="true" />
    <CategoryReference Kind="Category" Name="Primitive" />
    <Choice Kind="ApplicationStatefulRegion" Name="If" />
  </p:NodeReference>
  <Patch Id="...">
    <Canvas Id="..." CanvasType="Group"><!-- content --></Canvas>
    <Patch Id="thenId" Name="Then" />
    <Fragment Id="..." Patch="thenId" Enabled="true" />
  </Patch>
  <ControlPoint Id="..." Bounds="150,200" Alignment="Top" />
  <ControlPoint Id="..." Bounds="150,500" Alignment="Bottom" />
</Node>

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

TypeAnnotation

xml

<!-- Simple type -->
<p:TypeAnnotation>
  <Choice Kind="TypeFlag" Name="Float32" />
</p:TypeAnnotation>

<!-- Generic type: Spread<RGBA> -->
<p:TypeAnnotation LastCategoryFullName="Collections" LastDependency="VL.Collections.vl">
  <Choice Kind="TypeFlag" Name="Spread" />
  <p:TypeArguments>
    <TypeReference LastCategoryFullName="Color" LastDependency="CoreLibBasics.vl">
      <Choice Kind="TypeFlag" Name="RGBA" />
    </TypeReference>
  </p:TypeArguments>
</p:TypeAnnotation>

Slot Element (State Fields)

xml

<Slot Id="..." Name="MyField">
  <p:TypeAnnotation><Choice Kind="TypeFlag" Name="Float32" /></p:TypeAnnotation>
  <p:Value>0.5</p:Value>
</Slot>

Complete Minimal Example

xml

<?xml version="1.0" encoding="utf-8"?>
<Document xmlns:p="property" Id="A1b2C3d4E5f6G7h8I9j0Kl"
          LanguageVersion="2024.6.0" Version="0.128">
  <NugetDependency Id="B2c3D4e5F6g7H8i9J0k1Lm" Location="VL.CoreLib"
                   Version="2024.6.0" />
  <Patch Id="C3d4E5f6G7h8I9j0K1l2Mn">
    <Canvas Id="D4e5F6g7H8i9J0k1L2m3No" DefaultCategory="Main"
            BordersChecked="false" CanvasType="FullCategory" />
    <Node Name="Application" Bounds="100,100" Id="E5f6G7h8I9j0K1l2M3n4Op">
      <p:NodeReference>
        <Choice Kind="ContainerDefinition" Name="Process" />
        <CategoryReference Kind="Category" Name="Primitive" />
      </p:NodeReference>
      <Patch Id="F6g7H8i9J0k1L2m3N4o5Pq">
        <Canvas Id="G7h8I9j0K1l2M3n4O5p6Qr" CanvasType="Group" />
        <Patch Id="H8i9J0k1L2m3N4o5P6q7Rs" Name="Create" />
        <Patch Id="I9j0K1l2M3n4O5p6Q7r8St" Name="Update" />
        <ProcessDefinition Id="J0k1L2m3N4o5P6q7R8s9Tu">
          <Fragment Id="K1l2M3n4O5p6Q7r8S9t0Uv"
                   Patch="H8i9J0k1L2m3N4o5P6q7Rs" Enabled="true" />
          <Fragment Id="L2m3N4o5P6q7R8s9T0u1Vw"
                   Patch="I9j0K1l2M3n4O5p6Q7r8St" Enabled="true" />
        </ProcessDefinition>
      </Patch>
    </Node>
  </Patch>
</Document>

Validation Rules

1. All IDs must be unique (22-char base62 GUIDs)
2. xmlns:p="property" must be on Document
3. Version="0.128" always required
4. Fragment Patch must reference existing sibling Patch IDs
5. Link Ids: exactly "sourceId,sinkId" — output first
6. CanvasType="FullCategory" 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. isIOBox uses lowercase i
11. Dependencies are children of Document, not Patch

Common Mistakes

• Forgetting xmlns:p="property" namespace declaration
• Putting dependencies inside Patch instead of Document
• 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 isIOBox

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.