Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@toebeann
toebeann committed Mar 16, 2024
1 parent 885adf4 commit 07eb0a5
Showing 1 changed file with 94 additions and 23 deletions.
117 changes: 94 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ BepInEx is currently [one of the most popular modding tools for Unity on GitHub]

## This pack's contents

This pack is preconfigured and ready to use for Subnautica modding.
This pack is preconfigured and ready to use for Subnautica modding.\
In particular, this pack comes with

- [Tobey.Subnautica.ConfigHandler](https://github.com/toebeann/Tobey.Subnautica.ConfigHandler), a configurable BepInEx patcher to automatically take care of BepInEx configuration for QModManager compatibility,
Expand All @@ -27,9 +27,8 @@ In particular, this pack comes with

The TL;DR is that QModManager is compatibile with BepInEx, [but there are some things to bear in mind](https://github.com/toebeann/BepInEx.Subnautica/wiki/Compatibility-with-QModManager).

## General FAQ

[There is an FAQ in the wiki](https://github.com/toebeann/BepInEx.Subnautica/wiki/FAQ).
> [!CAUTION]
> **Do not** install QModManager unless you are on the legacy branch, otherwise it **will** cause issues.
## Easy Automated Installation

Expand Down Expand Up @@ -57,53 +56,125 @@ If you get stuck, refer to the [gib README](https://github.com/toebeann/gib#read

## Manual Installation

**ℹ️** macOS users should follow [the idiot's guide to macOS installation](https://github.com/toebeann/BepInEx.Subnautica/wiki/Idiot's-guide-to-macOS-installation).

***

**⚠️ IMPORTANT NOTE ⚠️**

If you later install QModManager, please make sure to choose **NOT** to overwrite any files when you do.
> [!WARNING]\
> It is _strongly_ recommended that macOS users [install with gib](#macos-gib), as manual installation on macOS is _extremely_ tedious and error prone!\
> If you are a glutton for punishment and are determined to install manually, follow [the idiot's guide to macOS installation](https://github.com/toebeann/BepInEx.Subnautica/wiki/Idiot's-guide-to-macOS-installation).
This is because QModManager overwrites this pack's files with an old version of BepInEx, and many BepInEx plugins require the latest version. QModManager is compatible with this pack's version of BepInEx.
> [!CAUTION]\
> If you later install QModManager, please make sure to choose **NOT** to overwrite any files when you do.
>
> This is because QModManager overwrites this pack's files with an old version of BepInEx, and many BepInEx plugins require the latest version. QModManager is compatible with this pack's version of BepInEx.
>
> If you do overwrite files when you install QModManager, you will need to reinstall this pack for some BepInEx plugins to work.
If you do overwrite files when you install QModManager, you will need to reinstall this pack for some BepInEx plugins to work.

***
> [!TIP]\
> The game folder is the folder containing the game's executable (e.g. `Subnautica.exe`).
>
> Steam users can find the game folder by right-clicking the game in their Steam library and selecting `Manage` -> `Browse local files`.
To install manually, follow these instructions:

1. [Download Tobey's BepInEx Pack for Subnautica](https://github.com/toebeann/BepInEx.Subnautica/releases/latest/download/BepInEx.zip).
1. Extract the contents of the downloaded archive into the game folder:
- On Windows and Linux (SteamOS etc.), the game folder is the folder containing the game executable `Subnautica.exe`
- On macOS, the game folder is the folder containing the game executable `Subnautica.app`
1. [Download Tobey's BepInEx Pack for Subnautica](https://github.com/toebeann/BepInEx.Subnautica/releases/latest/download/Tobey.s.BepInEx.Pack.for.Subnautica.zip).
1. Extract the contents of the downloaded archive into the game folder.\
**ℹ️** _That just means open the .zip file and drag the files and folders out into the game folder!_
1. Depending on your operating system:
- Windows users: Run the game. If everything runs correctly, you will see the BepInEx console pop up on your desktop.
- Linux (SteamOS etc.) & macOS users: Follow the configuration instructions for your operating system below:

> [!IMPORTANT]\
> **With just this pack installed, you will not see any changes in-game!**\
> Check the `LogOutput.log` file in the `BepInEx` folder to determine whether BepInEx has loaded.
### Configuration on Linux (SteamOS etc.)

1. If you don't own the game on Steam, add it to Steam as a non-Steam game.
1. In Steam, go to the game's properties and set the launch arguments to:
```
WINEDLLOVERRIDES="winhttp=n,b" %command%
```
1. Run the game via Steam
1. Run the game via Steam.

### Configuration on macOS

[Follow the idiot's guide to macOS installation](https://github.com/toebeann/BepInEx.Subnautica/wiki/Idiot's-guide-to-macOS-installation).

## Useful links
## Installing mods

> [!NOTE]\
> The paths in this section are relative to the game folder, i.e. `BepInEx/plugins` = `[game folder]/BepInEx/plugins`, where `[game folder]` is the path to the folder containing the game's executable (e.g. `Subnautica.exe`).
>
> Steam users can find the game folder by right-clicking the game in their Steam library and selecting `Manage` -> `Browse local files`.
> [!TIP]\
> "Extract the .zip" simply means take the contents of the .zip file and put them in the specified location.
>
> For example, if you are told to "extract the .zip" or "extract the contents of the archive" into `BepInEx/plugins`, then you can simply open the .zip archive by double-clicking on it, then just select everything inside and drag the contents into your `BepInEx/plugins` folder. Easy!
> [!CAUTION]
> Nautilus and SMLHelper are incompatible. If you want to use mods for Nautilus, you _can't_ use SMLHelper, and vice versa.
**It is _strongly_ recommended to read and follow the instructions provided in the description of each mod you download.**

However, sometimes mod authors don't give good (or any) instructions, or you just can't be bothered to read them (we've all been there). For those occasions, here's a simple reference:

### Mod installation by type

| Mod type | Where to extract the .zip |
| --------------- | ------------------------- |
| BepInEx plugin | `BepInEx/plugins` |
| BepInEx patcher | `BepInEx/patchers` |
| QMod | `QMods` |

> [!IMPORTANT]\
> QModManager and QMods are _only_ for use on the legacy branch! See [Compatibility with QModManager](https://github.com/toebeann/BepInEx.Subnautica/wiki/Compatibility-with-QModManager) for details.
### Mod installation by .zip structure

| Folder located in root of .zip | Where to extract the .zip |
| ------------------------------ | ---------------------------------------------- |
| `BepInEx` | Directly in the game folder |
| `plugins` | `BepInEx` |
| `patchers` | `BepInEx` |
| `Some Mod Name` | Try `BepInEx/plugins` first, otherwise `QMods` |
| `QMods` | Directly in the game folder |

> [!IMPORTANT]\
> QModManager and QMods are _only_ for use on the legacy branch! See [Compatibility with QModManager](https://github.com/toebeann/BepInEx.Subnautica/wiki/Compatibility-with-QModManager) for details.
### Mod installation by requirements

> [!TIP]\
> On Nexus mod pages, you can usually see a mod's requirements by expanding the `Requirements` near the top of the description tab. Otherwise, read the mod's description.
| Listed in requirements or mentioned somewhere on the page | Where to extract the .zip |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BepInEx / this BepInEx pack | Probably `BepInEx/plugins`, maybe `BepInEx/patchers`. Use common sense and refer to [the .zip structure](#mod-installation-by-zip-structure) as needed. |
| Nautilus | Probably `BepInEx/plugins`. Use common sense and refer to [the .zip structure](#mod-installation-by-zip-structure) as needed. |
| QModManager | `QMods` |
| SMLHelper | Try `BepInEx/plugins` first, otherwise `QMods` |

> [!IMPORTANT]\
> QModManager and QMods are _only_ for use on the legacy branch! See [Compatibility with QModManager](https://github.com/toebeann/BepInEx.Subnautica/wiki/Compatibility-with-QModManager) for details.
### I still can't figure it out!

First, double check and follow the instructions on the mod page. If you still can't figure it out or there aren't any instructions on the mod page, you'll have to get in touch with the author of the mod somehow. Your best bet is usually going to be the Nexus Mods posts tab of that mod. Make sure to check that the question hasn't already been asked and answered.

## Useful links for mod authors

- [BepInEx: writing basic plugin walkthrough](https://docs.bepinex.dev/articles/dev_guide/plugin_tutorial/)
- [BepInEx: useful plugins for modding](https://docs.bepinex.dev/articles/dev_guide/dev_tools.html)
- [BepInEx: patching game methods at runtime](https://docs.bepinex.dev/articles/dev_guide/runtime_patching.html)

## Issues, questions, etc.

[First, check the FAQ to see if there is an answer to your question/issue](https://github.com/toebeann/BepInEx.Subnautica/wiki/FAQ).
First, please make sure to check that the answer you're looking for isn't already somewhere on this page. Use Ctrl+F to search for keywords.

Second, check [the FAQ](https://github.com/toebeann/BepInEx.Subnautica/wiki/FAQ) to see if there is an answer there.

If not, at this moment, you can use the following channels to ask for help

- [Subnautica Modding Community Discord](https://discord.gg/UpWuWwq)
- [BepInEx Discord](https://discord.gg/MpFEDAg) -- **Only technical support for THIS PACKAGE. No support for plugins.**
- [Nexus Mods posts tab](https://www.nexusmods.com/subnautica/mods/1108/?tab=posts)
- [GitHub issues](https://github.com/toebeann/BepInEx.Subnautica/issues)
- [BepInEx Discord](https://discord.gg/MpFEDAg) -- **Intended for developers, only technical support for BepInEx itself will be provided. No support for mods.**

0 comments on commit 07eb0a5

Please sign in to comment.