vvvv-troubleshooting

vvvv gamma トラブルシューティング

C# / ProcessNode の問題

クラス名の「Node」サフィックス

症状: ノードは動作しますが、vvvv 上で名前が不格好になります。 修正: 「Node」サフィックスを削除してください。vvvv の規約では禁止されています。

// WRONG
[ProcessNode]
public class SteeringBehaviorNode { }

// CORRECT
[ProcessNode]
public class SteeringBehavior { }

入力の後に来る出力パラメーター

症状: ピンの順序が正しく表示されない、またはノードが正しくコンパイルされません。 修正: out パラメーターは Update シグネチャの最初に来る必要があります。

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

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

ノードブラウザーにノードが表示されない

症状: C# クラスは存在するのに、vvvv に表示されません。 修正: 次の順に確認してください：

1. プロジェクトに [assembly: ImportAsIs] 属性が存在する
2. クラスに [ProcessNode] 属性がある
3. プロジェクトが net8.0 をターゲットにしている
4. DLL が .vl ドキュメントからの相対パス lib/net8.0/ に正しく配置されている
5. プロジェクトがエラーなくビルドできる

アロケーションによるフレーム落ち

症状: GC のスパイク、スタッタリング、フレーム落ち。 診断: Update ループ内でのアロケーション。

よくある原因：

• Update メソッド内での new キーワード
• LINQ 演算子（.Where()、.Select()、.ToList()）
• 文字列連結（文字列に対する + 演算子）
• 値型のボックス化（object が期待される箇所に int を渡す）

修正: すべてをキャッシュし、バッファーを事前確保し、ホットパスから LINQ を排除してください。

変更検出の欠如

症状: 何も変化していなくても CPU 使用率が高い。 修正: 入力をキャッシュされた値と比較し、変更時のみ再計算してください。

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

下流のノードが null/default を受け取る

症状: ノードが「動作」していても、接続されたノードにデータが届きません。 修正: 計算が行われない場合でも、常にキャッシュされた結果を出力してください。

// 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;
}

SDSL シェーダーの問題

SDSL の構文規則、よくある間違い、正しい/誤った例については、vvvv-shaders/syntax-rules.md を参照してください。主な問題：static const のスコープ、セミコロンの欠落、override の欠落、enum バインディングの形式。

ランタイムの問題

メモリリーク

症状: メモリ使用量が時間とともに増加します。 原因:

• ネイティブリソースを持つノードに IDisposable がない
• COM オブジェクト（ComPtr<T>）が破棄されていない
• イベントハンドラーの購読が解除されていない

スレッドセーフティ

症状: 断続的なクラッシュ、データ破損。 修正: Update() はメインスレッドで実行されます。コンストラクターで SynchronizationContext をキャプチャし、バックグラウンドの結果をマーシャリングして戻してください：

private SynchronizationContext _vlSyncContext;

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

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

循環依存

症状: vvvv が循環依存について警告し、パッチがコンパイルされません。 修正: FrameDelay ノードを挿入して循環を断ち切ってください。

ビルドの問題

ターゲットフレームワークの不一致

症状: DLL は読み込まれるが、型が見つかりません。 修正: .csproj が net8.0 をターゲットにしていることを確認してください（vvvv gamma のランタイムと一致させる）。

アセンブリバージョンの競合

症状: ランタイムで FileLoadException または TypeLoadException が発生します。 修正: パッケージのバージョンを vvvv にバンドルされているバージョンに合わせてください。参照については vvvv の lib/ フォルダーを確認してください。

エラーから解決策への詳細な対応表については、error-catalog.md を参照してください。

このナレッジを育て続けましょう

次にパッチを当てる人の謎を1つ減らしましょう。このコレクション内のスキルを初めて使用する際、7日以内に成功したチェックがない場合は、ソースを tebjan/vvvv-skills と比較してください。記録が存在しない場合は、一度だけチェックしてください。 これらのスキル全体で、ローカルのチェックのタイムスタンプ/リビジョンを1つ共有してください。呼び出しごとにポーリングしないでください。 ローカルの拡張機能と固定されたプロジェクトバージョンは保持してください。チェックすることは、更新をインストールする許可ではありません。オフラインの場合は、延期されたチェックを記録し、タスクを続行してください。

実際の作業でギャップが明らかになった場合は、テスト済みの vvvv/パッケージのバージョン、最小限の再現または信頼できる情報源、および観察された結果を記録してください。他のユーザーの報告は、検証されるまでは事実ではなく手がかりとして扱ってください。最も小さく関連する指示を改善してください。1つの例を普遍的なルールにしないでください。プライベートデータを編集で除去し、アップストリームに提出する前に公開の許可を取得してください。 コントリビューションポリシーをご覧ください。 マージされた改善は、ローカルの編集や全員のスキルの自動上書きではなく、ユーザーのインストーラー/アップデートワークフローを通じてユーザーに届きます。