Twitch2Gether

Cheer Bits, trigger chaos. Twitch2Gether lets your viewers step right into your Minecraft world with Twitch Bits. One cheer is all it takes for a creeper to show up next to you, lightning to strike, or midday to turn into midnight. Every Bits amount can trigger its own action with its own message in chat, so your community sees exactly who just caused the chaos.

You decide in a simple config file which amounts trigger what. An action can be as small as a thank-you message or as wild as any Minecraft command you can think of. Cooldowns and a waiting queue make sure the chaos stays fun instead of everything happening at once. You can aim the actions at your streamer or let them hit every player on the server.

Once it’s set up, it keeps running on its own: your Twitch login is saved, refreshed automatically and reconnected if the connection drops. A few admin commands let you pause the fun, clear the queue or test a donation without spending a single Bit. The mod runs on the server only, so your players don’t have to install anything.

==========================================================
 STREAM2GETHER – WIKI
 Viewers trigger actions in Minecraft with Twitch Bits
==========================================================

The mod runs on the server only. Players don't need to install anything.

Requirements (must already be in place):
  - Minecraft server with Fabric, version 26.3 (Fabric Loader 0.20.1+)
  - Java 25
  - Fabric API in the "mods" folder
  - A Twitch channel that can receive Bits (Affiliate or Partner)

----------------------------------------------------------
 PART 1: INSTALL THE MOD
----------------------------------------------------------

1. Stop the server.

2. Put the file "stream2gether-1.0.0.jar" into the server's
   "mods" folder (e.g. upload it via SCP or SFTP).

3. Start the server.

4. The log must contain: "Twitch2Gether loaded"
   These files are also created in the "config" folder:
     twitch2gether-settings.json   (settings)
     twitch2gether-actions.json    (actions)

For mod updates: stop the server, replace the old .jar with the new
one, start the server. The config files are kept.

Enter commands in the server console (without "/") or in game as
an operator (with "/").

----------------------------------------------------------
 PART 2: CONNECT TO TWITCH (one time)
----------------------------------------------------------

The mod connects to your channel through a Twitch application
that you create yourself. You log in with YOUR Twitch account.
The application only gets the right to read the Bits donations
of your channel.

STEP 1 – Set up the Twitch application:

  1. Open https://dev.twitch.tv/console/apps and log in with the
     Twitch account that should own the application.
     (Twitch may require two-factor authentication for this.)

  2. Click "Register Your Application" and fill it in exactly like this:
       Name:                  "Application name" (can be any unique name)
       OAuth Redirect URLs:   http://localhost
       Category:              Game Integration
       Client Type:           Public   (important! NOT "Confidential")

  3. Click "Create".

  4. In the list, click "Manage" next to "Application name".

  5. Copy the "Client ID". This is the string that every user of
     the mod enters in Step 3.

  No "Client Secret" is needed and it must not be entered anywhere.

  Important: The type "Public" is required for the code login to
  work. This way every streamer can use the application with their
  own account.

STEP 2 – Get the Client ID of the application you created

  The Client ID is shown in the Twitch developer console
  (dev.twitch.tv/console/apps) under "Manage" for the application
  "Application name".

Step 3 - Step 6 has to be done in your server console / screen session while Server is running!

STEP 3 – Enter the Client ID in the mod

  twitch clientid set CLIENT-ID-OF-APPLICATION-NAME
  

STEP 4 – Log in

  twitch connect

    The console shows a web address and a code.
    1. Open the address in a browser.
    2. Enter the code.
    3. Log in with the Twitch account whose channel should receive
       the Bits (the streamer).
    4. Click "Authorize".

  Success: "Connected as YOURNAME!"

  The login is saved and used automatically on the next server
  start. You only have to do this once.

STEP 5 – Set the streamer player

  twitch streamer set YOUR-MINECRAFT-NAME
  Actions only affect this player. If the player is not online,
  donations are discarded (nothing is made up later).
  Without an entry, actions go to all players.

STEP 6 – Test

  twitch status           -> "Connected as ..." and "active"?
  twitch testbits 100     -> shows what would be triggered
  Then cheer 1 Bit in your channel yourself to check the real
  connection.

