# Streamer.bot Integration Guide

The Ultimate Pokedex overlay listens for **Custom Events** from Streamer.bot over WebSocket. Use these to trigger lookups from channel points, hotkeys, OBS scene changes, or any Streamer.bot action — without relying on chat commands.

## Prerequisites

1. Enable **WebSocket Server** in Streamer.bot (Settings → Servers/Clients → WebSocket Server).
2. Add the overlay URL from `index.html` as an OBS Browser Source.
3. Configure the overlay's Streamer.bot address/port in the customizer (password saved in localStorage).

## Custom Events

Trigger these with the **Trigger Custom Event** sub-action in Streamer.bot.

| Event Name | Purpose | Args (optional) |
|------------|---------|-----------------|
| `Pokedex.Lookup` | Look up a Pokémon | `query` or `pokemon` or `name` — name or national dex ID |
| `Pokedex.Show` | Show the overlay (re-show after auto-hide) | none |
| `Pokedex.Hide` | Hide the overlay immediately | none |
| `Pokedex.Next` | Next Pokémon in national dex | none |
| `Pokedex.Prev` | Previous Pokémon | none |
| `Pokedex.Random` | Random Pokémon | none |

### Args for `Pokedex.Lookup`

When **Use Args** is enabled on the Custom Event trigger, pass JSON args:

```json
{
  "query": "pikachu"
}
```

In Streamer.bot sub-actions, you can use variables:

- `%rawInput%` — from a custom command
- `%argument%` — first command argument
- `%rewardTitle%` — channel point reward title

## Example Actions

### 1. Hotkey — Random Pokémon

**Trigger:** Hotkey (e.g. F9)

**Sub-actions:**
1. Core → Triggers → **Trigger Custom Event**
   - Event Name: `Pokedex.Random`
   - Use Args: off

### 2. Custom Command — Lookup

**Trigger:** Command `!dex` with argument

**Sub-actions:**
1. Core → Triggers → **Trigger Custom Event**
   - Event Name: `Pokedex.Lookup`
   - Use Args: **on**
   - Args (JSON): `{ "query": "%rawInput%" }`

Or map a fixed Pokémon for testing:

```json
{ "query": "charizard" }
```

### 3. Channel Point Reward — Show Pikachu

**Trigger:** Twitch → Channel Reward → Redemption (filter reward title)

**Sub-actions:**
1. Core → Triggers → **Trigger Custom Event**
   - Event Name: `Pokedex.Lookup`
   - Use Args: on
   - Args: `{ "query": "25" }`

### 4. OBS Scene Change — Hide Overlay

**Trigger:** OBS → Scene Changed (to your "Starting Soon" scene)

**Sub-actions:**
1. Core → Triggers → **Trigger Custom Event**
   - Event Name: `Pokedex.Hide`

### 5. Stream Start — Show Default

**Trigger:** Twitch → Stream Online

**Sub-actions:**
1. Core → Triggers → **Trigger Custom Event**
   - Event Name: `Pokedex.Show`

## Chat Commands (built-in)

The overlay also parses Twitch chat when connected. Default command word: `pokedex`.

| Command | Action |
|---------|--------|
| `!pokedex <name\|id>` | Look up Pokémon |
| `!pokedex random` | Random Pokémon |
| `!pokedex next` / `prev` | Navigate dex |
| `!pokedex hide` / `show` | Hide or show overlay |
| `!pokedex shiny` | Force shiny sprite |
| `!pokedex` | Re-show current (or random if none) |

Configure permissions and command word in the customizer (`index.html`).

## Troubleshooting

- **Overlay not responding:** Check the connection indicator (unless hidden). Verify WebSocket is enabled and address/port match.
- **Custom Event not firing:** Event names are case-sensitive. Must be exactly `Pokedex.Lookup`, etc.
- **Args not working:** Enable **Use Args** on the Trigger Custom Event sub-action and pass valid JSON.
- **Password required:** Set password in customizer; it is stored in localStorage (not in the overlay URL by default).

See the main [README.md](../README.md) for OBS setup and overlay URL configuration.