Skill: tebjan/vvvv-fileformat (version 1.0.0)

--- name: vvvv-fileformat description: "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." license: CC-BY-SA-4.0 compatibility: Designed for coding AI agents assisting with vvvv gamma development metadata: author: Kopffarben version: "1.0" --- # 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 ``` 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](format-reference.md). For layout conventions, spacing, positioning, and visual organization best practices, see [best-practices.md](best-practices.md).


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector:  ()