Event Flowエディターガイド

0. 全体像をつかむ

このエディターとは？

Event Flowエディターは、Social Stream Ninjaで高度な自動処理を作るための機能です。ポップアップの簡単なスイッチに加えて、独自の振り分けロジックを記述できます。次のような場合に使用します：

• フィルターを使ってサービス間でチャットを中継します（例：コマンドを除外してTwitchからDiscordへ転送）。
• AND/OR/NOTロジックで、ロイヤルティに基づくコマンド、キーワードゲーム、抽選参加条件を作れます。
• フロー内で追加した情報に基づき、カスタムオーバーレイ、音声、OBSシーン、Webhookを起動します。
• 1つの自動処理で複数のプラットフォームを組み合わせられます（Kick、Twitch、YouTubeを1つのフローに通すなど）。

ポップアップは手軽なプリセット、Event Flowは独自のワークフローを作る道具として使えます。

すべてのフローはトリガーから始まります

アクションノード（緑）は単独では動きません。上流のトリガーノード（青）が次の値を出したときだけ実行されます： true。アクションだけをつないだフローは、有効に見えても、開始するものがないため常に待機したままです。ノード名は、そのノードが 何をするかを表し、いつ発生するかを表すものではありません： メッセージを取り上げる は、フローがそのノードに達したときにメッセージを取り上げます。ほかの場所でメッセージを取り上げても発火しません。

Flow Actionsオーバーレイ（アクション出力）

次のようなノード： 音声クリップを再生（Play Audio Clip）, メディアオーバーレイを表示（Display Media Overlay）やOBS操作には、描画用の画面が必要です。その画面は、次で提供するFlow Actionsオーバーレイページです： actions.html。配信ソフト（OBS/Streamer.botのブラウザドックなど）で動かしたままにし、Event Flowのアクションの表示先を用意してください。

読み込まれたオーバーレイは、次のことができます：

• フローをきっかけにGIPHYや直接指定したメディアURL、テキスト、紙吹雪を表示します。
• 視聴者に聞こえるよう、音声（読み上げ、音声クリップ）をローカルで再生します。
• ポップアップの「Flow Actions」セクションにあるWebSocket設定を使ってOBSを操作します（シーン切り替え、ソースの有効／無効、GDI+／FreeTypeのテキスト更新、リプレイバッファーなど）。

1. ノードを流れるもの

Event Flowの実行処理は、すべての接続線を通じて2つのものを渡します：

1. ペイロード – イベントまたはメッセージのデータオブジェクト。
2. ゲート信号 – 次の値： true/false という、次のノードを実行するかどうかを示すビット。

入力の要件

• イベントソース （Twitch Message、Timers、Manual Triggerなど）は上流の入力を無視し、独自のペイロードを作って常に次を出力します： true ノード自体でエラーが発生した場合を除きます。
• 変換ノードとロジックノード はペイロードを読み取り、フィールドの書き換え、状態の設定、ゲート信号の変更を行えます。変更先： false.
• アクションノード はゲートが次の状態のときにのみ発火します： true。アクションをつなぎ続けたい場合は、更新済みのペイロードを出力することもできます。

出力パターン

2. ロジックノード早見表

この説明では、「true/falseは何を意味するのか」というよくある疑問に答えます。

3. 小さなフローの例

A. コマンド以外のメッセージに自動返信

この例では、メッセージがコマンドの場合にRegexノードが true を出力します。 false 端子を返信につなぎます。通常のチャットには返答し、コマンドはそのまま通過させます。

B. ANDで複数の確認を必須にする

ANDノードは、正しいキーワードを使ったメンバーだけをDiscordに中継するために使います。両方の分岐がブール値の結果をANDノードに送ります。後続へ進むのは、 最初の分岐 のペイロードです。

C. NOTノードで重複アラートを防ぐ

State Check は、アラートがミュートされている場合に true を出力します。その結果を反転させることで、NOTノードはフラグが次の場合にのみお祝い演出を再生します： false.

