description README.md

Terrain Patcher

Terrain Patcher is a Subnautica and Below Zero library mod that allows anyone to modify the game's terrain.

Terrain Patcher loads terrain patches containing terrain to replace (stored as .optoctreepatch files) and makes the game load that terrain instead of its vanilla terrain.

Installation

This mod requires BepInEx.

You can download Terrain Patcher from the releases page, below the changelog.

To install Terrain Patcher, just extract the zip file and place the TerrainPatcher folder into your BepInEx/plugins folder.

To install a .optoctreepatch file manually, place it in the TerrainPatcher/patches folder. You can also place a terrain patch anywhere in the BepInEx folder or any subfolder and it will still be loaded.

You can specify a custom load order for .optoctreepatch files by writing the file names (without the extensions) into the load-order.txt file. If you have multiple terrain patches that conflict with each other, changing the load order usually won't fix broken terrain—the terrain patches are likely just incompatible.

Game Version

Terrain Patcher aims to always support up-to-date stable versions of Subnautica and Below Zero. Older versions of these games may require using old versions of Terrain Patcher, which are unsupported. Please do not submit issues for old versions of Terrain Patcher.

Terrain Extender

Current versions of Terrain Patcher provide all the features that Terrain Extender provided and satisfy other mods' dependencies on Terrain Extender. Terrain Extender is deprecated and you should uninstall Terrain Extender if you have it installed.

Library Usage

The following is for modders who want to use Terrain Patcher in your mod. Keep in mind that if your mod uses Terrain Patcher, anyone using your mod needs to have Terrain Patcher installed to see your terrain changes.

When linking users to Terrain Patcher to install, it's recommended to either link to this readme page or directly to the releases page at https://github.com/Esper89/Subnautica-TerrainPatcher/releases. Please avoid linking directly to one specific release (unless it's releases/latest) to avoid users installing old versions of Terrain Patcher instead of the latest version.

Patch Loading

To load a terrain patch, just distribute your .optoctreepatch file alongside your mod. Terrain Patcher will find and load all .optoctreepatch files placed anywhere in the BepInEx folder or any subfolder, so you don't need to do anything else to make sure your terrain patch gets loaded.

To have Terrain Patcher ignore a directory entirely, place a file named .terrain-patcher-ignore in that directory.

Terrain Patcher also currently supports loading patches via the TerrainPatcher.TerrainRegistry.PatchTerrain method, but this method is deprecated and may be removed in a future release of Terrain Patcher.

Dependency Registration

If your mod contains terrain patches, you should add Terrain Patcher as a dependency of your mod.

If your mod requires Terrain Patcher to function, add the [BepInDependency("Esper89.TerrainPatcher")] attribute to your mod's entry point (below the BepInPlugin attribute), as shown here:

[BepInPlugin("YourName.ExampleMod", "Example Mod", "0.0.0")]
[BepInDependency("Esper89.TerrainPatcher")]
internal class Mod : BaseUnityPlugin { /* ... */ }

If your mod does not require Terrain Patcher but still uses it, add the [BepInDependency("Esper89.TerrainPatcher", BepInDependency.DependencyFlags.SoftDependency)] attribute to your mod's entry point (below the BepInPlugin attribute), as shown here:

[BepInPlugin("YourName.ExampleMod", "Example Mod", "0.0.0")]
[BepInDependency("Esper89.TerrainPatcher", BepInDependency.DependencyFlags.SoftDependency)]
internal class Mod : BaseUnityPlugin { /* ... */ }

Licensing

Terrain Patcher is licensed under the GNU AGPL, which says that derivative works must also be licensed under the GNU AGPL. If your mod directly interacts with Terrain Patcher (e.g. by referencing TerrainPatcher.dll), it might be considered a derivative work. To avoid any possible copyright issues, if your mod isn't licensed under the GNU AGPL, you should avoid referencing TerrainPatcher.dll or otherwise interacting with Terrain Patcher directly. Terrain patches are loaded without referencing Terrain Patcher by distributing them alongside your mod as separate .optoctreepatch files.

Patch Format

The Subnautica Terrain Patch Format (the optoctreepatch format) is documented in Subnautica Terrain Patch Format.pdf. The format is designed to be as similar to the game's native terrain format as possible, while still allowing for proper patching of terrain. The patch format also allows as much data as necessary to be stored in one file, for easier distribution.

An example optoctreepatch file is included at example.optoctreepatch. Patches that demonstrate all valid materials in-game can be found for Subnautica and Below Zero at material-preview-sn.optoctreepatch and material-preview-bz.optoctreepatch.

Patch files can be created using Abyss Editor or Reef Editor. Any files conforming to the specification will work. An example Rust script that generates the material preview terrain patches is included at generate_material_preview.rs.

Terrain Patcher places patched batches in CompiledOctreesCache/patches, using the same naming system as the game. These patched batches can be loaded by external tools or other mods, if they wish to support terrain patches. Anything using this feature should make it optional, as those files aren't removed when Terrain Patcher is disabled or uninstalled.

Features

Loads terrain patch files.
Replaces the terrain that loads in-game.
Supports both Subnautica and Below Zero.
Extends the edges of the world to allow for more terrain and entities.

Planned Features

Patching the in-game seaglide and scanner room maps.

Contributing

Contributions of any kind—issues, pull requests, feature requests—are all welcome. You can submit suggestions and bug reports as issues, or code contributions as pull requests.

Building

To build Terrain Patcher, run dotnet build in the project's root directory. This will build in debug mode, and the output will be placed in target/Debug. If you create a file in the project root called game-dirs and input the paths to your Subnautica and/or Below Zero installations (one per line), the output of debug builds will be automatically installed into those game directories for easier testing.

To build Terrain Patcher in release mode, run dotnet build -c Release. This will also create a TerrainPatcher.zip file in target for easy distribution.

Contributors

Esper Thomson (@Esper89)
Metious (@Metious)
Jbeast (@jbeast291)
Aerith Butler (@jonahnm)

License

This program is free software: you can redistribute it and/or modify it under the terms of version 3 of the GNU Affero General Public License as published by the Free Software Foundation.

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 Affero General Public License for more details.

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

Additional permission under GNU AGPL version 3 section 7

If you modify this Program, or any covered work, by linking or combining it with Subnautica (or a modified version of that program), containing parts covered by the terms of its license, the licensors of this Program grant you additional permission to convey the resulting work.

Subnautica-TerrainPatcher