Beat Surgeon

Beat Surgeon is a Beat Saber mod that empowers your Twitch chat to directly interact with your gameplay in real time. It turns your stream into a collaborative (and chaotic) experience, allowing viewers to trigger visual effects like Rainbow notes, Flashbang, Bombs, Disappearing Arrows, Ghost Notes and Speed modifiers using simple chat commands or Channel Point Redeems. All while letting you maintain full control over cooldowns and if command is enabled or not.

What this mod does

This mod bridges Twitch chat with Beat Saber's gameplay engine. Viewers can type commands to instantly trigger effects such as:

• Rainbow Notes & Custom Colors: Randomize note colors or set specific RGB values on the fly.
• Visual Challenges: Trigger Ghost Notes, Disappearing Arrows, or a blinding Flashbang effect.
• Bombs: Arms the next note as a "bomb" and makes it look like one that displays either the viewer's name or a custom !bmsg message when cut.
• Speed Modifiers: Temporarily speed up (!faster, !superfast) or slow down (!slower) the song.

⚠️ A Note from the Developer

I am developing and supporting Beat Surgeon full-time to bring more fun, interactive features to the Beat Saber community.

Please be aware that I am still learning the intricacies of Beat Saber modding. The current version has been entirely reworked to make these effects work reliably and without causing any performance issues or conflicts with other mods, I plan to refine all that it does and plan for better features in future updates.

As this is my full-time focus, any support to help me keep going is highly appreciated! Your feedback and support allow me to continue tuning the mod and adding new features.

---

Features

Core Gameplay Effects

• Rainbow Mode (!rainbow): Instantly cycles note colors through the RGB spectrum for a vibrant, chaotic look.
• Custom Note Colors (!notecolor): Allows chat to set specific left and right saber colors using color names (e.g., red, blue) or hex codes.
• Ghost Notes (!ghost): Hides the cube mesh, leaving only the arrows visible for a short duration.
• Disappearing Arrows (!disappear): Hides the directional arrows and dots on notes, forcing players to rely on instinct.
• Bombs (!bomb, !bmsg <text>): Transforms the next spawnable note into a bomb. If the player cuts it, the viewer's name is displayed, or the custom !bmsg text if one was provided.
• Speed Control: Viewers can temporarily alter song speed:
  • !faster: Increases speed by 20%.
  • !superfast: Increases speed by 50%.
  • !slower: Decreases speed by 15%.
  • Includes an optional "Speed Exclusivity" mode to prevent multiple speed effects from stacking.
• Flashbang (!flashbang): Triggers an intense, momentary overexposure of the game's lighting system to simulate a flashbang.

Robust Moderation & Control

• Global Disable/Enable: Moderators can instantly shut down all mod interactivity with !surgeon disable (and restore it with !surgeon enable) if things get too chaotic.
• Granular Command Control: Moderators can disable specific problematic commands (e.g., !surgeon bomb disable) without stopping the entire mod.
• Cooldown Management:
  • Global Cooldowns: Enforce a universal wait time between any command usage.
  • Per-Command Cooldowns: Set specific timers for individual effects (e.g., allow !rainbow often, but restrict !superfast).
• Custom Aliases: Rename commands like !bomb to fit your channel's theme (e.g., !boop or !prank).

---

In-Game Settings

You can fully configure Beat Surgeon from within Beat Saber using the mod settings menu. The configuration is split into two main tabs:

1. Settings Panel

