vvvv-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vvvv gamma Troubleshooting

vvvv gamma 故障排除

C# / ProcessNode Issues

C# / ProcessNode 问题

"Node" Suffix in Class Name

类名中的“Node”后缀

Symptom: Node works but has ugly name in vvvv. Fix: Remove "Node" suffix — vvvv convention forbids it.

csharp

// WRONG
[ProcessNode]
public class SteeringBehaviorNode { }

// CORRECT
[ProcessNode]
public class SteeringBehavior { }

症状：节点可正常工作，但在vvvv中的名称不美观。 修复方案：移除“Node”后缀 —— vvvv的命名约定禁止使用该后缀。

csharp

// WRONG
[ProcessNode]
public class SteeringBehaviorNode { }

// CORRECT
[ProcessNode]
public class SteeringBehavior { }

Out Parameters After Inputs

输出参数位于输入参数之后

Symptom: Pins appear in wrong order or node doesn't compile correctly. Fix:

out

parameters must come FIRST in Update signature.

csharp

// WRONG
public void Update(float input = 0f, out float result) { ... }

// CORRECT
public void Update(out float result, float input = 0f) { ... }

症状：引脚显示顺序错误或节点无法正确编译。 修复方案：

out

参数必须在Update方法签名中排在最前面。

csharp

// WRONG
public void Update(float input = 0f, out float result) { ... }

// CORRECT
public void Update(out float result, float input = 0f) { ... }

Node Not Appearing in Node Browser

节点未出现在节点浏览器中

Symptom: Your C# class exists but doesn't show up in vvvv. Fix: Check these in order:

```
[assembly: ImportAsIs]
```
attribute exists in your project
```
[ProcessNode]
```
attribute on the class
Project targets
```
net8.0
```
DLL is in the correct
```
lib/net8.0/
```
path relative to
```
.vl
```
document
Project builds without errors

症状：你的C#类已存在，但在vvvv中无法找到。 修复方案：按以下顺序检查：

项目中存在
```
[assembly: ImportAsIs]
```
特性
类上标注了
```
[ProcessNode]
```
特性
项目目标框架为
```
net8.0
```
DLL位于相对于
```
.vl
```
文档的正确
```
lib/net8.0/
```
路径下
项目编译无错误

Allocations Causing Frame Drops

内存分配导致帧丢包

Symptom: GC spikes, stuttering, frame drops. Diagnosis: Allocations in the Update loop.

Common culprits:

```
new
```
keyword in Update method
LINQ operators (
```
.Where()
```
,
```
.Select()
```
,
```
.ToList()
```
)
String concatenation (
```
+
```
operator on strings)
Boxing value types (passing
```
int
```
where
```
object
```
expected)

Fix: Cache everything, pre-allocate buffers, eliminate LINQ from hot paths.

症状：GC峰值、卡顿、帧丢包。诊断：Update循环中存在内存分配操作。

常见诱因：

Update方法中使用
```
new
```
关键字
LINQ操作符（
```
.Where()
```
、
```
.Select()
```
、
```
.ToList()
```
）
字符串拼接（字符串的
```
+
```
操作符）
值类型装箱（将
```
int
```
作为
```
object
```
传递）

修复方案：缓存所有可复用对象，预分配缓冲区，从热点路径中移除LINQ操作。

Missing Change Detection

缺少变更检测

Symptom: CPU usage high even when nothing changes. Fix: Compare inputs to cached values, only recompute on change.

csharp

if (param != _lastParam)
{
    _cached = Compute(param);
    _lastParam = param;
}
result = _cached; // Always output cached

症状：即使没有任何变更，CPU使用率仍居高不下。 修复方案：将输入与缓存值进行比较，仅在发生变更时重新计算。

csharp

if (param != _lastParam)
{
    _cached = Compute(param);
    _lastParam = param;
}
result = _cached; // 始终输出缓存值

