Table of contents

1. What is it?
2. What can it do?
3. What can it NOT do?
4. This says a mod isn't available, what can I do?
5. That sounds great, how can I use it?
   1. Installation and setup
      1. Install Python
      2. Download the script
      3. Create a virtual environment
   2. Usage

What is it?

A utility script to help players determine whether they can safely upgrade their modded install of PC Beat Saber.

What can it do?

This script can help you determine if it's safe to upgrade your PC installation of Beat Saber by telling you which of your installed mods have a known upgrade available in your target version. The goal is to help you ask the right questions - rather than "Should I upgrade," you will have the information to ask questions like the following:

• "Which of my installed mods are available in the new version?"
• "Which mods have I have installed manually, rather than from Mod Assistant, that I'll have to find upgrades for?"
• "Do I really care that (some mod) is missing in the new version, or can I live without it?"

What can it NOT do?

This tool doesn't know everything. It cannot tell you anything about mods that are not available on Mod Assistant, nor can it tell you if a mod's functionality has been replaced by a new mod or the base game.

This says a mod isn't available, what can I do?

If a mod you want to keep doesn't have an upgrade available, here are some things you can try to help you decide if you should upgrade:

• Check beatmods.com: This is the source of truth for Mod Assistant. You can use this to help find new mods that might replace the functionality you're looking for.
• Check the #pc-mods channel on the BSMG Discord: This can be a good source for mods, especially if they're new or otherwise not yet available in Mod Assistant.
• Check the mod's GitHub page: This may contain information about upcoming releases or have beta version available. At a minimum, you can usually tell if a mod is actively being developed by it

That sounds great, how do I use it?

Installation and setup

This section assumes that you've never used a Python program or GitHub before. If that's not the case, you can probably skip to Usage.

Install Python

You'll need to install a Python interpreter in order to run this script. It's developed and tested in Python 3.9.1, which is the newest release of Python at the time of writing. It's also tested in 3.7 and 3.8 if you happen to already have one of those on hand.

Download the installer and make sure you check the box that will either say "Add Python to environment variables" or "Add Python to PATH" on the first page of the installer. When it's finished installing, open a command prompt and enter python --version to make sure it worked correctly.

Download the script

Download the .zip file from the latest release and extract it in a location of your choosing.

Automated dependency installation

Use the provided script install.bat to set up a virtual environment and install the needed dependencies. Since the file is downloaded from the internet, you may need allow it past Windows Defender. If you're not comfortable doing this, you can also perform the setup steps manually as detailed below.

Manual dependency installation

This section details all of the steps performed by the install.bat script if you'd rather perform them manually.

Create a virtual environment (Optional, but strongly recommended)

Python has the concept of a "virtual environment" which is a small and isolated Python interpreter that allows cleaner dependency management. If you don't create a virtual environment, there's a possibility that there could be interference between different Python programs. For many users, this is not a major concern and you can skip to Usage.

To create a virtual environment, open a command prompt in the folder you unzipped the script (the place where upgrade_check.py is). If you click the whitespace in the file path you can copy and paste it in the command line, like this:
> cd "C:\Users\YourUsername\Documents\CanIUpgradeBeatSaber"
Some versions of Windows also have an "Open Command Window Here" or "Open in Windows Terminal" if you right click in file explorer.

Run the following commands to create your virtual environment. It will create a folder called venv that contains your virtual environment.
> python -m venv venv

To activate your venv:
> venv\Scripts\activate.bat

To deactivate your venv, type deactivate while it's running.

Install dependencies

Open a command line to the location of the script. See above for details on how to do this. If you're using a virtual environment, activate it. Run > pip install -r requirements.txt to install the required libraries.

Usage

You can use the provided batch script run_gui.bat to run the UI with sensible defaults. Since the file is downloaded from the internet, you may need to allow it past Windows Defender. If you're not comfortable doing this

Open a command line to the location of the script. See above for details on how to do this. If you're using a virtual environment, activate it. Then run the following command, which will provide more information about the program:
> python upgrade_check.py --help. This includes details on how to use each argument and whether they are required.

On your first usage of the script, you'll be prompted for the location of yoru Beat Saber installation. It should be the folder containing the file Beat Saber.exe (mine is D:\Program Files\Steam\steamapps\common\Beat Saber for example).

Your path may be different, and you can find it in Mod Assistant if you're stuck. After the initial run, the program will remember this for you.