IRC-kosmi-relay/docs/IRC.md

# IRC Command Reference

This document covers everything available to IRC users when interacting with the Kosmi-IRC relay bot. All commands and vote syntax work in any channel the bot is present in.

## Commands

Commands are typed as regular messages in IRC. They are **not** relayed to other bridges -- the bot consumes them and acts on them directly.

There is no permission system; any user in the channel can issue any command.

### `!kreconnect`

Force-reconnect the Kosmi bridge. Useful if the Kosmi WebSocket has silently dropped.

**Response:** `Reconnecting Kosmi...` (sent to the channel immediately)

The reconnection happens asynchronously. If it fails, errors appear only in the bot's logs.

### `!jreconnect`

Force-reconnect the Jackbox Game Picker WebSocket. Only meaningful if the Jackbox integration is enabled.

**Response:** `Reconnecting Jackbox...`

### `!reconnect`

Reconnect all non-IRC services (Kosmi and Jackbox) at once.

**Response:** `Reconnecting all services...`

### `!votes`

Query the current vote tally for the game being played right now in the active Jackbox session.

**Response** (broadcast to all bridges -- IRC, Kosmi, etc.):

```
🗳️ Fibbage 4 • Today: 5👍 2👎 (Score: 3) • All-time: 46👍 3👎 (Score: 43)
```

**Requirements:**
- Jackbox integration must be enabled
- An active Jackbox session must exist
- A game must currently have status "playing" in that session

If any of these conditions are not met, the command is silently consumed (errors appear only in bot logs).

---

## Voting

Vote detection runs automatically on every non-relayed message. Votes are sent to the Jackbox Game Picker API when the integration is enabled and a session is active.

### Current Game Votes

Type anywhere in a message:

| Syntax | Effect |
|--------|--------|
| `thisgame++` | Upvote the currently playing game |
| `thisgame--` | Downvote the currently playing game |

- Case-insensitive (`ThisGame++`, `THISGAME++`, etc. all work)
- Can appear anywhere in the message text
- The message is still relayed to other bridges as normal chat

### Ticker Symbol Votes

Vote on a specific game by its ticker symbol:

| Syntax | Effect |
|--------|--------|
| `SYMBOL++` | Upvote the game identified by SYMBOL |
| `SYMBOL--` | Downvote the game identified by SYMBOL |

- Symbols are 2-4 alphanumeric characters
- Case-insensitive (`qpl3++` and `QPL3++` are equivalent)
- The symbol must exist in the ticker table below
- The message is still relayed to other bridges as normal chat

### Ticker Symbol Table

| Symbol | Game |
|--------|------|
| `BC` | Bomb Corp. |
| `BDTS` | Bidiots |
| `BR` | Blather 'Round |
| `BRKT` | Bracketeering |
| `CH` | Cookie Haus |
| `CU` | Champ'd Up |
| `CVDL` | Civic Doodle |
| `DD` | Dirty Drawful |
| `DCTN` | Dictionarium |
| `DOOM` | Doominate |
| `DRM` | Dodo Re Mi |
| `DRWA` | Drawful Animate |
| `DRWF` | Drawful |
| `EW` | Earwax |
| `FANL` | Fakin' It All Night Long |
| `FBG2` | Fibbage 2 |
| `FBG3` | Fibbage 3 |
| `FBG4` | Fibbage 4 |
| `FBXL` | Fibbage XL |
| `FI` | Fakin' It! |
| `FT` | Fixy Text |
| `GSPN` | Guesspionage |
| `HPNT` | Hypnotorious |
| `HRSY` | Hear Say |
| `JB` | Joke Boat |
| `JJ` | Job Job |
| `JNKT` | Junktopia |
| `LMF` | Let Me Finish |
| `LOT` | Legends of Trivia |
| `LS` | Lie Swatter |
| `MSM` | Monster Seeking Monster |
| `MVC` | Mad Verse City |
| `NNSR` | Nonsensory |
| `PS` | Patently Stupid |
| `PTB` | Push the Button |
| `QLXL` | Quiplash XL |
| `QPL2` | Quiplash 2 |
| `QPL3` | Quiplash 3 |
| `QXRT` | Quixort |
| `RM` | Role Models |
| `ROOM` | Roomerang |
| `SS` | Survey Scramble |
| `SPCT` | Suspectives |
| `STI` | Survive the Internet |
| `STR` | Split the Room |
| `TJ` | Time Jinx |
| `TKO2` | Tee K.O. 2 |
| `TKOX` | Tee K.O. T-Shirt Knock Out |
| `TMP1` | Trivia Murder Party |
| `TMP2` | Trivia Murder Party 2 |
| `TMP3` | Trivia Murder Party 3 |
| `TP` | Talking Points |
| `TPM` | The Poll Mine |
| `TWEP` | The Wheel of Enormous Proportions |
| `WD` | Weapons Drawn |
| `WS` | Word Spud |
| `YDK1` | You Don't Know Jack 2015 |
| `YDKJ` | You Don't Know Jack Full Stream |
| `ZPDM` | Zeeple Dome |

---

## Behavior Notes

### Loop Prevention

Messages that begin with `[irc]` or `[kosmi]` (case-insensitive) are treated as relayed from another bridge. Vote detection is skipped for these messages to prevent duplicate votes when the same text passes through multiple bridges.

### Command vs. Vote Processing Order

1. Vote detection runs first (on all non-relayed messages)
2. `!` commands are checked next
3. If the message is a `!` command, it is consumed and **not** relayed
4. If the message is not a command, it is relayed to other bridges

This means a vote phrase in a normal message (like "nice game thisgame++") both registers the vote and gets relayed. But `!votes` only triggers the votes query -- it is not relayed.

### What IRC Users See from Other Bridges

| Source | Format |
|--------|--------|
| Kosmi user message | `[kosmi] <username> message text` |
| Jackbox game announcement | System message (e.g. `🎮 Coming up next: Fibbage 4!`) |
| Jackbox room code | System message with room code (may include image link) |
| `!votes` result | `🗳️ Title • Today: X👍 Y👎 (Score: Z) • All-time: X👍 Y👎 (Score: Z)` |
| Reconnect confirmation | Plain text from "system" (e.g. `Reconnecting Kosmi...`) |

The `[kosmi]` prefix format is configurable via `RemoteNickFormat` in `matterbridge.toml`.

### Requirements for Jackbox Features

All Jackbox-related functionality (votes, `!votes`, game announcements, room codes) requires:

1. `[jackbox]` section in config with `Enabled=true`
2. Valid `APIURL` and `AdminPassword`
3. An active Jackbox session on the API
4. A game currently being played (for `!votes` and vote detection)

When the Jackbox integration is disabled or no session is active, vote syntax is ignored and `!votes` produces no output.