TwitchRandomizer

TwitchRandomizer

Modrinth

License: GPL v3

TwitchRandomizer is a powerful Minecraft (Paper 1.21+) plugin that brings interactive, randomized challenges to your server — all controlled by your Twitch viewers! It seamlessly integrates your Minecraft gameplay with Twitch chat, letting your audience influence and trigger in-game events in real time.

---

📌 Key Features

- Twitch Chat Integration: Twitch viewers can trigger random events by subscribing or donating bits to your channel!

- Play this Challenge with your Twitch Friends: The plugin can read subscriptions and bits from multiple Twitch accounts — including StreamElements and Tipeeestream donations. So you can play this challenge with your Twitch friends!

- multiple streamer accounts simultaneously Donations via StreamElements or Tipeeestream trigger in-game events. Both support multiple streamer accounts simultaneously. Configuration is done exclusively via `donations.yml` in the plugin folder.

- Channel Name Display: When playing with multiple Twitch channels, the source channel is shown in brackets after every trigger — e.g. `exnfachjan (fuxelbau) deals 4 hearts`.

- Twitch Role Colors: Viewer names appear color-coded in Minecraft chat — Broadcaster (red), Moderator (green), VIP (pink), Donation (aqua), and regular viewers (white).

- Event Weighting and Customization: Adjust the likelihood of each event — make some more common, some rare, or disable them entirely. Easily reload or adjust settings on the fly. Reset all weights to defaults with one click.

- Recent Event Cooldown: A built-in cooldown system reduces the chance of the same event appearing multiple times in a row, automatically — no configuration needed.

- Synced Multi-Player Events: When playing with multiple players, all random values within an event (duration, item, mob type, etc.) are identical for every player. No more player 1 getting 10 seconds of Floor is Lava while player 2 gets 69.

- Spectator After Death: When a player dies, all players are moved to Spectator mode simultaneously. The timer and queue pause until a new run begins. Configurable per-run as "Tries" (team lives) or classic "Deaths" counter.

- Death Counter and Statistics: Built-in death tracking and player statistics, perfect for challenge runs and community competitions.

- Queue System: Viewer-triggered events can be queued and managed, ensuring smooth pacing and no event spam. The queue persists across server restarts and world resets!

- Pause System: Timer and queue automatically pause when a player is in the death screen or when all players are in spectator mode. Fully configurable.

- Pause Aura: When the timer is paused, a spiral flame particle aura appears around all online players — a clear visual indicator that the challenge is on hold.

- Graphical Interface (GUI): Tweak plugin settings, manage event weights, control the timer, and configure behaviors directly from an in-game GUI. Perfect for easy setup without any OP permissions!

- Multi-Language Support: Full German and English UI with automatic client language detection. Players can override their language in the GUI.

- Session and World Reset: Reset your seed after a death if you want a REAL challenge! Supports BungeeCord fallback servers.

---

✔️ Main Commands

- `/trgui` — Open the graphical config GUI.

Optional commands (not necessary, because you can manage everything seamlessly from the GUI):

- `/timer` — Start, stop, pause, or reset the challenge timer. - `/reset` — Initiate a world/session reset with confirmation. - `/queue add <amount> <username>` — Manually add events to the queue. - `/cleardeath` — Clear the death counter. - `/trconfig` — Configure the plugin via command (tab completion supported).

---

🎉 Events

| Event | Description | | --------------------- | -------------------------------------------------------------------------------- | | equipment_shuffle | Spawn random mobs near the player (hostile mobs chase you!) | | equipment_shuffle | Apply a random potion effect | | equipment_shuffle | Give a random item | | equipment_shuffle | Clear random slots from the player's inventory | | equipment_shuffle | Teleport to a random location (safe Y-level) | | equipment_shuffle | Take heart damage | | equipment_shuffle | Set the player on fire | | equipment_shuffle | Shuffle the entire inventory | | equipment_shuffle | A fast zombie chases you — if it catches you, it explodes! | | equipment_shuffle | Block crafting for a random duration (with boss bar countdown) | | equipment_shuffle | Creepers surround you clock-style and explode (no damage, no block destruction) | | equipment_shuffle | The floor beneath you turns to magma blocks (with block restore) | | equipment_shuffle | Launch the player sky-high | | equipment_shuffle | The ground turns to packed ice (with block restore) | | equipment_shuffle | Homing fireballs rain down on you | | equipment_shuffle | TNT Minecarts rain from the sky | | equipment_shuffle | Anvils fall from the sky | | equipment_shuffle | All players are teleported together — surrounding chunks get deleted! | | equipment_shuffle | Receive a Totem of Undying that doesn't actually work | | equipment_shuffle | All tiered tools and armor in your inventory are randomly upgraded or downgraded |

---

🛠 Getting Started

You can configure the plugin through the config.yml or without OP permissions directly through the GUI in-game.

1. Install: Place `TwitchRandomizer.jar` into your server's plugins folder.

