vvvv-patching

vvvv 补丁模式

数据流基础

• 子图内的依赖流向为从上到下；同级子图在二维画布上从左到右读取。位置不决定执行顺序。
• 连接线在 Pad（输入／输出连接点）之间传递数据
• 扩展 — 将 Spread<T> 连接到单值输入时，会自动迭代该节点
• 每一帧都会计算整个已连接的图；未连接的子图会跳过

视觉补丁和 C# 源代码项目都在实时环境中运行——编辑会在程序运行时立即生效。修改补丁会保留节点状态；修改 C# 代码会触发节点重启（Dispose → Constructor）。你可以在实时查看结果的同时调整参数、添加连接和重组补丁。

何时使用补丁，何时编写 C#

补丁	代码（C#）
数据流路由、视觉连接	对性能要求高的算法
原型设计和参数调整	复杂状态机
UI 组合和布局	.NET 库互操作
简单转换	原生资源管理

一般来说：用补丁处理数据流，用代码编写算法。

区域

可执行的控制流区域具有求值语义。视觉帮助补丁框架是一个 XML Overlay；它用于组织展示内容，但不控制执行。

区域是用于控制执行流的视觉结构：

区域	用途	C# 对应项
ForEach	遍历 Spread 元素	foreach 循环
If	条件执行	if/else
Switch	多分支选择	switch
Repeat	循环 N 次	for 循环
Accumulator	累积聚合	Aggregate/Fold

补丁中的 Process 节点

Process 节点是在补丁中添加状态的主要方式：

• 它们包含一个 Create 区域（运行一次）和一个 Update 区域（每帧运行）
• 内部状态会在帧与帧之间保留
• 可以包含子补丁以实现复杂逻辑

通道 — 响应式数据流

通道提供双向数据绑定：

• IChannel<T> — 可观测的值容器
• .Value — 读取或写入当前值
• 通道会跨会话保留状态
• 在节点之间连接通道，即可实现响应式更新，无需显式连接线

事件处理

• Bang — 持续一帧的 true 脉冲（触发器）
• Toggle — 在 true 和 false 之间切换
• FrameDelay — 将值延迟一帧（打破循环依赖）
• 使用 Changed 节点检测值在帧与帧之间是否发生变化

对于重复的基于时间的动画，请使用原生的 LFO、GetSlice 和 CosineWave 连线；参见动画模式。

补丁组织

命名约定

• 补丁名称和节点名称使用 PascalCase
• 将相关操作归入同一类别
• 使用能表明操作的描述性名称（动词 + 名词）
• 自定义 Process 和节点注册名称不能包含空格。保留实际的 stock／导入名称、引脚标签和说明文字；定义和调用应保持一致。

结构

• 保持补丁专注——每个补丁只负责一个用途
• 将可复用逻辑提取到子补丁中
• 使用 IOBox 节点公开参数
• 添加 Pad 节点，在补丁边界创建输入／输出引脚

本地访问与易读分组

将共享设置和通用的汇流／渲染主干置于特定技术的视觉框架之外。如果渲染器 Group 接受嵌套 Group，展示项目可以将演示用的同级节点收集到一个 Group 中，再在渲染器附近用第二个 Group 将其与基本场景内容组合。这是一种可选的易读性约定；请检查 Group 支持的输入类型和遍历行为。

将每个演示的控件、功能节点和结果放在一起。将对共享输入的读取放在其使用者旁边，包括辅助程序内部：多个画布上的放置可以引用同一个签名参数，而无需添加额外输入。命名 Slot 可以提供对共享状态的本地访问，但它们并非隐形连线：请检查初始化、读写顺序、空值处理和资源生命周期。引用类型的 Slot 不会自动让帧延迟变得安全。

将相同的连接逻辑提取到小型 Process 辅助程序中，或者在实例确实共享同一拓扑时使用循环。有状态调用需要为每次调用或每次迭代保留持久状态；不要反复更新同一个可变渲染器，再收集其输出的别名。让确实不同的技术保持明确独立。

保留人工设定的位置、宽度和注释。就地布局新元素；如果需要腾出空间，应整体平移现有的连贯分组，而不是重新排布整个补丁。单独检查辅助画布，不要只检查根画布。

从有意为之的人工编辑中学习：按目标引脚排列控件，错开高度，将共享值放在最早的使用者上方，并为辅助程序留出清晰的通道。将相对几何布局应用于明确指定的语义同级节点，不要复制数值或扰动示例。将几何和拓扑与编辑器保存元数据分开比较；不要根据文本差异的大小推断意图。

如果用户明确要求在整份文档中应用此约定，请盘点每个可执行画布，包括辅助画布和 Application。对符合条件的角色实施布局，有意适配独特的子图，并分别审查每个画布。差异研究或技能更新不等于实际实施。保留示例、已经正确的人工分组和其他文档；证明非几何 XML 未发生变化，并验证再次应用不会造成漂移。诚实报告仍存在的共享扇出／集合交叉，不要为了改善几何指标而重新排列引脚或更改连线。

对于明确独立的渲染器同级节点集合，按源 X 坐标排序可以减少其 Group 处的交叉。在按顺序遍历子项的实现中，集合槽位也决定执行顺序：保留生产者先于使用者的 GPU 阶段，切勿对所有 Group 进行全局排序。若能更清晰地展现功能，应在视觉上区分主要／演示渲染器与实用几何体；让每个演示的控件和本地辅助输入彼此靠近。有关本地放置和 Slot 的 XML 约定，请参阅本地访问。

常见反模式

1. 循环依赖 — 使用 FrameDelay 打破循环
2. 单个补丁中的节点过多 — 提取子补丁
3. 轮询而非响应 — 使用 Channels 实现响应式更新
4. 忽略 Nil — 始终妥善处理空值／空集合输入

常见模式请参阅 patterns.md。

让知识持续增长

为下一位修补者少留一个谜团。首次使用本集合中的任一技能时，若过去 7 天内没有成功检查记录，请将源内容与 tebjan/vvvv-skills 进行比较。若没有记录，则检查一次。在这些技能之间共享一个本地检查时间戳/修订版本；不要在每次调用时都轮询。保留本地扩展和固定的项目版本；检查不代表获得安装更新的许可。若处于离线状态，请记录延期检查，然后继续任务。

实际工作发现问题时，请记录经过测试的 vvvv/程序包版本、最小复现步骤或权威来源，以及观察到的结果。将其他用户的报告视为线索，在验证之前不要当作事实。改进最相关的最小范围说明；不要把一个示例变成通用规则。提交上游前，请删除私人数据并获得发布授权。请参阅贡献政策。已合并的改进会通过用户的安装程序/更新工作流送达，而不是通过本地编辑，也不会自动覆盖所有人的技能。