创建 vvvv gamma 节点库

节点库是一个项目，它以可分发包的形式向 vvvv gamma 提供多个节点。本技能涵盖项目层面的关注点：目录结构、命名约定、类别组织、服务注册和节点工厂。

关于编写单个节点类（ProcessNode、Update、引脚、变化检测），请参阅 vvvv-custom-nodes。关于在节点构造函数中消费服务（IFrameClock、Game、日志记录），请参阅 vvvv-custom-nodes/services.md。

库识别模式

当文件夹名称、.vl 文件和 .nuspec 共享相同名称时，vvvv 会将一个目录识别为库：

VL.MyLibrary/ # 文件夹名称 = 包名称
├── VL.MyLibrary.vl # .vl 文档 — 必须与文件夹名称匹配
├── VL.MyLibrary.nuspec # NuGet 规范 — 必须与文件夹名称匹配
├── lib/
│ └── net8.0/ # 编译后的 DLL 放在此处
│ └── VL.MyLibrary.dll
├── src/
│ ├── Initialization.cs # [assembly:] 属性 + AssemblyInitializer
│ ├── Nodes/
│ │ ├── MyProcessNode.cs # [ProcessNode] 类
│ │ └── MyOperations.cs # 静态方法（无状态节点）
│ ├── Services/
│ │ └── MyService.cs # 每个应用程序的单例
│ └── VL.MyLibrary.csproj
├── shaders/ # 可选：SDSL 着色器（自动发现）
│ └── MyEffect_TextureFX.sdsl
└── help/ # 可选：.vl 帮助补丁
└── HowTo Use MyNode.vl

关键约定：

• - 文件夹名称、.vl 文件和 .nuspec 必须相同（例如，全部为 VL.MyLibrary）
• .csproj 必须将 DLL 输出到相对于包根目录的 lib/net8.0/
• 包内的任何 .vl 文件都不应引用 .csproj — 这会将包强制进入可编辑模式
• 库目录必须位于已配置的 package-repository 目录中，以便 vvvv 能够找到它

.csproj 输出路径

.csproj 必须编译到库的 lib/net8.0/ 文件夹中：

xml

net8.0
..\..\lib\net8.0\
false

Initialization.cs — 入口点

每个节点库都需要程序集级别的属性。合并到一个文件中：

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

// 必需：告诉 vvvv 扫描此程序集以查找节点
[assembly: ImportAsIs(Namespace = MyCompany.MyLibrary, Category = MyLibrary)]

// 可选：在任何节点运行之前注册服务
[assembly: AssemblyInitializer(typeof(MyCompany.MyLibrary.Initialization))]

namespace MyCompany.MyLibrary;

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

// 注册每个应用程序的单例（在首次访问时延迟创建）
services.RegisterService(serviceProvider =>
{
return new MyService(serviceProvider);
});
}
}

ImportAsIs 和类别命名

不带参数（[assembly: ImportAsIs]）时，vvvv 会扫描所有命名空间，并剥离一个命名空间层级以派生类别。带参数的形式可以显式控制库的组织结构。

命名空间 → 类别映射：C# 命名空间映射到以点分隔的节点浏览器类别。VL.MyLibrary.Particles 中的类在节点浏览器中显示在 MyLibrary.Particles 下（ImportAsIs 中指定的根命名空间被剥离）。

按类型类别覆盖

覆盖单个类型的类别：

csharp
[assembly: ImportType(typeof(SpecialNode), Category = MyLibrary.Advanced)]

使用此方法将特定节点放置到与其命名空间建议不同的类别中。

服务注册模式

服务在 Configure(AppHost) 中注册，并由节点通过 NodeContext 消费。本节仅涵盖注册 — 关于消费模式，请参阅 vvvv-custom-nodes/services.md。

直接单例（推荐）

csharp
services.RegisterService(serviceProvider =>
{
// 在首次调用 GetService() 时延迟创建
return new MyService(serviceProvider);
});

IResourceProvider 模式（用于管理生命周期）

当服务包装需要显式释放的资源时：

csharp
services.RegisterService>(serviceProvider =>
{
var gameProvider = serviceProvider.GetService>();
return gameProvider.Bind(game =>
{
var service = MyGPUService.Create(game);
return ResourceProvider.Return(service, disposeAction: s => s?.Dispose());
});
});

动态节点工厂

为动态节点集注册程序化节点生成：

csharp
public override void Configure(AppHost appHost)
{
// 来自着色器文件或其他来源的动态节点工厂
appHost.RegisterNodeFactory(VL.MyLibrary.ShaderNodes,
init: MyShaderNodeFactory.Init);
}

当节点是从外部文件（着色器、配置）生成而不是作为 C# 类编写时，请使用节点工厂。有关详细信息，请参阅 vvvv 节点工厂文档。

服务访问的扩展方法

为您的服务提供类型化访问器：

csharp
public static class MyLibraryExtensions
{
public static MyService? GetMyService(this ServiceRegistry services)
=> services.GetService(typeof(MyService)) as MyService;

public static MyService? GetMyService(this IServiceProvider services)
=> services.GetService(typeof(MyService)) as MyService;
}

.csproj 要点

完整的库 .csproj，输出到 lib/net8.0/：

xml


net8.0
enable
..\..\lib\net8.0\
false

将 VL 包版本与您的 vvvv 安装版本匹配。OutputPath 将编译后的 DLL 放置在库的 lib/net8.0/ 文件夹中，vvvv 期望在此处找到它们。

实际示例：自定义渲染库

带有服务注册和节点工厂的库初始化：

csharp
[assembly: AssemblyInitializer(typeof(Initialization))]
[assembly: ImportAsIs(Namespace = VL.MyRendering, Category = MyRendering)]

public sealed class Initialization : AssemblyInitializer
{
public override void Configure(AppHost appHost)
{
appHost.Services.RegisterService(sp =>
{
var vlGame = sp.GetService();
if (vlGame == null) return null!;
var customGame = CustomGameSystem.Create(vlGame, sp);
vlGame.GameSystems.Add(customGame);
return customGame;
});

// 来自着色器文件的动态节点工厂
appHost.RegisterNodeFactory(VL.MyRendering.ShaderNodes,
init: ShaderNodeFactory.Init);
}
}

有关命名约定、引脚规则、方面和标准类型，请参阅 design-guidelines.md。
有关发布 NuGet 包、帮助补丁和库结构，请参阅 publishing.md。
有关完整的实际示例（VL.IO.MQTT、VL.Audio），请参阅 examples.md。