110 lines
5.2 KiB
Markdown
110 lines
5.2 KiB
Markdown
# Twitch setup
|
|
|
|
This guide connects the Twungeon proof of concept to a Twitch development
|
|
channel. Never commit real values: copy `.env.example` to an ignored `.env` or
|
|
provide the variables through your process manager.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 22 or newer and npm.
|
|
- A Twitch developer application and a development channel.
|
|
- A Twitch Extension with identity sharing enabled. Twungeon requires the
|
|
numeric `user_id`; anonymous or opaque-only viewers fail closed.
|
|
- A broadcaster user access token that can read chat and check followers.
|
|
- The Extension shared secret, copied exactly as the base64 value supplied by
|
|
the Extension Manager.
|
|
|
|
The installed Twurple packages are locked in `package-lock.json`. Re-check
|
|
their release documentation and Twitch's current scope requirements before
|
|
rotating tokens or upgrading packages.
|
|
|
|
## Required environment
|
|
|
|
Set `TWITCH_ENABLED=true`, then provide:
|
|
|
|
| Variable | Purpose |
|
|
| --- | --- |
|
|
| `TWITCH_CLIENT_ID` | Developer application/Extension client ID |
|
|
| `TWITCH_CLIENT_SECRET` | Server-only application secret |
|
|
| `TWITCH_BROADCASTER_ID` | Numeric channel owner ID |
|
|
| `TWITCH_CHANNEL_LOGIN` | Channel login joined by Twurple chat |
|
|
| `TWITCH_BOT_ACCESS_TOKEN` | Broadcaster user access token |
|
|
| `TWITCH_EXTENSION_SECRET` | Base64 Extension shared secret |
|
|
| `CHANNEL_POINTS_RESURRECTION_REWARD_ID` | Stable ID of the resurrection custom reward |
|
|
| `PUBLIC_BASE_URL` | Public HTTPS backend origin |
|
|
|
|
The user token currently needs `chat:read`, `moderator:read:followers`, and
|
|
`channel:read:redemptions`. The follower and Channel Points subscriptions use
|
|
the broadcaster token, so its subject must match `TWITCH_BROADCASTER_ID`.
|
|
Twungeon subscribes only to the configured custom reward and uses Twitch's
|
|
stable redemption ID as the deduplication key. The broadcaster owns the reward
|
|
cost in Twitch; the backend does not duplicate it.
|
|
|
|
## Extension configuration
|
|
|
|
1. Host the built static files and backend at an HTTPS origin allowed by the
|
|
Extension configuration. Twitch embeds the UI in an iframe and supplies the
|
|
Extension Helper JWT through `onAuthorized`.
|
|
2. Point the viewer/mobile video component to the application root.
|
|
3. Enable identity sharing. A JWT without `user_id`, with the wrong
|
|
`channel_id`, an expired signature, or an `external` role is rejected.
|
|
4. Keep the Extension secret only in the backend environment. It must never be
|
|
included in the UI bundle or URL.
|
|
5. Start with `npm run build && npm start`. Confirm `/health` returns `ready:
|
|
true` and `twitchMode: "configured"` after chat connects.
|
|
|
|
The Extension JWT is exchanged for a random 15-minute Twungeon session. A
|
|
refresh obtains a new Twitch JWT, re-verifies it, and restores the existing
|
|
character; it does not create a player.
|
|
|
|
## Channel Points reward
|
|
|
|
1. In the broadcaster dashboard, create one custom reward for resurrection.
|
|
2. Choose its title and cost in Twitch. Disable viewer text input unless the
|
|
channel has a separate moderation reason to keep it.
|
|
3. Enable **Skip Reward Requests Queue** because Twungeon consumes the
|
|
redemption immediately and uses read-only EventSub access rather than
|
|
managing fulfillment status.
|
|
4. Retrieve the reward's stable ID through the Twitch API or Twitch CLI using
|
|
the broadcaster token, and set it as
|
|
`CHANNEL_POINTS_RESURRECTION_REWARD_ID`.
|
|
5. Do not reuse that reward for another action. Redemptions of every other
|
|
reward are ignored by the domain.
|
|
|
|
Bits, Cheers, and Bits-in-Extensions products are outside the MVP and have no
|
|
gameplay handler.
|
|
|
|
## Event flow
|
|
|
|
1. A follower types `!spawn` in chat.
|
|
2. Twurple supplies the stable chatter ID; the API checks that ID against the
|
|
broadcaster's followers.
|
|
3. The Extension sends its current Twitch JWT to
|
|
`POST /api/extension/session`.
|
|
4. The backend verifies signature, expiry, channel, role, and numeric user ID.
|
|
5. Controls enable only when the verified ID equals the chat-spawn owner ID.
|
|
6. A redemption of the configured Channel Points reward by the dead player
|
|
invokes resurrection exactly once.
|
|
|
|
## Troubleshooting and rotation
|
|
|
|
- **Chat disconnected:** check token validity, `chat:read`, channel login, and
|
|
outbound WebSocket access. Existing game state continues; new Twitch inputs
|
|
fail closed until reconnect.
|
|
- **Follower rejected:** ensure the token belongs to the broadcaster and has
|
|
`moderator:read:followers`; confirm the numeric broadcaster ID.
|
|
- **Extension returns `UNAUTHENTICATED`:** check the base64 secret, JWT expiry,
|
|
allowed channel, and identity-sharing capability. Never log the JWT.
|
|
- **`IDENTITY_NOT_BOUND`:** compare the chat and verified Extension numeric IDs;
|
|
display names are deliberately ignored for ownership.
|
|
- **Reward does not resurrect:** confirm the configured reward ID, the
|
|
`channel:read:redemptions` scope, the dead character owner ID, and that the
|
|
redemption was not already processed.
|
|
- **Public iframe fails:** confirm TLS, allowed origins, Extension asset paths,
|
|
and that WebSocket traffic reaches `/ws`.
|
|
|
|
To rotate credentials, stop new Twitch intake, replace the server environment,
|
|
restart, verify `/health`, test one follower check and Extension login, then
|
|
revoke the old token/secret. A full process restart creates a new in-memory run,
|
|
as required by the MVP persistence boundary.
|