Skip to content

Installing on macOS via hardpatching (for non‐Steam platforms, e.g. Epic Games etc.)

Jump to bottom
Tobey Blaber edited this page Nov 12, 2023 · 12 revisions

This guide was written for macOS Sonoma. The instructions below should still work for other versions of macOS, but there may be some slight differences.

Note that while the images refer to Subnautica, this is just because I am too lazy to take new screenshots. Just pretend that the screenshots refer to Subnautica: Below Zero.

If you run into any unexpected issues while following this guide, join the Subnautica Modding discord server and send a message in one of the #help-and-support channels describing your problem. Make sure to mention you were following this guide, and what step you got stuck on, and I or someone else will help you out.

⚠️ IMPORTANT NOTE ⚠️

This installation method is a deprecated workaround. Currently the best way to use BepInEx and mods for Subnautica: Below Zero on macOS is to launch it with Steam (even if you don't own it on Steam, e.g. you have it on the Epic Games Launcher), following the instructions in the idiot's guide to macOS installation.

If you have an Intel-based Mac, we would recommend installing Windows with Boot Camp and running Subnautica: Below Zero with BepInEx through Windows before trying this installation method, as you will have much better support for BepInEx mods that way.

However, it is possible to run most of the latest mods on macOS without launching through Steam by following the guide below - but please note that is not well supported and should only be used as a last resort.

QModManager is not supported via this installation method, nor are any mods which require it:

  • QModManager requires the use of BepInEx patchers, and this installation method only supports BepInEx plugins.

⚠️ YOU WILL NEED TO FOLLOW THESE INSTRUCTIONS AGAIN WHENEVER SUBNAUTICA: BELOW ZERO UPDATES, SO YOU SHOULD PROBABLY BOOKMARK THIS PAGE ⚠️

  1. First, you will need to find the folder where Subnautica: Below Zero is installed in your Terminal.

    Example for Epic Games Launcher:

    1. Find Subnautica: Below Zero in your game library and then click the three dots and choose Manage. In the window which opens, look for the line Installation. There will be an option to uninstall Subnautica: Below Zero, but beside that there is a folder icon. Click this icon and it will open a Finder window where Subnautica: Below Zero is installed.

      image

    2. In the Finder window, hold the Option key to reveal the path bar at the bottom of the Finder window, and right-click on the final folder of the path bar (should be "SubnauticaZero") and click Open in Terminal from the menu.

      image

      Assuming you have a terminal window open, you can now skip ahead to step two of this guide.

      ⚠️ On some macOS versions you may not see the option to Open in Terminal. In this case, follow these steps:

      1. Right-click on the final folder of the path bar and click Copy "SubnauticaZero" as Pathname.

      2. Then, open Terminal from the Launchpad.

      3. In the Terminal window, type the following command, replacing with the pathname you just copied, and then press enter:

        cd "<PASTE THE PATHNAME HERE>"

        ⚠️ Make sure to remove the <>, but leave in the ""! It should look something like this once pasted properly:

        image

        You can now continue to step two of this guide.

    If you don't own Subnautica: Below Zero on Epic Games and are unable to determine how to find your Subnautica installation folder, follow the guide to locate it by brute force, then continue from step two of this guide once you have a Terminal window open at its location (open Terminal and enter cd "<PATH>" once you've got the right path in your clipboard).

  2. Next, we need to run the hardpatcher script in your game folder from the Terminal:

    1. Open this website in a new tab: https://tobey.me/mods/bepinex/hardpatcher/

    2. Copy the command under the heading macOS/Linux, paste it into your Terminal window (which MUST be navigated to your Subnautica: Below Zero installation folder), and run it.

      It will take a while to complete as it needs to download and execute some code I wrote to patch your game. Until it has finished downloading the necessary requirements, you won't see anything happening in the Terminal - just wait. Once it has finished, you should see the line Hardpatched successfully! at the end.

      image

  3. Finally we are ready to install the BepInEx Pack.

    1. Download Tobey's BepInEx Pack for Subnautica: Below Zero. You can get this either from the Files tab on Nexus Mods, or here on GitHub, whichever you prefer.

    2. Open your Subnautica: Below Zero installation folder in Finder (where the SubnauticaZero.app is). If you already closed it but still have Terminal open from running the hardpatcher, you can simply paste and run the following command in Terminal:

      open .

      image

    3. Move the contents of the BepInEx pack archive you previously downloaded into this folder.

      image

  4. Now let's check BepInEx is working. One of the best ways to do this is to install a simple BepInEx plugin such as Configuration Manager:

    1. Download the latest version of Configuration Manager

    2. Drag the contents of the archive into the BepInEx folder so that the .dll and .xml files are in the BepInEx\plugins folder. It should look like this when done correctly:

      image

    3. Run Subnautica: Below Zero as normal (e.g. launch via Epic Games Launcher). Once you reach the main menu, press F5. If everything is working you should see the Configuration Manager window pop up:

      image

      And now you're ready to go wild installing mods. Have fun!

If you ran into any unexpected issues while following this guide, join the Subnautica Modding discord server and send a message in one of the #help-and-support channels describing your problem. Make sure to mention you were following this guide, and what step you got stuck on, and I or someone else will help you out.

Clone this wiki locally