D. 2つの音からランダムに再生

ANDゲートは必須です。 入力のないNOTは、次を出力します： true をRANDOMゲートが動作していないときにも返すため、サウンドBは次のようなすべてのチャットメッセージで再生されてしまいます： トリガーに一致しないメッセージ。 トリガーをANDの2つ目の入力に接続すると、条件に一致するメッセージでのみサウンドBが再生されます。このパターンは音声だけでなく、どちらか一方を実行するアクションの組み合わせにも使えます。

4. 反射、ループ、中継のフィードバックを防ぐ

複数の画面間でチャットを中継する機能は便利ですが、自分の出力を受信すると無限に反復する場合があります。次の対策を行ってください：

• 中継システムの重複を避けます。 同等のEvent Flow経路を使う場合は全体のRelay allを無効にし、同じチャットをつなぐ他のサービスも確認してください。独自メタデータがプラットフォームのチャットを経由しても残る保証はありません。
• DebounceまたはCooldownノードを使用する と、X秒に1回だけ発火するアラートを作れます。
• 循環は意図的に断ち切ります。 2つの分岐が互いに送り合う場合は、状態変数（「currentlyRelaying」）を確認するロジックノードを追加し、そのフラグが立っているときにフローを早期終了させます。

5. 入力、出力、実用上の質問

よくある質問と回答

• 2つのフィルターを組み合わせるたびにANDが必要ですか？ いいえ。多くのノードに複数の判定が含まれています（例えば基本のMessage Filterはキーワード＋役割に対応しています）。ANDは高度な条件の組み合わせや、異なるノードからの信号をまとめる場合にのみ使用してください。
• true/falseの値はどのようにNOTノードに届きますか？ 緑の出力を持つノードは、次を出力します： true が既定です。条件を満たさない場合は、次を出力します： false。その線をNOTにつなぐと結果を反転できます。
• falseを返してもペイロードを出力できますか？ はい。ペイロードはfalse出力にも流れます。その分岐をどこへ接続するかは自分で決められます。
• TikTokのチームメンバーを判定するには？ 選ぶ項目： TikTokチームメンバー をUser Roleノードで選択します。受信メッセージのTikTokファンクラブ／チームのレベルやバッジを認識し、Main Chat Overlayの設定には依存しません。
• Speak Textノードごとに別の音声を使えますか？ はい。プロバイダーが対応する音声名またはIDを、次に入力します： 音声の上書き（Voice Override）を指定するか、空欄にしてFlow Actionsの標準TTSを使います。

6. テンプレート変数のリファレンス

いくつかのアクションノード（Show Text、Set Text Source、Send Message、Relay Chat、TTS Speak、Call Webhook、Print Thermal Label）は、次に対応しています： テンプレート変数 は実行時にイベントデータに置き換えられます。変数名は次のように波括弧で囲みます： {username}.

基本変数（後方互換）

拡張変数

テンプレート例

• テキストを表示（Show Text）： {username} just cheered {hasDonation}!
• OBSテキストソースを設定： {username}: now {counterValue}, need {counterTarget}
• Relay Chat： [{source}] {username}: {message}
• TTS： {username} says {message}
• 寄付アラート： {username} donated {donation} - {subtitle}
• 感熱ラベル： {username}、改行、次の値を入力します： {donation}。参照先： 感熱プリンターガイド で、プリンター設定、固定サイズのラベル、完成したフローを確認できます。
• DiscordのCall Webhook： {"content":"{message}","username":"{username}","avatar_url":"{chatimg}"}

7. 実用上の確認事項

• 名前と色 ノードに名前と色を付けると、後で各分岐を見分けられます。
• 内蔵シミュレーターでテストする （Send Test Event）で確認してから、本番でフローを有効にしてください。
• ソースの近くにロジックをまとめます。 後続の不要な処理を避けるため、できるだけ早い段階でフィルターを適用します。
• 繰り返し使う情報は状態ノードに保存します。 カウンター、切り替え状態、タイムスタンプを使ってアラートの重複を防ぎます。
• metaフィールドを記録します。 カスタムの値を追加した場合： meta キーを追加した場合は、オーバーレイやリモートクライアントとの整合性を保つために記録してください。