Done: viewers can now trigger actions with Bits.

----------------------------------------------------------
 PART 3: CONFIGURE ACTIONS
----------------------------------------------------------

File: config/twitch2gether-actions.json
(created with examples on first start; the example messages are
in English. An existing file keeps its old text.)

Example:
  {
    "actions": [
      {
        "bits": 100,
        "message": "{user} sends a Creeper!",
        "commands": [
          "execute as {player} at @s run summon minecraft:creeper ~ ~ ~"
        ]
      }
    ]
  }

  bits      Minimum number of Bits for this action
  message   Message to all players (empty = none)
  commands  Minecraft commands (empty = message only)

Placeholders:

  {user}    Name of the donor (only in "message")
  {bits}    Number of Bits (only in "message")
  {player}  Streamer name, "@a" without a streamer (only in "commands")

Tier rule:

  Exactly ONE action runs: the one with the highest Bits threshold
  that is less than or equal to the donation.
  Example with tiers 50, 300, 1000: 400 Bits -> the 300 action.
  Below the lowest tier nothing happens.

After changes:  twitch reload

----------------------------------------------------------
 PART 4: SETTINGS
----------------------------------------------------------

File: config/twitch2gether-settings.json
After changes:  twitch reload

  cooldownSameSeconds   (default 300)
      Time before the same action may run again.

  cooldownOtherSeconds  (default 60)
      Time between any two actions.

  queueTimeoutSeconds   (default 600, minimum 10)
      After this time a queued donation expires.

Queue:
  - Actions with commands wait in a queue (max. 50) during a
    cooldown.
  - Message-only actions (no commands) have no cooldown.
  - If the streamer goes offline, the queue is cleared.
  - On an empty server Minecraft pauses after 60 s (default).
    Cooldowns don't advance then either.

----------------------------------------------------------
 PART 5: ALL COMMANDS
----------------------------------------------------------

Who may use them? Only operators (admins) and the server console.
In the console enter them without "/", in game with "/".

--- Connection ---

twitch connect
    Starts the login to Twitch. Shows an address and a code
    that you enter in the browser.

twitch disconnect
    Disconnects Twitch and deletes the saved login.
    A new "twitch connect" is needed afterwards.

twitch status
    Shows: connected as whom, active or PAUSED, and how many
    actions are waiting in the queue.

twitch clientid
    Shows whether a client ID is set (only the first 4 characters).

twitch clientid set <id>
    Saves the client ID of your Twitch application. With a new ID
    the old login is deleted, then run "twitch connect".

--- Streamer ---

twitch streamer
    Shows which player is set as the streamer.

twitch streamer set <name>
    Sets the player who receives the actions.

twitch streamer clear
    Removes the streamer. Actions then go to all players.

--- Control ---

twitch pause
    Stops execution. Queued actions are kept, new actions with
    commands are queued. Message-only actions are skipped.

twitch resume
    Continues execution after a pause.

twitch clear
    Discards all queued actions immediately.

twitch reload
    Reloads settings and actions from the files.
    Reports how many actions were loaded.

--- Test ---

twitch testbits <amount>
    Simulates a donation by the user "TestUser" and reports what
    happened (executed, waiting, discarded, ...).

twitch testbits <amount> <name>
    Same as above, but with your own donor name.

----------------------------------------------------------
 PART 6: COMMON PROBLEMS
----------------------------------------------------------

"No client ID set"
    -> twitch clientid set CLIENT-ID-OF-APPLICATION-NAME

Nothing happens on a donation
    -> twitch status: connected and active?
    -> Is the streamer player online? Name spelled correctly?
    -> Does the donation reach the lowest Bits tier?
    -> Check with twitch testbits <amount>.

Login expired or revoked
    -> Run twitch connect again.

Mod does not load
    -> Java 25, Minecraft 26.3, Fabric Loader 0.20.1 or newer and
       Fabric API in the "mods" folder?

Security notes
    -> The file config/twitch2gether-auth.json gives access to your
       channel. Never share it.
    -> Only make trusted players operators, they can use all
       twitch commands.
    -> Keep "online-mode=true" on public servers.