Downstream Nodes See null/default

下游节点获取null/默认值

Symptom: Connected nodes get no data, even though the node "works". Fix: Always output cached result, even when no computation happens.

csharp

// WRONG — output is only set inside the if block
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        result = Compute(input);
        _last = input;
    }
    // result is unassigned when input hasn't changed!
}

// CORRECT — always assign output
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        _cached = Compute(input);
        _last = input;
    }
    result = _cached;
}

症状：已连接的节点无法获取数据，尽管节点本身“可正常工作”。 修复方案：始终输出缓存结果，即使未执行计算。

csharp

// WRONG — 仅在if块内设置输出
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        result = Compute(input);
        _last = input;
    }
    // 当输入未变更时，result未被赋值！
}

// CORRECT — 始终为输出赋值
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        _cached = Compute(input);
        _last = input;
    }
    result = _cached;
}

SDSL Shader Issues

SDSL 着色器问题

For SDSL syntax rules, common mistakes, and correct/wrong examples, see vvvv-shaders/syntax-rules.md. Key issues:

static const

scope, missing semicolons, missing

override

, enum binding format.

关于SDSL语法规则、常见错误及正反示例，请参考vvvv-shaders/syntax-rules.md。关键问题包括：

static const

作用域、缺失分号、缺失

override

、枚举绑定格式。

Runtime Issues

运行时问题

Memory Leaks

内存泄漏

Symptom: Memory usage grows over time. Causes:

Missing
```
IDisposable
```
on nodes with native resources
COM objects (
```
ComPtr<T>
```
) not disposed
Event handler subscriptions not unsubscribed

症状：内存占用随时间增长。原因：

包含原生资源的节点未实现
```
IDisposable
```
COM对象（
```
ComPtr<T>
```
）未被释放
事件处理程序订阅未取消

Thread Safety

线程安全

Symptom: Intermittent crashes, data corruption. Fix:

Update()

runs on the main thread. Capture

SynchronizationContext

in the constructor, then marshal background results back:

csharp

private SynchronizationContext _vlSyncContext;

public MyNode()
{
    _vlSyncContext = SynchronizationContext.Current!;
}

// From background thread:
_vlSyncContext.Post(_ => { /* runs on VL thread */ }, null);

症状：间歇性崩溃、数据损坏。 修复方案：

Update()

在主线程运行。在构造函数中捕获

SynchronizationContext

，然后将后台结果封送回主线程：

csharp

private SynchronizationContext _vlSyncContext;

public MyNode()
{
    _vlSyncContext = SynchronizationContext.Current!;
}

// 从后台线程调用：
_vlSyncContext.Post(_ => { /* 在VL线程运行 */ }, null);

Circular Dependencies

循环依赖

Symptom: vvvv warns about circular dependency, patch won't compile. Fix: Insert a

FrameDelay

node to break the cycle.

症状：vvvv警告存在循环依赖，补丁无法编译。 修复方案：插入

FrameDelay

节点以打破循环。

Build Issues

构建问题

Target Framework Mismatch

目标框架不匹配

Symptom: DLL loads but types aren't found. Fix: Ensure

.csproj

targets

net8.0

(matching vvvv gamma's runtime).

症状：DLL已加载，但无法找到类型。 修复方案：确保

.csproj

的目标框架为

net8.0

（与vvvv gamma的运行时版本匹配）。

Assembly Version Conflicts

程序集版本冲突

Symptom:

FileLoadException

TypeLoadException

at runtime. Fix: Align package versions with vvvv's bundled versions. Check vvvv's

lib/

folder for reference.

For detailed error-to-solution mapping, see error-catalog.md.

症状：运行时出现

FileLoadException

或

TypeLoadException

。 修复方案：将包版本与vvvv捆绑的版本对齐。参考vvvv的

lib/

文件夹中的版本。

有关详细的错误-解决方案映射，请参考error-catalog.md。