## 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.