gib

gib (tobey's Guided Installer for BepInEx) is a TUI application for automating the installation of BepInEx, the popular modding framework for Unity games.

curl -fsSL https://cdn.jsdelivr.net/gh/toebeann/gib/gib.sh | bash

gib aims to automate whatever it can, and hold your hand through whatever it cannot. Check the Features section for details.

Currently only macOS is supported, as the process of manual BepInEx installation is exceptionally cumbersome on this operating system. Both Intel-based and Apple Silicon processors are supported. For other limitations, see the Caveats section.

Table of contents

• gib
  • Table of contents
  • Features
  • Usage
    • Quick start
    • Walkthrough
      • Prerequisites
      • Running gib
  • Temporarily disabling mods for a game
    • Re-enabling mods after disabling them
  • Uninstallation
    • Uninstalling BepInEx
      • Clearing Steam launch options
      • Removing Steam shortcuts
      • Removing shortcuts from Applications
      • Removing BepInEx from the game folder
    • Uninstalling gib
      • Clearing bun's cache
      • Removing bun
  • Caveats
  • Known issues
  • License

Features

• Completely automates the process of installing BepInEx 5 for native unix builds of Unity games on macOS - no more falling asleep or pulling your hair out with frustration while trying to install it manually!
• Takes care of all the annoying stuff like making the run script executable and giving permission to run BepInEx which is where most people give up when installing manually!
• After installing BepInEx, runs an automated test to check that BepInEx is actually loading when you run the game, so you know that everything is working as it's supposed to!
• Nifty Steam integrations:

  • Automatically configures the launch options to run Steam games with BepInEx!

  • Optionally adds Steam shortcuts to run Steam games vanilla (without mods) or non-Steam games with mods!

    Note: The Steam shortcuts feature is experimental, please see Caveats below for details.

Usage

Quick start

Just run the following command in Terminal:

curl -fsSL https://cdn.jsdelivr.net/gh/toebeann/gib/gib.sh | bash

This command will make sure that bun (a speedy JavaScript runtime) is installed, then install and run the latest version of gib with it. If you're curious how it all works or want to verify the source code is safe, check gib.sh and index.ts for details.

If you get stuck, refer to the below walkthrough.

Walkthrough

Tip

If you run into any unexpected issues while following these instructions or need further assistance, please feel free to send a DM on discord to toebean (that's me) explaining the issue and I'll reply when I remember to check my message requests.

Note

These usage instructions were written for macOS Sonoma. The instructions below should work for other versions of macOS, but there may be some slight differences.

Prerequisites

• You'll want a Finder window open at the folder where the game is installed.

  • If you own the game on Steam, find the game in your library, then right-click it and select Manage -> Browse local files.

  • For the Epic Games Launcher, find the game in your library, then right-click it and select Manage. In the window that opens, look for the folder icon and click it.

  • For games you typically launch with Spotlight, search for the game as usual in Spotlight, and when the game is highlighted in the drop-down, hold Command until the icon changes to Finder. With Command still held down, press Enter.

• You'll want a copy of BepInEx downloaded and unzipped in your Downloads folder.

  If you're unsure where to get BepInEx from, try a Google search for [game name] bepinex pack, e.g. for Subnautica, I would search for:

  Subnautica BepInEx pack
  

  Where available, it is always advised to use a popular pack of BepInEx which has been tailored to the specific game you're trying to mod.

  If you can't find a BepInEx pack for the game, then the latest stable version of BepInEx from their official GitHub repo will do. You can find it here - scroll down to the Assets section, then download the file with "unix" or "macos_x64" in the name, e.g. BepInEx_unix_5.4.22.0.zip, BepInEx_macos_x64_5.4.23.2.zip

  Make sure it is unzipped in your Downloads folder after downloading it, as presently gib requires this. By default, Safari will have unzipped it for you. If you use other browsers, simply open the .zip and macOS should unzip it for you.

  Go ahead and open a Finder window in the unzipped BepInEx folder, so that you can see the file run_bepinex.sh.

  Leave this Finder window open - you'll want to come back to it later.

  

Tip

In some cases the shell script to load BepInEx may be named something else, e.g. start_game_bepinex.sh - in this case you will need to rename it to run_bepinex.sh for gib to recognise it.

Running gib

1. Open Terminal from Launchpad or Spotlight (press Command Space, type terminal and press Enter).

   

2. Copy the command from the Quick start section above and paste it in your terminal window with Command V, then press Enter to run it.

   

3. Now, simply follow the instructions in the terminal to install BepInEx to your game!

Tip

You can press Control C at any time in the terminal to abort.

Tip

If you ran into any unexpected issues while following these instructions or need further assistance, please feel free to send a DM on discord to toebean (that's me) explaining the issue and I'll reply when I remember to check my message requests.

Temporarily disabling mods for a game

Note

Please note that this section only applies to Steam games, For non-Steam games, you can simply run the game normally - without Steam - and it should launch vanilla.

If you have installed BepInEx with gib for a Steam game, you will have been given the option to add a shortcut to Steam to launch the game without mods (vanilla). However, this feature is experimental and for some games, it unfortunately cannot work due to the way the game is coded. Or, you may simply have declined the option and now find that you do indeed want to run the game without mods temporarily.

In either case, you can temporarily disable mods by following these steps:

1. Locate the game in your Steam library, then right-click it and choose Properties...
2. In the General tab of the window which opens, there should be a text input for launch options. Add the following text to the beginning of the text field, so that it comes before any other text:

   %command% #

3. Close the window.

Now, when you run the game with Steam, it should run without any mods. If you instead get an error when you try to launch the game, it means you made a mistake when you were editing the launch options. Make sure that %command% # comes before any other text in the launch options!

You may want to remove the vanilla shortcut for the game, if you added one when running gib.

Re-enabling mods after disabling them

To re-enable mods after temporarily disabling them, you simply need to undo the changes you made to the launch options:

1. Locate the game in your Steam library, then right-click it and choose Properties...
2. In the General tab of the window which opens, there should be a text input for launch options. Delete the following text, which should be at the start of the line:

   %command% #

3. Close the window.

The game should now run with mods once more when launched through Steam. If you get an error when you try to launch the game, it means you made a mistake when editing the launch options. If you can't seem to fix it, you will need to run gib again to reinstall BepInEx for the game - don't delete any files, just run the gib command again and it will fix the launch options for you - you won't lose any mods or anything.

Uninstallation

Uninstalling BepInEx

At present, uninstalling BepInEx is an entirely manual process which gib cannot automate, but it is fairly straightforward:

1. Undo any changes gib made to your Steam library:
   • Steam games: clear the launch options, and remove the vanilla shortcut added during instalation, if applicable.
   • Non-Steam games: remove the Steam shortcut to launch the game with BepInEx, if applicable.
2. You should also remove the shortcuts added to your Applications folder by gib for the game.
3. Optionally, you can reclaim the disk space used by BepInEx and your mods by removing BepInEx from the game folder. As long as you've followed the previous steps this is entirely optional, but probably a good idea since mods can take up a lot of space - and this isn't taken care of for you when you uninstall the game!

Clearing Steam launch options

Note

Please note that this section only applies to Steam games.

To uninstall BepInEx from Steam games, we need to clear the launch options for the game which are responsible for injecting BepInEx when we launch the game from Steam:

1. Locate the game in your Steam library, then right-click it and choose Properties...
2. In the General tab of the window which opens, there should be a text input for launch options. Click into the text box, press Command A to select all text, then Backspace or Delete to clear the launch options.
3. Close the window.

Now, when you launch the game with Steam it will launch completely vanilla, with no mods.

Removing Steam shortcuts

When setting up BepInEx you may have optionally added a Steam shortcut, e.g. for Steam games you can add an optional shortcut to launch the game without mods (vanilla), and for non-Steam games it is often preferable to set up a Steam shortcut to launch the game with mods.

In either case, if you're uninstalling BepInEx from the game you likely want to get rid of these shortcuts. To do so, follow these steps:

1. Locate the shortcut in your Steam library. If you have trouble finding it, you can use the search bar at the top to search for (Vanilla) or (BepInEx) as applicable.
2. Right-click the shortcut in your library and choose Manage -> Remove non-Steam game from your library.

Removing shortcuts from Applications

When setting up BepInEx with gib, it often adds shortcuts to your Applications folder for easy use from Launchpad or Spotlight. If you're no longer planning to use BepInEx with the game, you should remove these shortcuts. To do so, follow these steps:

1. Open Spotlight with Command Space, start typing the name until you find the shortcut - it will have the suffix (Vanilla) or (BepInEx). If you can't find it then you don't have one and can skip this.
2. With the shortcut selected in Spotlight, hold Command until the icon changes to Finder. With Command still held down, press Enter.
3. You should find yourself in a Finder window at the location of the shortcut. Simply delete it as normal.

Removing BepInEx from the game folder

Important

Make sure you follow the first two steps of Uninstalling BepInEx section before doing this.

If you want to reclaim the disk space taken up by BepInEx and the mods you're no longer using, here are instructions on how to completely remove BepInEx and all mods from the game folder:

1. Navigate to the game folder in Finder, the same way you found it when installing BepInEx. If you can't remember how to find it, check the Prerequisites section for instructions.
2. Delete the following files if present:
   • changelog.txt
   • doorstop_config.ini
   • libdoorstop.dylib
   • run_bepinex.sh
   • winhttp.dll
3. Delete the following folders if present:
   • doorstop_libs
   • corlibs
4. Finally, delete the BepInEx folder itself. Be aware that deleting this folder will delete not only BepInEx but also all mods you had installed, and any stored configuration of those mods.

Uninstalling gib

Note

Uninstalling gib itself is entirely optional and will not uninstall BepInEx, nor any mods you have installed for any games. For that, see Uninstalling BepInEx.

As of gib v0.2, gib is installed and executed with bun. gib itself (and its dependencies besides bun) takes up ~28 MB of space, and bun takes up ~59 MB, making for a total less than ~90 MB, which is pretty negligible all things considered.

If you're a web developer you may want to keep bun installed as it's a fantastic alternative to Node.js - even if you are targeting Node.js for your work, try using bun i instead of npm i sometime.

If you do want to delete gib for the miniscule space saving, you can choose to either remove bun entirely which will also delete gib and all of its dependencies, or you can choose to only clear bun's cache which will delete gib and its dependencies (and any other cached packages), but leave bun installed so that you can make use of it for development.

Clearing bun's cache

Clearing bun's cache will remove gib and all of its dependencies except for bun. To do so, follow these steps:

1. Open Terminal with Spotlight (Command Space, type terminal and press Enter).
2. Enter the following command:

   bun pm cache rm -g

If the above command reports an error, then you can also try deleting the contents of the cache manually by entering the following command in Terminal:

rm -rf ~/.bun/install/cache

Removing bun

To remove bun (which will also remove gib and all its dependencies), follow these steps:

1. Open Terminal with Spotlight (Command Space, type terminal and press Enter).
2. Enter the following command:

   rm -rf ~/.bun

Caveats

• Steam shortcuts are an experimental feature and may not work with all games - particularly the shortcuts to launch the game vanilla (without mods). For non-Steam games this isn't an issue - you can simply launch the game "normally" (without Steam) and as such we don't offer to create a vanilla shortcut. For Steam games however this can be irksome if we want to occasionally run the game without mods.

  If the vanilla shortcut does not work for one of your Steam games, you are encouraged to remove the vanilla shortcut and follow the guide to temporarily disable mods for the game.

• Only native macOS applications are currently supported.

  • Support for Windows apps on macOS (e.g. via CrossOver or Wine) is being considered.

  • Support for other operating systems is being considered.

• Only BepInEx 5 is currently supported. Support for BepInEx 6 is being considered.

• Users on Apple Silicon sometimes report that their game performance seems to diminish with only BepInEx installed. This is due to the fact that BepInEx is built for Intel-based chips, and therefore your Apple Silicon chip needs to run it through Rosetta. Unfortunately, there is nothing gib can do to resolve this, since BepInEx does not currently support Apple Silicon. If you find the performance impact too drastic, your only other option might be to use a Windows emulator like Parallels Desktop, Wine via Whisky or HyperPlay etc., and then install and run the Windows versions of both the game and BepInEx.

Known issues

• If the shell script to launch BepInEx is named something other than run_bepinex.sh (e.g. start_game_bepinex.sh), gib will not recognise it. I plan to fix this in an update. In the meantime, you can workaround this by renaming the shell script to run_bepinex.sh as needed.

• Relative paths are currently not supported and providing them will lead to strange issues. If you encounter an issue after having provided a relative path, please run the script again, this time providing absolute paths. You can provide absolute paths easily by simply highlighting the file in Finder, pressing Option Command C, then Command V in terminal to paste.

License

gib is licensed under the ISC License.