toebeann/subnautica-support

Vortex support for Subnautica

Subnautica Support for Vortex

Description

This extension adds support for Subnautica to Vortex Mod Manager, enabling you to easily automate installation of mods for Subnautica without having to worry about where the files are supposed to go, etc.

At this time, the following mod types are supported:

• BepInEx Pack for Subnautica
• BepInEx plugins
• BepInEx patchers
• QModManager
• QMods
• CustomCraft2 plugin packs
• CustomHullPlates addon packs
• CustomPosters addon packs

If you are developing a different kind of mod and would like it to be supported by this extension, please raise an issue or pull request on the GitHub repository with a link to your mod page so that I can take a look at how you are packaging it. Please make sure to include instructions for how you would expect it to be installed, so that I can have Vortex automate the process. PRs welcome!

How to install

This extension requires Vortex ^1.9.0. To install, click the Vortex button at the top of the Nexus Mods page to open this extension within Vortex, and then click Install. Alternatively, within Vortex, go to the Extensions tab, click "Find More" at the bottom of the tab, search for "Subnautica Support" and then click Install.

You can also manually install it by downloading the main file and dragging it into the "drop zone" labelled "Drop File(s)" in the Extensions tab at the bottom right.

Afterwards, restart Vortex and you can begin installing supported Subnautica mods with Vortex.

---

The rest of this page is intended for mod authors only.
Users can simply follow the instructions above to install, and you're done!

---

How to make my mod compatible with this extension?

Assuming your mod is of a supported type, simply follow the packaging examples for that mod type below.

Don't forget to set your latest main file as your main Vortex file, and make sure that the "Remove the 'Download with Manager' button" option is unticked!

If your mod is not of a supported type, you will need to raise an issue or pull request on the GitHub repository with a link to your mod page so that I can take a look at how you are packaging it. Please make sure to include instructions for how you would expect it to be installed.

Packaging examples

BepInEx plugins

Any of the following structures are valid:

- MyBepInExPlugin.dll

- My BepInEx Plugin
  - MyBepInExPlugin.dll

- plugins
  - MyBepInExPlugin.dll

- plugins
  - My BepInEx Plugin
    - MyBepInExPlugin.dll

- BepInEx
  - plugins
      - MyBepInExPlugin.dll

- BepInEx
  - plugins
    - My BepInEx Plugin
      - MyBepInExPlugin.dll

BepInEx patchers

Any of the following structures are valid:

- patchers
  - MyBepInExPatcher.dll

- patchers
  - My BepInEx Patcher
    - MyBepInExPlugin.dll

- BepInEx
  - patchers
      - MyBepInExPatcher.dll

- BepInEx
  - patchers
    - My BepInEx Patcher
      - MyBepInExPatcher.dll

BepInEx plugin/patcher combos

Any of the following structures are valid:

- patchers
  - MyBepInExPatcher.dll
- plugins
  - MyBepInExPlugin.dll

- patchers
  - My Mod Name
    - MyBepInExPatcher.dll
- plugins
  - My Mod Name
    - MyBepInExPlugin.dll

- BepInEx
  - patchers
    - MyBepInExPatcher.dll
  - plugins
    - MyBepInExPlugin.dll

- BepInEx
  - patchers
    - My Mod Name
      - MyBepInExPatcher.dll
  - plugins
    - My Mod Name
      - MyBepInExPlugin.dll

QMods

Any of the following structures are valid:

- My QMod
  - mod.json
  - MyQMod.dll

- QMods
  - My QMod
    - mod.json
    - MyQMod.dll

- mod.json
- MyQMod.dll

Mods which can be installed as either a QMod or a BepInEx plugin

Mods which meet all of the following criteria are eligible to be installed as either a QMod or a BepInEx plugin:

• has a mod.json manifest for QModManager
• has an assembly containing a BaseUnityPlugin class with a BepInPlugin attribute applied to it
• has the following structure:

  - My Mod
    - mod.json
    - MyMod.dll
  

When a user installs an eligible mod, if the user is on the legacy branch it will be installed as a QMod. Otherwise, it will be installed as a BepInEx plugin.

CustomCraft2 plugin packs

Any of the following structures are valid. Note that although these examples only include a single asset and/or working file each, the extension will happily install packs containing multiple of each.

- CustomCraft2SML
  - Assets
    - MyCC2Asset.png
  - WorkingFiles
    - MyCC2Mod.txt

- CustomCraft2SML
  - WorkingFiles
    - MyCC2Mod.txt

CustomHullPlates addon packs

Any of the following structures are valid. Note that although these examples only include a single hull plate, the extension will happily install packs containing multiple hull plates.

- CustomHullPlates
  - HullPlates
    - MyHullPlate
      - icon.png
      - info.json
      - texture.png

- HullPlates
  - MyHullPlate
    - icon.png
    - info.json
    - texture.png

- MyHullPlate
  - icon.png
  - info.json
  - texture.png

CustomPosters addon packs

Any of the following structures are valid. Note that although these examples only include a single poster, the extension will happily install packs containing multiple posters.

