Grim Games Live Grim Games Live

GRiMbot documentation

Setup for a Twitch stream

This is the hosted copy of the GRiMbot technical manual. Use the table of contents to open any page in the manual.

GRiMbot product page Manual home

Setup for a Twitch stream

Purpose and scope

This runbook takes a packaged GRiMbot Core installation through Twitch authorization, chat verification, and the first OBS overlay. Use it before installing optional plugins or Chat Game packs.

Prerequisites

  • The items on What you need have been prepared.
  • GRiMbot Core has been downloaded for the correct operating system and architecture.
  • OBS Studio 28 or newer is installed if the stream will use overlays.
  • The broadcaster can access the Twitch Developer Console and authorize the channel.
  • Twitch two-factor authentication is enabled for the account that will manage the Twitch application.
  • A separate Twitch bot account is available if Chat Messages should use a bot name.

Procedure

1. Install and start Core

  1. Complete Install on Windows or Install on Linux.
  2. Before the first login, set unique ADMIN_USERNAME and ADMIN_PASSWORD values in the local .env file as directed by the installation page.
  3. Start GRiMbot.
  4. Open http://127.0.0.1:8000/admin in a browser on the GRiMbot machine.
  5. Sign in with the GRiMbOS credentials set in .env.

[!IMPORTANT] Packaged launchers bind to 127.0.0.1. The current packaged release supports the local machine layout only. It does not supply a supported network deployment for a two-PC layout.

Core includes the bot process, API, GRiMbOS, media functions, overlays, and core Twitch functions. Optional plugins and Chat Game packs are separate packages.

2. Complete SETUP BOT

  1. Open System → SETUP BOT.
  2. Complete Twitch App and click Save configuration.
  3. If the GRiMbOS username or password changed, sign out and sign in with the new values.
  4. Complete the required broadcaster authorization on Sign-In.
  5. Authorize the optional bot account if required.
  6. Open Progress and click Refresh.
  7. Confirm that Twitch events arrive over shows websocket. Packaged local installations restart WebSocket EventSub automatically after authorization.
  8. Confirm that the status line says Setup is complete.
  9. Select the broadcaster's local Bot Timezone and click Save.
  10. Verify Bot Timezone and the non-default GRiMbOS password separately. Setup is complete. does not include either check.
  11. Trigger a real Twitch EventSub event that is safe for the channel.
  12. Confirm that GRiMbot receives and processes the event.

Follow SETUP BOT for the complete Developer Console and callback procedure.

3. Check core connections

  1. Open System → Connection Status.
  2. Confirm that the broadcaster account is authorized.
  3. Confirm that the expected Chat Message identity is authorized and joined to the channel.
  4. Use Fix… on any failed Twitch row.
  5. Ignore an overlay connection failure until an OBS Browser Source has been added.

4. Create the first overlay

  1. Open Overlays → Browser & Chat → Overlay Browser.
  2. Create an overlay.
  3. Set its canvas width and height to the OBS output size.
  4. Open Layout.
  5. Add one object, such as Vertical Chat Box or Event Alerts.
  6. Save the layout.
  7. Click Copy URL.
  8. In OBS, add a Browser Source.
  9. Paste the copied URL.
  10. Set the Browser Source width and height to the overlay canvas.
  11. Enable Control audio via OBS.
  12. Place the source in the intended scene.
flowchart LR
    Twitch[Twitch events and chat] <--> Core[GRiMbot Core]
    Core --> URL[Overlay URL]
    URL --> Source[OBS Browser Source]
    Source --> Program[OBS program output]

5. Verify Chat Messages

  1. Open the Twitch channel chat.
  2. Send !ping from an account permitted to use the command.
  3. Confirm that GRiMbot replies.
  4. Open System → Core Commands.
  5. Review the permissions for commands that can affect other users or the stream.
  6. Keep moderator-only permissions unless the stream requires a documented change.

6. Test media and Event Alerts

  1. Add one media file through the GRiMbOS media tools.
  2. Test it before attaching it to a Point Redemption or command.
  3. Configure one Event Alert.
  4. Use Preview to check the overlay card.
  5. Confirm the result in OBS.

[!IMPORTANT] Preview draws the alert on the overlay only. System → Event Emulator runs normal event processing and can affect configured outputs.

7. Add only required plugins

  1. Open System → Add/Remove Plugins.
  2. Install the plugin packages required for the current stream.
  3. Install Games Integration before a dependent Chat Game pack.
  4. Configure each installed plugin.
  5. Return to Connection Status and verify each connection.

Settings and choices

Choice Operator guidance
Separate bot account Optional. Use it when Chat Messages should appear under a dedicated bot name.
Bot Timezone Select the broadcaster's local IANA timezone.
Overlay canvas Match the OBS Browser Source dimensions exactly.
Browser Source audio Enable Control audio via OBS for clips and sounds.
Event Alert test Use Preview during setup. Use Event Emulator only when its full side effects are acceptable.
Plugins Install only those required by the stream configuration.

Expected result

GRiMbot connects to Twitch, joins the channel using the expected account, answers !ping, and supplies an overlay that appears in OBS at the correct size.

Verification checklist

  • [ ] GRiMbOS loads and accepts the GRiMbOS credentials.
  • [ ] .env has unique GRiMbOS credentials.
  • [ ] SETUP BOT Progress says Setup is complete.
  • [ ] Bot Timezone and the GRiMbOS password were verified separately.
  • [ ] Twitch events arrive over shows websocket.
  • [ ] A real Twitch EventSub event was received and processed.
  • [ ] The broadcaster account is authorized.
  • [ ] The expected Chat Message identity is joined to chat.
  • [ ] !ping receives a reply.
  • [ ] The OBS Browser Source uses the copied overlay URL.
  • [ ] The Browser Source dimensions match the overlay canvas.
  • [ ] Control audio via OBS is enabled.
  • [ ] One Event Alert Preview appears in OBS.
  • [ ] Core Command permissions have been reviewed.
  • [ ] Required plugin connections report working.

Failure handling

If !ping receives no reply, check Connection Status, then re-authorize the expected account in System Status. Confirm that the channel name in SETUP BOT is correct.

If the overlay is blank on a single-PC packaged installation, load its URL in a browser on that same PC and confirm that the Browser Source dimensions match the overlay canvas.

If OBS is on another machine, the current packaged release cannot supply the connection. See Two-PC setup for the deployment boundary.

If an Event Alert Preview does not appear, confirm that the overlay layout contains an Event Alerts object and that the OBS Browser Source is connected.

If a new Twitch-dependent feature reports missing permission, re-authorize the broadcaster in System Status. WebSocket EventSub restarts automatically. Re-subscribe EventSub applies only to webhook deployments.

If a real EventSub event is not received, verify the transport on SETUP BOT Progress, re-authorize the broadcaster, and test another real event. Event Emulator does not verify the Twitch EventSub connection.

Security and data notes

[!SECURITY] Set unique GRiMbOS credentials in .env before the first login. Do not expose the admin port, database, .env file, OAuth callback URL, or overlay administration URLs publicly.

Local installations use WebSocket EventSub when no public base URL is configured. Do not create a tunnel merely to receive normal Twitch events.

Related pages