vvvv-node-libraries

Creating vvvv gamma Node Libraries

A node library is a project that provides multiple nodes to vvvv gamma as a distributable package. This skill covers the project-level concerns: directory structure, naming conventions, category organization, service registration, and node factories.

For writing individual node classes (ProcessNode, Update, pins, change detection), see vvvv-custom-nodes. For consuming services inside node constructors (IFrameClock, Game, logging), see vvvv-custom-nodes/services.md.

Creating your own library vs. contributing to one you don't own are different tasks. This SKILL.md and its design/publishing references cover creating and distributing a package. To change or submit a PR to an existing/upstream library (fork → branch → PR workflow, editable source packages, the .vl diff problem), see contributing.md.

Library Recognition Pattern

vvvv recognizes a directory as a library when the folder name, .vl file, and .nuspec all share the same name:

VL.MyLibrary/                       # Folder name = package name
├── VL.MyLibrary.vl                 # .vl document — MUST match folder name
├── VL.MyLibrary.nuspec             # NuGet spec — MUST match folder name
├── lib/
│   └── net8.0/                     # Compiled DLLs go here
│       └── VL.MyLibrary.dll
├── src/
│   ├── Initialization.cs           # [assembly:] attributes + AssemblyInitializer
│   ├── Nodes/
│   │   ├── MyProcessNode.cs        # [ProcessNode] classes
│   │   └── MyOperations.cs         # Static methods (stateless nodes)
│   ├── Services/
│   │   └── MyService.cs            # Per-app singletons
│   └── VL.MyLibrary.csproj
├── shaders/                         # Optional: SDSL shaders (auto-discovered)
│   └── MyEffect_TextureFX.sdsl
└── help/                            # Optional: .vl help patches
    └── HowTo Use MyNode.vl

Critical conventions:

• Folder name, .vl file, and .nuspec must be identical (e.g., all VL.MyLibrary)
• The .csproj must output DLLs to lib/net8.0/ relative to the package root
• No .vl file within a package should reference a .csproj — this forces the package into editable mode
• The library directory must be in a configured package-repository directory for vvvv to find it

.csproj Output Path

The .csproj must compile into the library's lib/net8.0/ folder:

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <OutputPath>..\..\lib\net8.0\</OutputPath>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

What gets imported as a node — the foundational rule

A type becomes a node in vvvv's node browser when two conditions are both true:

1. The type is public (and lives in an imported assembly).
2. The type's C# namespace is covered by an [assembly: ImportAsIs] / [assembly: ImportNamespace] declaration, OR the type is listed by an [assembly: ImportType] declaration.

If either condition is false, the type is invisible to vvvv. Importing is opt-in by namespace, not by type accessibility alone. A public class in a namespace nobody imports is just as hidden from the node browser as an internal class.

When a type IS imported, vvvv generates nodes from its full public surface:

• Public classes and structs → constructor + public methods/properties become nodes
• Public static methods → operation nodes
• Public enums → split + values become nodes
• Public records and interfaces → handled like classes

[ProcessNode] does NOT gate node visibility. It is purely lifecycle sugar — it tells vvvv "this is a stateful class with an Update() method, manage one instance per node, call Update() each frame". A plain public class Foo { public Foo() {} public int Bar(int x) => x; } in an imported namespace becomes a node browser entry exactly the same as one decorated with [ProcessNode]. The attribute affects how the node is invoked, not whether it appears.

Implication for library design: the primary lever for "what shows up in the node browser" is which namespaces you import, not which types are public. But note that importing is recursive — declaring one root namespace pulls in every namespace nested below it, so a .Internal sub-namespace is not a hiding place. See Excluding helpers from the node browser for the four levers that actually work.

Source: VL.StandardLibs ImportAsIsAttribute, Gray Book — Writing nodes using C#.

Initialization.cs — The Entry Point

Every node library needs assembly-level attributes. Combine in one file:

using VL.Core;
using VL.Core.CompilerServices;
using VL.Core.Import;

// Required: tells vvvv to scan this assembly for nodes
[assembly: ImportAsIs(Namespace = "MyCompany.MyLibrary", Category = "MyLibrary")]

// Optional: register services before any node runs
[assembly: AssemblyInitializer(typeof(MyCompany.MyLibrary.Initialization))]

namespace MyCompany.MyLibrary;

public sealed class Initialization : AssemblyInitializer<Initialization>
{
    public override void Configure(AppHost appHost)
    {
        var services = appHost.Services;

        // Register per-app singletons (created lazily on first access)
        services.RegisterService<MyService>(serviceProvider =>
        {
            return new MyService(serviceProvider);
        });
    }
}

Choosing the right import attribute

vvvv provides three assembly-level attributes for declaring what becomes a node. Pick based on how much control you need.

[assembly: ImportAsIs] — single, namespace-rooted

[assembly: ImportAsIs(Namespace = "VL.MyLib", Category = "MyLib")]

Both parameters are optional; all four combinations are legal and each does something different:

[assembly: ImportAsIs]                                            // the scaffolded default:
                                                                  // nothing stripped, no root →
                                                                  // VL.MyLib.Particles ⇒ "VL.MyLib.Particles"
[assembly: ImportAsIs(Namespace = "VL.MyLib")]                    // strip only →
                                                                  // VL.MyLib.Particles ⇒ "Particles" (top level!)
[assembly: ImportAsIs(Category = "MyLib")]                        // root only →
                                                                  // VL.MyLib.Particles ⇒ "MyLib.VL.MyLib.Particles"
[assembly: ImportAsIs(Namespace = "VL.MyLib", Category = "MyLib")] // ✅ strip + root →
                                                                  // VL.MyLib.Particles ⇒ "MyLib.Particles"

The last form is what you almost always want. Use ImportAsIs when the whole library lives under one root namespace and you want one root category. You cannot stack two ImportAsIs to split sub-namespaces into different categories — it is AllowMultiple = false.

[assembly: ImportNamespace] — per-namespace, multi-use

// ⚠️ Order matters — first declaration wins. Specific before general.
[assembly: ImportNamespace("VL.MyLib.Renderers",    Category = "MyLib.Rendering")]
[assembly: ImportNamespace("VL.MyLib.Resources",    Category = "MyLib.Resources")]
[assembly: ImportNamespace("VL.MyLib.Experimental", Category = "MyLib.Experimental")]
[assembly: ImportNamespace("VL.MyLib",              Category = "MyLib")]   // catch-all, LAST

Use when one library has multiple sub-namespaces and you want each to land in a distinct category — without polluting the browser with C# folder names. This is the right tool for multi-category libraries.

[assembly: ImportType] — per-type, hand-picked

[assembly: ImportType(typeof(MyRenderer),  Category = "MyLib.Rendering")]
[assembly: ImportType(typeof(MyResource),  Category = "MyLib.Resources", Name = "Resource")]

Use for surgical control — e.g. when you want to expose only a curated subset of a large internal codebase, or to force one outlier into a different category than its namespace siblings.

Decision matrix

🛑 Importing is RECURSIVE — a nested namespace is NOT a hiding place

This is the single most common way a library's node browser gets polluted, and the mistake is easy to make because the intent reads as obviously correct.

ImportFromNamespace in [AssemblySy

Content truncated.