- CustomPosters
  - Posters
    - MyPoster
      - icon.png
      - info.json
      - texture.png

- Posters
  - MyPoster
    - icon.png
    - info.json
    - texture.png

- MyPoster
  - icon.png
  - info.json
  - texture.png

Mixed CustomHullPlates/CustomPosters addon packs

Any of the following structures are valid. Note that although these examples only include a single hull plate and poster each, the extension will happily install packs containing multiple of each.

- CustomHullPlates
  - HullPlates
    - MyHullPlate
      - icon.png
      - info.json
      - texture.png
- CustomPosters
  - Posters
    - MyPoster
      - icon.png
      - info.json
      - texture.png

- HullPlates
  - MyHullPlate
    - icon.png
    - info.json
    - texture.png
- Posters
  - MyPoster
    - icon.png
    - info.json
    - texture.png

- MyHullPlate
  - icon.png
  - info.json
  - texture.png
- MyPoster
  - icon.png
  - info.json
  - texture.png

My mod is being installed strangely!

If you have followed the packaging examples above and your mod is still being incorrectly installed by this extension, please raise an issue on the GitHub repository with a link to your mod page or with a sample archive attached so that I can get it fixed.

Copyright notice

Subnautica Support - Vortex support for Subnautica

Copyright (C) 2023 Tobey Blaber

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see https://www.gnu.org/licenses.

subnautica-support's Issues

feature idea: steam branch management

I have been considering making a tool that lets you have multiple copies of the game via Steam installed simultaneously and automating the process of swapping branches and all that jazz for the user.

It would be nice if such a tool could be integrated with Vortex so that users can swap between mod loadouts (integrate with Vortex's profile management feature) at the same time as swapping between game versions.

This way a user could easily switch between SN 2.0 and SN legacy with different mods (or different versions of mods) enabled.

Add support for CustomCraft3 (both of them)

There are currently two competing versions of CustomCraft3, both for Living Large only. Both of these mods known as CustomCraft3 seem to be used by users, and both have recipes available on Nexus Mods.

On top of that, there is also CustomCraft2 available for both legacy and living large.

PrimeSonic's CustomCraft2

This is considered the OG, but is in itself a remake of a mod made by Iw23J. PrimeSonic's CC2 has been around a long time, and has both a legacy version for QModManager, and as of August 2023, a living large version for BepInEx. Both versions of this mod install to the CustomCraft2SML folder within either QMods or BepInEx/plugins, respectively, and plugin packs are installed within this folder.

Vortex currently supports both versions of PrimeSonic's CC2, and I intend for this to continue.

shaimildar's unofficial remake

shaimildar's CC3 uses a completely different syntax for plugin packs that is backwards-incompatible with PrimeSonic's CC2 (it uses JSON instead of PrimeSonic's EasyMarkup format).

This shouldn't be too difficult to support, packs will be just coming with .json files instead of .txt files. Just need to detect them and put them in the right place (within the same folder as the mod itself).

Note

A user should never have both shaimildar's CC3 and PrimeSonic's CC2 installed at the same time, since one is for Nautilus and the other is for SML, and these are incompatible.

Important

While the instructions for shaimildar's CC3 say to place the files in BepInEx/plugins/CustomCraft3, currently Vortex wil install them directly within BepInEx/plugins, since the mod author did not nest the files in a CustomCraft3 folder. This needs to be addressed - see the below section "Supporting both mods called CustomCraft3 at the same time" for a proposed solution.

MrPurple6411's officially sanctioned port

MrPurple6411's CC3 is an officially sanctioned port of the PrimeSonic's CC2 and I believe it is backwards-compatible with plugin packs for PrimeSonic's CC2 - both PrimeSonic's CC2 and MrPurple6411's CC3 use the same syntax for plugin packs (PrimeSonic's EasyMarkup format).

Supporting MrPurple6411's CC3 requires some finesse. First, we need to investigate whether MrPurple6411's CC3 is indeed backwards-compatible with PrimeSonic's CC2, and if PrimeSonic's CC2 is forwards-compatible with MrPurple6411's CC3.

Note

A user should never have both MrPurple6411's CC3 and PrimeSonic's CC2 installed at the same time, since one is for Nautilus and the other is for SML, and these are incompatible.

If they are fully compatible with one another's plugin packs, then it means that both plugin pack types can be treated the same way:

• if the user is on legacy:
  • always install to the old CC2 folder (CustomCraft2SML)
• if the user is on living large:
  • if the user only has MrPurple6411's CC3 installed: install the plugin pack to the new CC3 folder (CustomCraft3)
  • if the user only has PrimeSonic's CC2 installed: install the plugin pack to the old CC2 folder (CustomCraft2SML)
  • if the user has both (or neither) installed: prompt the user to choose (and inform them that they are incompatible since one uses SMLHelper and the other uses Nautilus)

If MrPurple6411's CC3 has back-compat with PrimeSonic's CC2, but PrimeSonic's CC2 does not have forwards-compat with MrPurple6411's CC3, then we need to use the above logic only for PrimeSonic's CC2 plugin packs, but for MrPurple6411's CC3 plugin packs we will always install them to the new CC3 folder within BepInEx/plugins.

Supporting both mods called CustomCraft3 at the same time

The biggest complication in all of this is supporting both shaimildar's CC3 and MrPurple6411's CC3 at once, side-by-side. They both want to use the same base folder (CustomCraft3) for their mod, and they both use the same dll name CustomCraft3.dll, which means there will be file conflicts if they both get their way.

The easiest thing to do is just declare them incompatible and simply not support this use case, but it should technically be possible to use them both at once if the file conflicts are resolved. Of course, this should be investigated, because if they are actually fully incompatible then we can simply not allow the user to install both - they must choose.

But if this does not turn out to be the case, then we should not create an incompatibility in the Vortex extension. We will need to address the issue.

Since currently shaimildar's CC3 does not actually get installed by Vortex into a CustomCraft3 folder due to the author's negligence to nest the files in a CustomCraft3 folder themself, we could simply ignore the problem and detect the right place to put the packs, relative to where each's plugin file is located. So for shaimildar's CC3 it would currently be BepInEx/plugins/WorkingFiles and for MrPurple6411's CC3 it would currently be BepInEx/plugins/CustomCraft3/WorkingFiles.

This solution though would ignore the desired structure of each mod. It would also potentially cause conflicts for other mods. And in the worst case, if shaimildar's CC3 ever does address their negligence by nesting the files within a CustomCraft3 folder, there will be file conflicts.

shaimildar's CC3 hasn't been updated since July of 2023, and since PrimeSonic's own port of CC2 to BepInEx and MrPurple6411's officially sanctioned port have come out, it is unlikely they will, especially since there are currently only 2 mods on Nexus which require shaimildar's CC3. This does not however rule out the possibility that it will ever happen, and I don't want to have to update this extension if it ever does.

Therefore, I think it would be best for the Vortex extension to award MrPurple6411's officially-santioned port with the CustomCraft3 folder, and shaimildar's CC3 will instead live in CustomCraft3 JSON. This will make it easier at a glance for users to understand the difference, and it shouldn't prevent the mods from functioning, while preventing file conflicts.

If Vortex detects shaimildar's CC3 installed without the CustomCraft3 JSON folder, it should prompt the user to reinstall it, and until such time as they do it should refuse to install plugin packs for shaimildar's CC3. And if the user has manually installed it to a CustomCraft3 folder and attempts to install MrPurple6411's CC3, it should ask the user to decide whether they want to overwrite it or not, and if not then it should cancel the install and prompt the user to reinstall shaimildar's CC3 with Vortex.

This proposed solution does of course ignore the intended structure of shaimildar's CC3, and so it could cause confusion for users. However, I think this is unlikely to be a problem as usage of shaimildar's CC3 is likely in decline. We can mitigate the risk by prompting the user when installing shaimildar's CC3, letting them know that we will install it there, and why.

It is likely also worth prompting users when they install plugin packs for either mod that if they don't have the appropriate required mod, they should install it, and probably to let them know of the differences ("But I already have CustomCraft3 installed!" is going to come up a lot otherwise - it probably still will since user's never read, but you know...)