• Command Toggles: Individually enable or disable specific commands (e.g., if you want !rainbow enabled but don't want !flashbangs).

2. Cooldowns Panel

Control how often chat can trigger effects to balance chaos with playability.

• Global Cooldown:

  • Toggle: When enabled, triggering any command puts all other commands on cooldown.
  • Duration: Set the universal wait time (default: 60s).

• Per-Command Cooldowns:

  • Toggle: Switch to granular control where each command runs on its own timer.
  • Sliders: Adjust individual cooldowns for Rainbow, Ghost, Disappear, Bomb, Faster, SuperFast, Slower, and Flashbang.

• Speed Exclusivity:

  • Toggle: When enabled, prevents speed modifiers from stacking. Activating !faster will automatically cancel an active !slower or !superfast effect, ensuring the song remains playable.

• Custom Bomb Alias: Change the default !bomb command to something unique for your channel (e.g., set it to !boop or !plur).

3. Surgeon Tab

Quick access to command and channel point controls directly from the gameplay setup screen. Perfect for adjusting settings on the fly before starting a map or in multiplayer.

This tab contains two sub-tabs:

Surgeon Commands Sub-Tab

Enable or disable individual chat commands and effects with visual icon toggles.

• Command Toggles: Click each icon button to enable/disable that specific command:
  • !rainbow / !notecolor - RGB note colors
  • !disappear - Disappearing arrows
  • !ghost - Transparent notes
  • !bomb / !bmsg <text> - Convert a random note to a bomb, optionally with custom cut text
  • !faster - Increase song speed
  • !superfast - Dramatically increase song speed
  • !slower - Decrease song speed
  • !flashbang - Environmental flash effect
• Visual Feedback: Enabled commands show in color with a highlighted icon; disabled commands appear grayed out.

Twitch Sub-Tab

Configure Twitch Channel Point rewards for each effect without leaving the lobby if in one. Channel Points are completely Individual now and work even without command being enabled as long as your channel point is enabled

• Connection Status: Real-time display showing your Twitch connection state.

• Channel Point Configuration: Click any effect icon to open its settings modal:

  • Enable as Channel Point: Toggle to create/enable or disable the reward on your Twitch channel.
  • Cost: Set the channel point price for the reward (numeric input).
  • Cooldown: Define per-user cooldown in seconds (0-3600).
  • Background Color: Customize the reward's appearance on Twitch with a color picker.

• Channel Points are Refunded automatically if the effect did not apply for any reason.

---

Supporter Exclusive Features

To say thank you to those who support the development of Beat Surgeon, I've added exclusive customization options for Supporters!

Note: To activate these benefits, you must connect to the Beat Surgeon Backend via the Twitch tab in the mod settings (see Twitch Chat Setup below). This allows the mod to verify your Twitch subscription status securely.

If you are a supporter (currently via Twitch Subscription), you gain access to Edit Visuals buttons throughout the mod. Each effect that supports visual customization will have its own Edit Visuals button, allowing you to personalize how the effect looks to match your style.

Current supporter-exclusive customization features:

Bomb Text Effect

• Custom Bomb Text Color, Height and Width: Change the color of the text that appears when a bomb is cut (default is blue fading to white)
• Custom Bomb Fonts: Choose from a variety of unique fonts for the bomb message to make it stand out even more
• Custom Explosion Effects: Coming soon...

Rainbow Effects

• Cycle Speed: Change how fast the Gradient in rainbow changes if enabled. (lower = slower)

Disappearing Arrow Effects

• Fade Timer (Ms): changes how Fast or slow the arrows fade. Default is 0.30 Ms

Flashbang Effects

• Brightness Multiplier: Changed how bright your flashbang is. Default is 91

---

More exclusive cosmetic features and additional effects with Edit Visuals buttons are planned for future updates, so please check back soon!

Current supporter exclusive cosmetic features are displayed below:

---

Commands

Viewer Commands

Command	Description	Duration	Default Cooldown
!rainbow	Activates Rainbow Mode (cycling note colors).	30s	60s
!notecolor <left> <right>	Sets custom note colors. Accepts names (red) or hex (#FF0000). Example: !notecolor red blue or !notecolor #FF007F #00FF00	30s	60s
!ghost	Activates Ghost Notes (invisible cubes, visible arrows).	30s	60s
!disappear	Activates Disappearing Arrows (visible cubes, invisible arrows).	30s	60s
!bomb	Arms the next note as a bomb. Displays viewer name on cut. (Alias customizable)	Until hit	60s
!bmsg <text>	Arms the next note as a bomb. Displays up to 70 characters of custom text on cut, or falls back to the viewer name if no text is supplied. Shares the same cooldown as !bomb.	Until hit	60s
!faster	Increases song speed by 20%.	30s	60s
!superfast	Increases song speed by 50%.	30s	60s
!slower	Decreases song speed by 15%.	30s	60s
!flashbang	Triggers a blinding light effect.	Instant	60s
!surgeon	Displays current mod status and list of enabled commands.	N/A	None

Moderator Commands

Restricted to Broadcasters and Moderators only.

Command	Action	Description
!surgeon disable	Global Disable	Instantly disables ALL commands. Useful for serious attempts or if chat spams too much.
!surgeon enable	Global Enable	Re-enables all commands that were previously active.
!surgeon <cmd> disable	Disable Specific	Disables a single command type (e.g., !surgeon bomb disable).
!surgeon <cmd> enable	Enable Specific	Re-enables a single command type (e.g., !surgeon bomb enable).

Supported command names for specific enable/disable: rainbow, notecolor, disappear, ghost, bomb, faster, superfast, slower, flashbang.

---

Requirements

To use Beat Surgeon, you need a PC version of Beat Saber (Steam or Oculus) and the following dependencies:

• Beat Saber (PC VR)
• AssetBundleLoadingTools
• BSIPA (v4.3.6 or later)
• BeatSaberMarkupLanguage (BSML) (v1.12.5 or later)

---

Installation

1. Install Dependencies:

   • (Necessary if you dont use BeatSurgeon Twitch backend) Make sure you have installed BeatSaberPlus and successfully connected your Twitch account in its setup menu.
   • Ensure BSML and BSIPA are installed (usually handled automatically by ModAssistant).

2. Download & Install:

   • Download the latest BeatSurgeon.zip from the Releases page.
   • Once you extract the zip file there will be 2 folders Plugins and UserData.
   • Copy and paste both the folders in your beat saber directory (typically C:\Program Files (x86)\Steam\steamapps\common\Beat Saber\)

3. Launch & Verify:

   • Launch Beat Saber.
   • Look for the Beat Surgeon Button in the Mod Settings menu on the left side of the main screen.

---

Twitch Chat & Backend Setup

Beat Surgeon requires two simple steps to get fully up and running:

1. Chat Connection (Basic)

The mod leverages your existing BeatSaberPlus (ChatPlex) connection.

• How to: Simply ensure BeatSaberPlus is installed and you are logged into Twitch within its settings.
• Result: The mod will automatically listen to your chat for basic commands that start with !.

2. Backend Connection (Advanced/Supporter)

To enable Supporter Benefits and to unlock Edit Visuals buttons, you must authenticate with the Beat Surgeon backend.

• How to:

  1. Open the Beat Surgeon Settings in-game.
  2. Navigate to the Twitch Tab in Surgeon Menu.
  3. Click the "Connect to Twitch" button.
  4. This will open a browser window to authorize the mod securely via Twitch.
  5. You can Close the browser page once you see this page.

• Why is this needed? There is a ChatPlex connection that handles reading chat if you dont want to use BeatSurgeon Backend, but the Beat Surgeon backend is required to use Channelpoint features and to safely verify subscription status for unlocking supporter features.

• Once you are connected to BeatSurgeon's Backend, you should see Edit Visuals button in the Cooldown settings menu

• If you dont see the Edit Visuals button, Please go out of the menu and reselect Beat surgeon in the mods tab to see it.

Notes / Current Status (Work in Progress)

Beat Surgeon is currently in active development. While the core features listed above are fully functional, please keep the following in mind:

• Disabled Features: You may see references to "Song Requests" or "Endless Mode" in the code, messages or older discussions. These features are currently disabled/commented out while they undergo major refactoring and testing. They will be reintroduced in a future update once they meet stability standards.
• Compatibility: This mod is tested primarily on the Beat Saber v1.40.8. Compatibility with other major gameplay mods (like Noodle Extensions or Chroma) is generally fine, but visual conflicts can occasionally occur when multiple mods try to control notes and their visuals simultaneously. Please let me know if you find any of them so they can be patched.

---

Support Development

I am working on Beat Surgeon full-time to create the best possible interactive experience for Beat Saber streamers. As a solo developer still mastering the Beat Saber codebase, this project is a labor of love—and a significant time investment.

If you enjoy the chaos this mod brings to your streams and want to support its continued development, optimization, and new features, please consider supporting me:

• Subscribe on Twitch and Unlock Supporter Benefits
• Donate via PayPal

Your support directly helps me:

• Dedicate time to crefinind features and fixing bugs.
• Re-enable and finish complex features like Endless Mode and Dynamic Block/ BeatMap Insertions.
• Keep the mod updated for new Beat Saber versions.

Thank you for helping me keep the lights on and the sabers swinging!

---

Version History

• v1.0.0 (Current)

  • Major Update: Reworked almost the entire mod architecture (chat/backend/Twitch systems) for stability and long-term maintainability.
  • Performance Fix: Full performance pass to reduce/remove frame-drop issues during gameplay.
  • New Feature: Added modular command-processor pipeline for gameplay effects and moderation handling.
  • New Feature: Added/updated Twitch EventSub + Channel Point backend flow (per-reward subscriptions, safer resubscribe behavior, better redemption routing).
  • New Feature: Added ranked-map detection and auto-disable safeguards for score-impacting features.
  • New Feature: Added dedicated !notecolor command processor support.
  • Fix: Improved score-submission disable text/state handling.
  • Fix: Multiple Channel Point/EventSub reliability fixes (duplicate handling, quit/shutdown safety, and command routing).
  • Fix: Fixed Endless mode replies and improved logging/rainbow visual consistency.

• v0.3.0

  • Removed Feature: Local subscription checking methods
  • Fixed Feature: Various improvements for bomb visuals and multithreading.
  • Fixed Feature: Moderator command management as well as Mod/VIP detection.
  • New Feature: Added entitlement-based subscription checking system with auto-refreshing tokens
  • (Still in Testing) New Feature: Multiplayer+ support for anyone using Beat Surgeon in the lobby.
  • New Feature: Added Twitch EventSub connection to let the mod manage channel point rewards
  • New Feature: Added Submit Later tab in the Gameplay Setup view.
  • New Feature: Added Surgeon tab in the Gameplay Setup view (now lets you enable/disable commands and channel points in multiplayer through UI)

• v0.2.0

  • New Feature: Added moderator command management (!surgeon disable/enable) for global and per-command control.
  • New Feature: Added !notecolor command for custom chat-specified RGB values.
  • New Feature: Added Speed Exclusivity setting to prevent stacking speed modifiers.
  • Cleanup: Temporarily removed "Play First, Submit Later" and "Song Request" systems for refactoring.
  • Fix: Various stability improvements for asset loading and material handling.

• v0.1.0

  • Initial release.
  • Core effects: !rainbow, !ghost, !disappear, !bomb, !bmsg, !flashbang.
  • Basic speed commands (!faster, !slower).
  • Basic configuration UI.

---

License

Copyright © PhoenixBlaze0 2025

This project is proprietary. All rights reserved.

• You may download and use this mod for personal gameplay and streaming.
• You may not modify or redistribute without explicit written permission from the author.
• You may not re-upload this mod to other platforms or claim it as your own.

---

Credits

Beat Surgeon wouldn't exist without the inspiration and tools provided by the amazing Beat Saber modding community.

• Development & Design: PhoenixBlaze0
• UI Framework: Built using BeatSaberMarkupLanguage (BSML).
• Inspirations:
  • GameplayModifiersPlus by Kylemc1413 – The original inspiration for chat-controlled modifiers.
  • StreamPartyCommands – For ideas on interactive viewer commands like bombs.

---

Enjoy making your streams chaotic with Beat Surgeon!