2. Configure Twitch Integration: - Open the GUI with `/trgui`; in the top left, you'll find the "twitch-info" book. - Insert your `Broadcaster Username` by left-clicking on the book, then confirm with `done`. You can enter multiple channels separated by commas, semicolons, or new lines. - Insert your `Bot OAuth` by right-clicking on the book, then confirm with `done`. You can get your OAuth token here: https://twitchtokengenerator.com/quick/1KRFjxyoNE Make sure the following scopes are active: `bits.read`, `chat:read`, `channel:read:subscriptions` and `user:read:subscriptions`.

3. never overwritten Edit `plugins/TwitchRandomizer/donations.yml` — this file is created automatically on first start and is never overwritten by the plugin.

```yaml se_enabled: true se_accounts: "YOUR_CHANNEL:YOUR_JWT_TOKEN" ```

For multiple streamers, separate entries with a semicolon:

```yaml se_accounts: "Channel1:JWT1;Channel2:JWT2" ```

Get your JWT token from: https://streamelements.com/dashboard/account/channels

4. Configure Tipeeestream (optional): In the same `donations.yml`:

```yaml tipeee_enabled: true tipeee_accounts: "YOUR_CHANNEL:YOUR_APIKEY" ```

Multiple accounts work the same way: `"Ch1:KEY1;Ch2:KEY2"` Get your API key from: https://tipeeestream.com/dashboard/stream

After editing `donations.yml`, apply it in-game with `/trconfig donations reload` — no server restart required.

5. Reload/Restart: If you use the GUI, you don't need to restart the server.

6. Set up your trigger You can test your connection. With the test triggers enabled (find them in the `Debug Menu`), you can simulate events like a sub (`!test`), a gift sub (`!gift`), or a sub gift bomb (`!giftbomb [N]`).

MAKE SURE YOUR TIMER IS RUNNING! OTHERWISE, YOU CAN'T ADD EVENTS TO THE QUEUE THROUGH TWITCH!

If you want to add some events to the queue, you can simply use the command `/queue add <AMOUNT> <Username>`. This also works when the timer isn't running!

---

🔍 Permissions for non-OP users (LuckPerms required)

| Permission | Description | | ----------------------------- | ------------------------------- | | twitchrandomizer.gui | Full GUI access (super-node) | | twitchrandomizer.gui.use | Use GUI (basic) | | twitchrandomizer.admin.save | Save & hot-reload config | | twitchrandomizer.admin.edit | Edit values via GUI | | twitchrandomizer.admin.twitch | Set Twitch channel/token | | twitchrandomizer.timer.start | Start the timer | | twitchrandomizer.timer.stop | Stop/pause the timer | | twitchrandomizer.timer.reset | Reset the timer | | twitchrandomizer.reset | Reset flow | | twitchrandomizer.reset.force | Force reset (skip confirmation) |

The GUI uses sensible permission checks for each action.

📎 Requirements

- Minecraft Paper server 1.21+ - Java 21 or newer - Twitch account (at least affiliate) and OAuth token for chat integration

---

📋 Changelog

v1.5.0

- Queue pause on all-spectator — `donations.yml` now uses `tipeee_accounts` with the same `"Channel:APIKEY;Channel2:APIKEY2"` format as StreamElements. - Queue pause on all-spectator — When playing with multiple Twitch channels, the source channel name is shown in brackets after every event trigger. - Queue pause on all-spectator — All random values (duration, item, mob type, potion effect, etc.) are now identical for every player in the same event dispatch. - Queue pause on all-spectator — All players are now teleported to a single meeting point before chunks are cleared. Prevents players from voiding each other. - Queue pause on all-spectator — When a player dies, all online players are now moved to Spectator simultaneously. Timer and queue pause correctly. - Queue pause on all-spectator — When Spectator-after-death is enabled, the counter is labeled "Tries/Versuche" and only counts once per team-death. When disabled, it counts individual deaths as before. - Queue pause on all-spectator — The donation value per event is now capped at 5.0€ (the standard price). You can only go lower, not higher. - Queue pause on all-spectator — A new anti-repeat algorithm reduces the weight of recently triggered events for the next 2–3 picks, making the event pool feel more varied. - Queue pause on all-spectator — Timer and queue now correctly pause as soon as all players are in Spectator mode.

v1.4.0

- Weights: — All tiered tools and armor in the inventory are randomly upgraded or downgraded by one tier. Enchantments, display names, and lore are preserved. - Weights: — Donations via StreamElements now trigger in-game events. Supports multiple streamer accounts simultaneously. - Weights: — A spiral flame particle effect is displayed around all online players while the timer is paused. - Weights: small default value changes.

v1.3.1

- Initial public release.

---

🗝 Credits

Built by exnfachjan with the help of AI (Claude by Anthropic). Thanks to the Paper/Spigot communities and Twitch4J for solid foundations.

---

🔒 License

This project is licensed under the GNU General Public License v3.0 — see GNU General Public License v3.0 for details.

License: GPL v3

---

❤️ Support

Do you like my plugin? Feel free to support my work: https://streamelements.com/exnfachjan/tip