Investigate QMods folder nesting

Some users have been showing up in the Subnautica Modding discord server with some mods installed into a nested QMods folder, i.e. Subnautica\QMods\QMods\BetterPowerInfo

Example:

At least two users have had BetterPowerInfo installed this way.

Add support for CustomBatteries text packs

The CustomBatteries wiki mentions that you can create text files to define a custom battery pack, in a similar manner to CustomCraft, CustomPosters, etc. etc.

These text packs would live in the [...]/CustomBatteries/Packs/[pack name] folder.

At the present time, Vortex does not support CustomBatteries text packs.

It is also possible for modders to utilise the CustomBatteries API via mod code and publish as a QMod/BepInEx plugin, which Vortex should support just fine.

Investigate SML QMod installing incorrectly

A user of the Subnautica Modding discord has turned up with their QMods\Modding Helper folder completely devoid of assemblies and mod.json. Strangely, it did include generated files and folders, indicating SML was working at some point.

Example:

It is possible this was caused by user error, but also possible that Vortex the generated files are from a previous installation and Vortex failed to install SML correctly in a new installation.

No idea if this will be replicable, but it warrants investigation.

CC2 plugins pack detections

There seem to be some users turning up to the discord with cc2 plugin packs not working correctly due to the way they were packaged.

It might be worth adding a few more acceptable packaging structures (eg. If cc2 folder is nested within QMods or BepInEx\plugin)

Possibly also if there is no CC2 folder, just WorkingFiles as long as it includes only .txt files.

Maybe investigate the way cc2 .txt files are structured so we can even detect loose .txt files, similar to how we detect bepinex plugins in loose .dlls, rather than relying so much on package structure?

Extension allows users to install the macOS version of the pack and doesn't tell them anything is wrong, leading to confusion

Address this by detecting the macOS pack at installation time and cancelling the install, followed by a prompt informing them that they were attempting to install the macOS pack and guiding them on how to install the correct version.