Event Flow System

State Nodes Playbook

State nodes give Social Stream Ninja memory. Use them to build cooldowns, toggles, counters, and throttles that keep automations predictable. This guide breaks the topic into focused mini-guides with examples and troubleshooting tips.

01 · Quick Orientation

Every State node has two halves:

State Node

  • Lives on the canvas.
  • Holds the value (ON/OFF, count, timestamps).
  • Runs for every message that enters the node.

State Action

  • Placed downstream.
  • Changes the stored value (set ON, add +1, reset, etc.).
  • Can live anywhere in the flow—just pick the matching node name.
Remember: Add the State node first, give it a unique name, then wire the matching action node. Without the base node, Set/Increment/Reset actions have nothing to talk to.

02 · On/Off Switch (Gate)

The switch is a boolean guard. When ON, messages pass through; when OFF, the flow halts at this node.

Best for

  • Cooldowns for chat commands.
  • Manual toggles (enable/disable overlays).
  • Maintenance windows (pause features during BRB scenes).

Key Actions

  • Set Gate State — flip ON or OFF.
  • Reset State Node — revert to default (usually ON).

Example: 15s Cooldown

!hello ──▶ Switch (ON?) ─▶ Send Reply ─▶ Set Gate: OFF ─▶ Delay 15s ─▶ Set Gate: ON

Build Steps

  1. Drop the switch node, name it “helloCooldown”, default ON.
  2. Connect your trigger → switch → actions.
  3. After your action, add Set Gate State (OFF) referencing “helloCooldown”.
  4. Add a Delay node (15 seconds).
  5. Add another Set Gate State (ON) for “helloCooldown”.

03 · Counter

Counters track numbers across messages. They increment automatically when a message flows through, and you can adjust values manually with actions.

Auto increment: Every time a payload passes through the Counter node it adds 1 (unless you pause it with the “Only count when gate is true” option).

Use Cases

  • Every Nth chatter triggers a prize.
  • Track progress to a community goal.
  • Store points redeemed via commands.

Actions

  • Increment Counter — add or subtract custom amounts.
  • Set Counter Value — jump to a specific number.
  • Reset State Node — revert to the default start value.

Example: Celebrate Every 5 Messages

Any Message ─▶ Counter (name: hype5) ─▶ Condition (value % 5 === 0?) ─▶ Play Celebration

Inside the Condition node, compare state.hype5.value or simply use the built-in “Trigger when value matches Target” option from the Counter node’s properties.

04 · Rate Limiter (Throttle)

The throttle remembers timestamps and refuses new events until the rate you specify is respected.

Great When You Need

  • “Only five raffle entries per minute.”
  • “One API call per 10 seconds.”
  • “Drop alerts if the overlay is already busy.”

Configuration

  • Set the maximum events allowed.
  • Choose the time window (seconds).
  • Decide whether to queue or discard overflow.
Heads up: Throttles do not auto-reset when you edit the flow. Use Reset State Node if you need a clean slate during testing.

05 · Problem Kits

Pick a scenario and follow the steps.

Command Cooldown

  1. Switch node named “commandCooldown”.
  2. Trigger → switch → reply.
  3. Set Gate OFF → Delay → Set Gate ON.
  4. Add a chat message “Cooldown active” on the false output if desired.

Limited Freebies

  1. Counter default 0, target 3.
  2. Increment after each redemption.
  3. When value ≥ 3, branch to “Sorry, all gone”.
  4. Use Reset action at the end of stream.

Viewer Toggle

  1. Switch named “overlayToggle”.
  2. !overlay on command → Set Gate ON.
  3. !overlay off command → Set Gate OFF.
  4. All overlay triggers pass through the switch.

Example Flow Charts

Trigger ─▶ Switch (overlayToggle) ─▶ If ON → Show Overlay └─false─▶ Notify moderator “Overlay disabled”
Redeem Reward ─▶ Counter ticketsSold ├─value < 50 ─▶ Approve Redemption └─value ≥ 50 ─▶ Deny + Refund points

06 · Troubleshooting & FAQ

Symptom Likely Cause Fix
Set Gate State action won’t save. No matching switch node exists (or the names differ). Add the switch node first and confirm the dropdown references it.
Counter never increments. The flow bypasses the counter node or the gate is false. Make sure the trigger wire passes through the counter and the gate output is true.
Throttle blocks everything forever. Window too strict or leftover state from testing. Relax the limit and drop a Reset State Node action before retesting.
Guide buttons don’t open. Running inside the extension without web_accessible resources updated. Ensure actions/state-nodes-guide.html ships via manifest and reload the extension.

Testing Checklist

  • Use the Event Flow “Send Test Event” tool to simulate commands.
  • Temporarily shorten cooldowns (2 seconds) or lower counter targets while verifying.
  • Reset state nodes between tests so you are not reading stale data.
  • Label branches (e.g., “false → cooldown active”) so you can follow the path visually.

07 · Next Steps

Combine state nodes with the rest of the Event Flow toolkit:

  • Use logic gates (AND/OR/NOT) before a switch to decide who can toggle it.
  • Store state-driven metadata under meta so overlays know why a branch fired.
  • Export working patterns as templates so your team can re-import them later.
Keep experimenting! The new Event Flow Guide pairs with this playbook so you can master both logic and state layers.