# Streamer.bot Integration — Square Race

Custom events let you trigger race actions from Streamer.bot actions, hotkeys, or rewards.

## Custom events

| Event name | Effect |
|------------|--------|
| `SquareRace.Start` | Same as **Start Race** in the control panel |
| `SquareRace.TriggerBorder` | Starts the shrinking border immediately |
| `SquareRace.Reset` | Resets race / clears for a new round |

## Setup

1. Ensure Streamer.bot is running and the control panel **Streamer.bot Connection** matches your WebSocket settings (default `127.0.0.1:8080`).
2. In Streamer.bot, create a **Custom Event** action (or sub-action) that fires one of the event names above.
3. The control panel must be open (or the overlay connected to the same WebSocket) to receive events.

### Example: chat command `!startrace`

1. **Triggers → Command** — command `startrace`, permission Mods.
2. **Action → Core → Custom Event** — Event Name: `SquareRace.Start`.

### Example: channel point reward

1. Create a Channel Point reward.
2. Action chain: **Custom Event** → `SquareRace.TriggerBorder`.

## Twitch chat via Streamer.bot

Set **Chat Source** to **Streamer.bot** or **Auto** in the control panel. Join messages are read from `Twitch.ChatMessage` — no separate bot account required for read-only joins.

## Notes

- Custom events are handled in the control panel JavaScript when connected via WebSocket.
- For OBS-only setups, race state still syncs through **localStorage** when you use the control panel buttons.
- Password: if your Streamer.bot WebSocket requires a password, enter it in the control panel (stored in localStorage).