8. さらに詳しく

Stream DeckまたはAPIからカスタムワークフローを実行する：名前付きトリガー、開始用テンプレート、ワークフローの検出、追加データ、HTTP/WebSocket/P2Pの例、ダイヤル操作。

さらに詳しく知りたいですか？

• 使う項目： 状態ノード （カウンター、スイッチ、タイマー）で、イベント間の文脈を保持します。
• 組み合わせるもの： 変数とロジック で、順番待ちシステム、抽選、スコア計算を作れます。
• 次に接続します： ポイントと報酬 の仕組みを使うと、視聴者が意図的にフローを起動できます。
• 使用中のアプリは SSAppデスクトップアプリですか？ ロック解除 カスタムJavaScriptノード で、組み込みノードにはない任意のロジックを記述できます。
• 次を確認してください： イベントリファレンス に、すべてのプラットフォームのペイロードが詳しく記載されています。

このガイドは単独でも使えるように作成されています。ローカルにコピーしてチーム用に調整し、エディターでさまざまな方法を試してください。

9. カスタムJavaScript SSApp／デスクトップ版のみ

Event Flowエディターでは、2種類のノードで任意のJavaScriptを記述し、フローの処理中に実行できます： カスタムコード（Custom Code） （トリガー）と カスタムコードを実行（Execute Custom Code） （アクション）。組み込みノードで表現できない処理を実現するための手段です。

Custom Code — トリガーノード

ドラッグする項目： カスタムコード（Custom Code） の送信元： 高度な機能 グループ。場所： トリガー パネルからキャンバスに配置します。ゲートとして働き、コードが次を返した場合にのみフローを続行します： true.

Execute Custom Code — アクションノード

ドラッグする項目： カスタムコードを実行（Execute Custom Code） の送信元： 連携（Integrations） グループ。場所： アクション パネル内。メッセージの変更、ブロック、後続ノードが読み取れるメタデータの追加ができます。

オブジェクト： message

両ノードは完全なイベントペイロードを次として受け取ります： message。以下のフィールドは常に利用でき、プラットフォーム固有イベントでは追加フィールドがある場合があります。

アクションが返すもの

アクションコードからプレーンなオブジェクトを返します。含めたフィールドは、フローの次の部分にマージされます： result オブジェクト。省略したフィールドは現在の値を維持します。

スニペット例

対応するノードのJavaScript Code欄へ、いずれかの例をコピーしてください。

トリガーのスニペット — 戻り値： true でフローを続行します

アクションのコード例 — 返す値： { modified, message }

完全な例 — VIP向け機能追加リクエストボット

このフローは次を待ち受けます： !feature <text> をサブスクライバー、VIP、モデレーターから受信し、機能追加リクエストの形式に整えて別の送信先（Discordなど）に中継します。

手順1 — Custom Codeトリガー （トリガーのJavaScript Code欄に貼り付けます）：

手順2 — Execute Custom Codeアクション （アクションのJavaScript Code欄に貼り付けます）：

手順3 — Relay Chatアクション：アクションの後に標準のRelay Chatノードを置き、Discordなどの送信先を指定してください。ここでは独自コードは不要です。整形済みの message.chatmessage は自動的に通過します。

セキュリティ上の考慮事項

• ネットワークのサンドボックスはありません。 アクションコードから次を呼び出せます： fetch()。他の人が共有したフローを使う場合は、有効にする前にJavaScriptを確認してください。
• エラーは捕捉されます。 コードの実行時エラーでは、次を返します： false （トリガー）または何もしない動作（アクション）となり、DevToolsコンソールへ記録されます。フローはクラッシュしません。
• 構文エラーも捕捉されます。 コンパイル時の SyntaxError も同様に捕捉されます。ノードが何もしていないように見える場合は、DevTools（F12）を確認してください。