Guide:Modding

*Please note: this is an incomplete guide, as modding is still very new. Please allow time and do your own research in addition to following this guide. Our discord is a great place to talk to others!*

Modding in *BONELAB* uses the MarrowSDK, a Unity software development kit published on GitHub.

## Prerequisites

* Latest version of Git (install before Unity or Unity Hub)
* General understanding of Unity Engine and how to maneuver/operate it (many tutorials are available online on YouTube)
* Unity Hub (strongly recommended and free)

## Setup

### Git Installation

Install Git from `git-scm.com/download,` ensuring you download the latest version. Do this *before* installing Unity.

### Unity Installation

1. Install Unity 2021.3.5f1. Do this either from the Archives tab of Unity. It is recommended you also download the Unity Hub, which makes it easier to download Unity and its packages. If you already have Unity Hub installed, copy this into a browser to automatically install: `unityhub://2021.3.5f1/40eb3a945986`
2. When installing, ensure that you also install the following modules from the list:
	1. **Android Build Support** and its subitems:
		1. **Android SDK & NDK Tools**
		2. **OpenJDK**
	2. **Windows Build Support (IL2CPP)**

### Creating a Project

1. Once Unity 2021.3.5f1 and its modules are installed, open it and create a new 3D (URP) project. If building for Quest 2, select `File -> Build Settings -> Android -> Switch Platform.`
2. Upon entering the Unity Editor, delete the Global Volume and Main Actor gameobjects from the hierarchy. Then, go to Window -> Package Manager and install the following GIT packages. Be very careful when copypasting these URLs, as any leading or trailing spaces will cause the package install to error. Be sure to update these packages in the Package Manager if required or prompted. If this is your first time installing git packages, your firewall may prompt you.
	1. `https://github.com/StressLevelZero/Custom-RenderPipelineCore.git`
	2. `https://github.com/StressLevelZero/Custom-URP.git#Bonelab`
	3. `https://github.com/StressLevelZero/MarrowSDK.git`
3. Once all three packages are installed, close Package Manager and return to the Unity Editor. You should notice a new tab in the toolbar, titled Stress Level Zero. Select it, and choose Void Tools -> Validate Marrow Project Settings. A window will pop up with several errors - select Fix All.
4. Once the project is repaired, you are ready to start building!

## Pallets & Crates

***Important: Read this to understand how modding works with MarrowSDK!***

Each MarrowSDK mod is a separate Unity project that is structured into a single 'Pallet' that can contain one or many 'Crates' of various types. Each mod should contain only one Pallet, but Pallets can refer to the contents of other Pallets through dependencies. It is recommended to create a Pallet as the first step when beginning a new mod project.

Essentially, a Pallet is the mod, comprising various Crates, which is the content of the mod, such as new items.

###  Pallets

To create a Pallet:

1. Select `Assets → New Pallet`

1. Fill out the `Pallet Title` and `Pallet Author` fields and select `Create`.
2. The Pallet will appear in the MarrowSDK `Asset Warehouse` (Select `Stress Level Zero` -> `Void Tools` -> `Asset Warehouse` if the Asset Warehouse is not visible.)

###  Crates

Each Crate holds a single object of a specific type:

* Spawnable: A weapon, an enemy NPC, a destructible box, etc.
* Avatar: A properly rigged player model that changes the appearence, strength and size of the player.
* Level: The Unity Scene containing the geometry, materials, sounds, lighting, triggers and events that comprise the environment.

To create a Crate:

1. Select the `Pallet` in the Asset Warehouse window.
2. In the Unity Inspector for the Pallet, click the `Add Crate` button.
3. In the "Create Crate" window that appears, set the `Crate Type` to the type of item you want to create using the pulldown menu (See: Types of Crates for more information), then set the `Asset Reference` to the appropriate prefab (Avatar or Spawnable types) or Unity scene file (Level type).
4. The `Crate Title` will auto-fill with suggested information but can be renamed, if desired.
5. Click `Create`

### Types of Crates

* Spawnable Crate
* Avatar Crate
* Level Crate

## Avatars

This section is TBD, see this official wiki page for more info.

## Spawnables

This section is TBD, see this official wiki page for more info.

## Maps

This section is TBD, see this official wiki page for more info.

## Coding

Code modding is not officially supported at this time, check back later for more info.

## How To

This section covers a lot of miscellaneous useful information for modding.

###  How To Use BONELAB Assets

You may have noticed that as of right now, the assets used in *BONELAB* are not available to place in your mod. To use vanilla assets, you will need to import it as a pallet. Click this link to install the pallet, or go to `https://cdn.discordapp.com/attachments/1024985393902387251/1025712365108461608/Pallet_SLZ.BONELAB.Content.json.`

Once the file is installed, open your project and go to Stress Level Zero -> Void Tools -> Import Pallet. Choose the .json file you just downloaded.

Now it's time to implement. In the Content Browser, go to \_MarrowAssets -> Pallet Dependencies -> SLZ.BONELAB.Content. Here, you'll find all the items in BONELAB, in the form of crates.

To add these items to your scene, create a new empty GameObject and add the Spawnable Crate Placer script to it. This essentially sets up the object. Then, in the Spawnable Crate Reference, add the crate of your choice. Ignore the VOID warning.

###  How To Build for Quest 2

Aside from optimizing your mods to run on quest, building your mods to be compatible is actually quite easy. All you need to do is go to `File > Build Settings > Android` and select `Switch Platform`, then you should be good to go!

## Finding Mods

Mods can be found on various websites.

For normal players who don't understand Unity, coding, or don't want to go through the trouble of surfing the web, you can find even more mods on the BONEWORKS/BONELAB Discord Server. There are tons of mods that are already released and thousands of mods being worked on. There is also a way of getting in the server through the game by going to the mods section in the lab.

## Trivia

* The VOID model that shows is a reference to the Source Engine, which had an identical error model that displayed ERROR in shiny red text.