diff --git a/docs/Mod-Creation/Assets/Character.md b/docs/Mod-Creation/Assets/Character.md index 4d493c6f..8187a339 100644 --- a/docs/Mod-Creation/Assets/Character.md +++ b/docs/Mod-Creation/Assets/Character.md @@ -1,16 +1,22 @@ # Character -[Rob's character template, called HenryTutorial](https://github.com/ArcPh1r3/HenryTutorial), is the recommended method of adding a custom survivor as it is the most up to date and involves the least amount of jank. +## Henry Tutorial +[Rob's character template, called HenryTutorial](https://github.com/ArcPh1r3/HenryTutorial), is the recommended method of adding a custom survivor as it is the most up to date, and most complete. It does its best to abstract as much as possible under the hood that you don't have to worry about. +## Thunderkit. +If you are more Unity-minded, and would like to get your hands dirty with the nitty gritty of creating characters, Thunderkit may be for you. +Currently, no such template like the Henry Tutorial exists for Thunderkit, but that isn't to say it is impossible. Reach out in the modding discord for help along the way. +- [See here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Unity-Editor-Usage/ThunderKit/Crash-Course-and-Getting-Started/) to get started with thunderkit. +- RoR2EditorKit has a wizard for easily creating a CharacterBody. + - Provided your Thunderkit Import went smoothly and you have RoR2EditorKit installed, go to the toolbar at the top, and hit `Tools/RoR2EditorKit/Wizards/Character Body` -[ThunderHenry](https://github.com/Vale-X/Thunderkit-Henry) is another template, which utilize Thunderkit, even though that template is mostly complete too, be warned though as most people who made a custom character used the regular HenryTutorial rather than this project, so getting help from other may be more difficult. +[ThunderHenry](https://github.com/Vale-X/Thunderkit-Henry) was a Thunderkit-oriented version of the henry template, but it is currently out of date. It does however, have a good wiki of general RoR2 information that applies to any character, which we have yet to move to this wiki. +## Before You Begin If you are newer to modding, then I recommend that you start out just working on the skills before you work out anything relating to custom models or animations. Doesn't matter if your character is a commando clone, so long as they're fun to play. To this end you should check out the [custom skills page on the wiki](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Assets/Skills/) since this will give you a working template that's a little more simple to understand than the full character template. It's a good place to start before you move on to a fully fledged character mod. -Additionally, if you have all of your skill states in their own .cs files, then when it's time to switch templates it will be as easy as dragging the files from one project to the other. - -Another thing to note, rob uses a different method of asset bundle embedding than the [current recommended way, which is to just put the assets next to the .dll file (instead of embedding the assets directly in the .dll)](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Assets/Loading-Assets/). If you are unfamiliar with loading from stream, then feel free to replace the entirety of the assets static class in robs template with the method that's on the wiki (just make sure to use the same variable names). \ No newline at end of file +Additionally, if you have all of your skill states in their own .cs files, then when it's time to switch templates it will be as easy as dragging the files from one project to the other. \ No newline at end of file diff --git a/docs/Mod-Creation/C#-Programming/Using-MonoBehaviour-Scripts-in-Editor.md b/docs/Mod-Creation/C#-Programming/Using-MonoBehaviour-Scripts-in-Editor.md deleted file mode 100644 index d423fa62..00000000 --- a/docs/Mod-Creation/C#-Programming/Using-MonoBehaviour-Scripts-in-Editor.md +++ /dev/null @@ -1,76 +0,0 @@ -MonoBehaviours are components that are attached to Unity GameObjects and perform various functions. See our article about them [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/C%23-Programming/Unity-and-MonoBehaviour/), and see Unity documentation about them [here](https://docs.unity3d.com/Manual/ScriptingImportantClasses.html) - -MonoBehaviours are most commonly used in prefabs, created in the Unity Editor. From here, this article will assume you know how to create prefabs, attach scripts to them, and build those prefabs into assetbundles. See [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Assets/Loading-Assets/) -to learn how to load those assetbundles into your mod. - -If you are creating and loading prefabs for use in your mod, you have the ability to attach any of the game's MonoBehaviours, and any custom MonoBehaviours that you want to write as well. Refer to the respective sections on how to do each. - -## Using RoR2 MonoBehaviours -There are two ways to use RoR2 scripts - -### Option 0: AddComponent -Possibly the simplest way is to simply call AddComponent in your code at runtime. - -This works perfectly fine, but does not scale. It can easily become tedious to the point of limiting. - -### Option 1: Dummy Scripts -Preferred if you are only using a few scripts - -1. Create a script with the same name and namespace as an existing RoR2 script -2. fill this script out with any Serialized Fields in the script that you want to use in editor. - - this includes any any `public` field, and any field with the `[SerializedField]` attribute - -That's it. pretty simple, but this doesn't really scale. You will have to do this with *every* script you want to use in editor. -Consider the next option if you want to use many RoR2 scripts. - -### Option 2: Importing all RoR2 scripts -Preferred if you are using many RoR2 scripts, namely if you are creating projectiles. - -If you are currently creating your mod in code, and only using Unity to build assetbundles, you can use ThunderKit to import the RoR2 codebase into your unity project, and you will have access to all unity components. After which, you can return to buliding your mod in code as before. - -This will take some setup, but if you are using components a lot, and if you want to work with projectiles, it is definitely worth it. - -If you are creating a character using the Henry Template, refer to [this article](https://github.com/ArcPh1r3/HenryTutorial/wiki/Using-RoR2-Scripts-in-Unity-Editor-(Thunderkit-Import)). - -1. [Here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Thunderkit/Getting-Started/) is a video guide on how to import thunderkit into unity. -1. Once RoR2 is imported, you can build your assetbundle and continue building your mod in code like normal. You don't have to worry about the other thunderkit-specific stuff, unless you want to go that route. - -#### If you are working with other people or in any case uploading your mod on github, make sure you .gitignore the RoR2 package. Otherwise, you are redistributing game assets and that's a big no-no. - -### Option Bonus: Just Use Thunderkit -If you are more unity-minded, Thunderkit is an mod creating workflow where everything is in editor. - -All objects, code, and mod creation happens in one place and you can simply attach any scripts as normal, RoR2 or custom, so you may be interested in that. However, it is not recommended for beginners, as it requires familiarity with unity, ror2, and thunderkit itself. -See [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Thunderkit/Getting-Started/) to get started, and if you run into any issues pursuing this, reach out in the modding discord. - -## Using Custom MonoBehaviours -If you try to write a component, attach it to your prefab, and build your bundle, the game will not recognize it. There are a few options to accomplish this - -### Option 0: AddComponent -Possibly the simplest way is to simply call AddComponent in your code at runtime. -This works perfectly fine, but does not scale. It can easily become tedious to the point of limiting. - -### Option 1: Dummy Scripts -Any MonoBehaviour in your mod code can be attached to a prefab in unity. - -1. Create a script with the same name and namespace as your MonoBehaviour class in your mod - - You can likely just copy the whole code over, but if you can't, you only need the class name and any serialized fields you want to use in editor. - - this includes any any `public` field, and any field with the `[SerializedField]` attribute -2. Put this script in a folder in your Unity project -2. Right click and create an Assembly Definition in this folder, with the same name as the .csproj of your mod - -Now you can attach this script to your prefab and the game will recognize it. Have fun assigning things in the inspector instead of having to call AddComponent a million times! - -Note: If your code runs into errors because it references other RoR2 code, you will have to have that code in your project as well. Follow the RoR2 section below to find out how to do this. - -### Option 2: Whole Assembly in Unity -You can just take your whole mod dll and slap it in your unity project. -To do this, you will need to use Thunderkit to add RoR2 and all other dependencies of your mod to your unity project. - -In my experience, this just ended up slowing down my development, compared to Option 1. If you are considering this option because you are using a ton of components, it may be time to pursue a thunderkit setup - -### Option 3: Just Use Thunderkit -If you are more unity-minded, Thunderkit is an mod creating workflow where everything is in editor. - -All objects, code, and mod creation happens in one place and you can simply attach any scripts as normal, so you may be interested in that. However, it is not recommended for beginners, as it requires familiarity with unity, ror2, and thunderkit itself. -See [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Thunderkit/Getting-Started/) to get started, and if you run into any issues pursuing this, reach out in the modding discord. diff --git a/docs/Mod-Creation/IDE/Visual-Studio/Post-Build-Events.md b/docs/Mod-Creation/IDE/Visual-Studio/Post-Build-Events.md index 71a27c69..96a977b7 100644 --- a/docs/Mod-Creation/IDE/Visual-Studio/Post-Build-Events.md +++ b/docs/Mod-Creation/IDE/Visual-Studio/Post-Build-Events.md @@ -10,7 +10,7 @@ The language for these events is [Batch](https://en.wikipedia.org/wiki/Batch_fil > If you are running into issues due to macros being empty. Feel free to hop into the discord and ask Paddywan or ping Harb. We'll share your pain and hopefully be able to tell you how to remedy it. -### Copy output DLL +## Copy output DLL Most commonly used is the copy command to get your dll to where you want it. ```batch copy @@ -18,12 +18,14 @@ copy copy /Y "$(TargetPath)" "$(SolutionPath)Builds\" ``` Let's go over the arguments individually -* `copy` signifies a copy instruction. It takes two arguments: what to copy and where to copy it to. -* `/y` is a flag for the copy instruction to suppress the prompting if you want to overwrite the destination file. -* `"$(TargetPath)"` is a macro to the output dll produced by building the project. See **macros** at the end of the page. -* `"$(ProjectPath)Builds\"` is a folder named Builds right next to your `.sln` file. This is especially useful if you want to have folder containing all latest builds of your mods contained in your solution. +- `copy` signifies a copy instruction. It takes two arguments: what to copy and where to copy it to. +- `/y` is a flag for the copy instruction to suppress the prompting if you want to overwrite the destination file. +- `"$(TargetPath)"` is a macro to the output dll produced by building the project. See **macros** at the end of the page. +- `"$(ProjectPath)Builds\"` is a folder named Builds right next to your `.sln` file. This is especially useful if you want to have folder containing all latest builds of your mods contained in your solution. -### External Programs +Use `xcopy` to copy a folder if your mod requires multiple files. + +## External Programs If you have external files or programs you want to run, simply provide the absolute path to run it, followed by any arguments that you might need it. ```batch [program] arg1 arg2 etc @@ -42,7 +44,18 @@ del temp.txt ``` Afterwards you can use this variable in commands by using `%VARNAME%`, in the example's case, this would be `%COOLDLL%`. -### Conditionals +### UNetWeaver +Possibly the most common example of an external program would be the use of Unity's UNetWeaver for networking. [See this page](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/C%23-Programming/Networking/UNet/) to learn more. + +If you are using a .bat file, make sure you `call` it before you perform other post build actions in your IDE, or the post build will for some reason stop at the .bat +```batch +call weaver.bat + +copy /Y "$(TargetPath)" "$(SolutionPath)Builds\" +rem the rest of your commands +``` + +## Conditionals Batch has `for, if` and probably more go google! Batch does not have conditional operators, but there are some implementations for `or` and `and` @@ -64,7 +77,7 @@ if %a% == 1 ( ) ``` -# Macros +## Macros * `$(OutDir)` is the folder to which your dll is outputted. This path ends in a `\`. * `$(ConfigurationName)` is the configuration under which you've chosen to build under. By default this is set to "Debug", and a "Release" configuration is available. **NOTE:** sometimes this does not work and you need to use `$(Configuration)` instead. * `$(ProjectName)` is the name of your project. @@ -77,6 +90,4 @@ if %a% == 1 ( * `$(SolutionFileName)` is the filename of your [solution](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solutions-overview), which contains all your projects. this file usually ends in in `.sln`. * `$(SolutionPath)` is the absolute path to your solution file. Ending in `.sln`. * `$(SolutionName)` is your solution name, excluding the `.sln` part. -* `$(TargetExt)`, `$(ProjectExt)`, and `$(SolutionExt)` will likely be `.dll`, `.csproj`, and `.sln` respectively. - - \ No newline at end of file +* `$(TargetExt)`, `$(ProjectExt)`, and `$(SolutionExt)` will likely be `.dll`, `.csproj`, and `.sln` respectively. \ No newline at end of file diff --git a/docs/Mod-Creation/Thunderkit/Using-Scripts-with-Assetbundles.md b/docs/Mod-Creation/Thunderkit/Using-Scripts-with-Assetbundles.md deleted file mode 100644 index 58c1ae62..00000000 --- a/docs/Mod-Creation/Thunderkit/Using-Scripts-with-Assetbundles.md +++ /dev/null @@ -1,220 +0,0 @@ -# Using Scripts with Assetbundles - -## TODO FIXME : JUST REWRITE THAT WHOLE THING: USE THUNDERKIT AND EITHER USE THE ASMDEF WORKFLOW AND USE THE UNITY EDITOR COMPILER / OR SHOW HOW TO IMPORT YOUR C# PROJECT DLL ASSEMBLY IN YOUR UNITY EDITOR PROJECT DRAG AND DROP AND REFER THE SCRIPTS FROM THAT ASSEMBLY DIRECTLY - -_(WIP)_ - -Tutorial on how to use custom scripts in AssetBundles. - -## Before you start -* ### [First Mod](https://github.com/risk-of-thunder/R2Wiki/wiki/First-Mod) - -Read up on how to create a BepInEx plugin as we will be utilizing one. - -## Tools -* **Unity** -* **AssetBundle Browser** - Built in unity package - -## Building the ExamplePlugin -Example classes of the plugin we will be using ==> - -* **ExamplePlugin.cs** : _This is our plugin class._ -```cs -using BepInEx; -using UnityEngine; -using RoR2; -namespace ExamplePlugin -{ - //BepInEx plugin information - [BepInPlugin("com.examplemodder.exampleplugin", "ExamplePlugin", "1.0")] - - //make sure this inherits BaseUnityPlugin otherwise BepInEx will not recognize this. - public class ExamplePlugin : BaseUnityPlugin - { - //our elevator prefab - private GameObject _elevatorprefab; - //the player's character master - private CharacterMaster _playerMaster; - - public void Awake() - { - //get location of the plugin - string pluginfolder = System.IO.Path.GetDirectoryName(GetType().Assembly.Location); - - //asset bundle to load - string assetBundle = "myelevator"; - - //prefab location inside asset bundle - string prefab = "assets/prefabs/MyElevator.prefab"; - - //load assetbundle then load the prefab - _elevatorprefab = AssetBundle.LoadFromFile($"{pluginfolder}/{assetBundle}").LoadAsset(prefab); - - //start listening for onPlayerAdded - PlayerCharacterMasterController.onPlayerAdded += OnPlayerAdded; - } - - public void OnPlayerAdded(PlayerCharacterMasterController playerCharacterMasterController) - { - //no longer need to listen for any other player masters, we just need one player. - PlayerCharacterMasterController.onPlayerAdded -= OnPlayerAdded; - - //Listen for the creation of the player body - playerCharacterMasterController.master.onBodyStart += OnBodyStart; - } - - public void OnBodyStart(CharacterBody body) - { - //check if master exists - if (body.master) - { - //grab our master - _playerMaster = body.master; - - //remove listener onBodyStart - body.master.onBodyStart -= OnBodyStart; - } - } - - public void Update() - { - //listen for user input "1" - if (Input.GetKeyDown(KeyCode.Alpha1)) - { - //Check to see if the player body exists. - if (_playerMaster) - { - //get player position - Vector3 playerPosition = _playerMaster.GetBodyObject().transform.localPosition; - - //create new instance of prefab "MyElevator(Clone)" - GameObject newElevator = GameObject.Instantiate(_elevatorprefab); - - //example of accessing child component - ElevatorHandler elevatorComponent = newElevator.GetComponentInChildren(); - - //set new instance of prefab to playerPosition - newElevator.transform.localPosition = playerPosition; - } - } - } - - } -} -``` - -* **ElevatorHandler.cs** : _This is our elevator component which is in charge of moving it around._ - -```cs -using System; -using UnityEngine; -namespace ExamplePlugin -{ - [Serializable] - public class ElevatorHandler : MonoBehaviour - { - [Header("ElevatorHandler Example Component")] - [Space] - [Header("!!!Position of this GameObject will reset to zero, keep this GameObject Nested!!!")] - [Space] - - [Tooltip("ElevatorConfig Prefab")] - public ElevatorConfig elevatorConfig; - - - //what direction are we moving in? - [UnityEngine.HideInInspector] - public bool isMovingFoward; - - //additive position modification - private Vector3 _velocity; - - //max distance can travel - private float _max_distance; - - //used as reference when calculating distance. - private static Vector3 _zero = new Vector3(0, 0, 0); - public void Awake() - { - //check if Config Exist - if (elevatorConfig) - { - _velocity = elevatorConfig.elevatorVelocity; - _max_distance = elevatorConfig.maxDistance / 2; - } - //otherwise set default config - else - { - _velocity = new Vector3(0, 0.3f, 0); - _max_distance = 25; - } - //set default position - this.transform.localPosition = _velocity * -_max_distance; - - //set moving direction - isMovingFoward = true; - - Debug.Log("New Elevator Created!"); - } - - public void Update() - { - //check what direction it is traveling - //then apply the velocity to the position - if (isMovingFoward) - this.transform.localPosition += _velocity; - else - this.transform.localPosition -= _velocity; - - //check distance traveled - if (Vector3.Distance(_zero, this.transform.localPosition) > _max_distance) - //if traveled too : far flip directions! - isMovingFoward = !isMovingFoward; - } - } -} -``` -* **ElevatorConfig.cs** : _This is the elevator config template file_ -```cs -using UnityEngine; -namespace ExamplePlugin -{ - public class ElevatorConfig : ScriptableObject - { - [Header("ElevatorConfig Template File")] - - [Tooltip("The velocity of which this travels")] - public Vector3 elevatorVelocity; - - [Tooltip("The max distance allowed to travel")] - public float maxDistance; - } -} -``` -### !!! Build these files into a BepInEx Plugin !!! - - -# Steps -* Start up a project in unity to be the base of your asset bundle. - -* Create a Folder called Scripts - -* Create a Assembly Definition - -* In the Assembly Definition that you just created change the 'Name' to your plugin Assembly, In this example it is "TutorialExample" - -* Drag the scripts you want to use in the AssetBundle over to this Folder - -* Click on one of your scripts and you will see that it will be referring to your assembly file. - -* Create a prefab , in this case I created a parent GameObject with a child called Platform. - -* In the prefab I placed my Monobehaviour as a component in the Platform. - -* Open up AssetBundle Browser and Drag your prefab into a new bundle - -* Build your bundle and copy it over to your plugin folder. - -* Run your plugin and see if it works... - -* Congrats! you learned how to create asset bundles with scripts, go make something crazy. \ No newline at end of file diff --git "a/docs/Mod-Creation/Unity-Editor-Usage/ThunderKit/Thunderkit-\342\200\220-using-the-DOTS-framework-in-Modding.md" "b/docs/Mod-Creation/Unity-Editor-Usage/ThunderKit/Thunderkit-\342\200\220-using-the-DOTS-framework-in-Modding.md" index ea60e390..0c90e8c2 100644 --- "a/docs/Mod-Creation/Unity-Editor-Usage/ThunderKit/Thunderkit-\342\200\220-using-the-DOTS-framework-in-Modding.md" +++ "b/docs/Mod-Creation/Unity-Editor-Usage/ThunderKit/Thunderkit-\342\200\220-using-the-DOTS-framework-in-Modding.md" @@ -10,4 +10,114 @@ The DOTS framework is built on three key pillars, of which 2 are accessible and | Burst Compiler | Burst is a compiler that can be used alongside the Job system to create code that improves performance by translating your IL/.Net bytercode into native CPU code using the LLVM compiler. | Available, known method via Unity and ThunderKit | | C# Jobs | Allows you to create multithreaded code for performance intensive tasks, such as multiple transform modifications, complex mathematic operations and more. Has built in guard rails for development of safe multithreaded code | Available | -This guide will not cover how to use the Burst Compiler or how to Write C# jobs, it'll only cover how to get access to the framework on a ThunderKit context and how to compile your mod \ No newline at end of file +This guide will not cover how to use the Burst Compiler or how to Write C# jobs, it'll only cover how to get access to the framework on a ThunderKit context and how to compile your mod + +## Burst and Jobs in RoR2 + +Utilizing Jobs is an already by default implemented feature of the current unity version, however, We've made the mod [BurstsOfRain](https://thunderstore.io/package/RiskofThunder/BurstsOfRain/) for the purposes of extending the development potential by including extra libraries for running burst compiled Jobs and access to improved Native Collections such as Native Lists, Native Hash Maps and more. + +![image](https://github.com/user-attachments/assets/5adb67af-82f7-46a6-90bf-d5fa2f7b8832) + +Bursts of Rain is a thunderstore package that contains a lightweight assembly that can be used for loading burst-code assemblies, however, it also comes with re-distribution of specific unity DLL's that are loaded which can be used in jobs. + +| Redistributed Assembly | Description | Version | +|--|--|--| +| System.Runtime | Required for the collections package. | Not Applicable | +| [Unity.Burst](https://docs.unity3d.com/2021.3/Documentation/Manual/com.unity.burst.html) | The runtime front-end of the Burst compilation system, this runs the bursted code when applicable. | 1.8.18 | +| [Unity.Collections](https://docs.unity3d.com/2021.3/Documentation/Manual/com.unity.collections.html) | A package that contains multiple, thread safe, native collections that can be used within jobs, such as Lists, Queues, Hashmaps and more. | 1.5.1 | +| [Unity.Mathematics](https://docs.unity3d.com/2021.3/Documentation/Manual/com.unity.mathematics.html) | A light-weight math library with a shader-like syntax which can be safely used within jobs. | 1.2.6 | + +As a note, it is _**NOT**_ recommended to install Bursts of Rain directly with the ThunderKit package manager for the following reasons: + +* Unity will not recognize the redistributed unity assemblies, this is an intentional feature. +* You'll have to manually install the selected versions of Burst, Collections and Mathematics. +* The collections package has a dependency on Mono.Cecil, which makes modding difficult. + +For these reasons, this guide will cover installing Bursts of Rain using the [RoR2 Thunder Burster](https://github.com/risk-of-thunder/RoR2ThunderBurster) package. + +## Installing RoR2 Thunder Burster + +It is recommended to do a full game re-import once the package is installed. to do this, select all folders within your project's Packages folder (``ProjectRoot/Packages``) except for ``manifest.json`` and ``packages-lock.json``. and Delete the folders. + +![image](https://github.com/user-attachments/assets/2e09eed6-4032-420d-b9a0-bfaa4c0f23ec) + +1. Go to ``Window/Package Manager`` to open the Unity Package Manager + +![image](https://github.com/user-attachments/assets/46ac15bd-6def-4221-a3dc-f6df50c74ade) + +2. Go to the [RoR2ThunderBurster Repository](https://github.com/risk-of-thunder/RoR2ThunderBurster). Taking a look at the website you can see a big green ``<> Code`` button. Clicking it and then clicking the copy url button will copy the link to the repository. + +![image](https://github.com/user-attachments/assets/71d65b39-4efe-498c-99a4-b3602e2f5f39) + +3. On the Package Manager window, hit the ``+`` button, and click the ``Add package from Git URL...`` option + +![image](https://github.com/user-attachments/assets/7562cea9-2d0a-4bc1-84e7-2f4ba00d2159) + +4. Paste the git URL copied beforehand. As a side note, it is recommeneded to install only the latest tagged release from the repository. To install a specific release tag, append the Tag's name preceded by a ``#`` character. + +For example, to download the version 0.0.2 of RoR2 Thunder Burster to your project, you must use the git url ``https://github.com/risk-of-thunder/RoR2ThunderBurster#0.2.2`` + +![image](https://github.com/user-attachments/assets/0c6b43e8-2b4f-4346-89bc-5fcb866ba88c) + +5. Once installed, you may get a popup regarding missing dependencies, clicking on "Install All" will install all the listed packages. it may take a while for the editor to finish installing your dependencies. + +![image](https://github.com/user-attachments/assets/13074990-6be5-45fd-a05c-dd46d58b28a9) + +6. You may stumble upon this popup once the packages are installed, click "Ok" to proceed. If this popup does not appear or your project ends in an invalid state, refer to the next section. + +![image](https://github.com/user-attachments/assets/ad657793-7f92-4d0b-9942-17b219bfc473) + +7. Open the ThunderKit settings window, and go to the import config, you may notice that a new import step for installing Bursts of Rain has appeared, reimport your game and youre ready to go. + +![image](https://github.com/user-attachments/assets/c5e3db64-cdd2-4487-875d-83af2156f731) + +### Project Troubleshooting + +If you installed RoR2ThunderBurster after you've imported the game your project might end up in an unstable/unusable state, this is because the Collections package comes with an explicit dependency to Mono.Cecil, which gets installed and conflicts with our BepInEx mono.cecil assemblies. To fix this, you can do the following steps. + +1. Go to ``ProjectRoot/Library/PackageCache`` find the folder ``com.unity.collections@1.5.1`` + +![image](https://github.com/user-attachments/assets/d7d60e7c-5dd0-4371-b463-c828beaf8c00) + +2. Copy this folder and paste it on ``ProjectRoot/Packages`` and remove the substring ``@1.5.1``, this Embeds the package into your project and can now be modified. + +![image](https://github.com/user-attachments/assets/e3f2168f-783f-455c-81ba-a855e823eda9) + +3. Download this [Zip](https://github.com/user-attachments/files/17710219/com.unity.collections.zip) file, which contains modified files. Open the zip file and drag all its contents inside the ``com.unity.collections`` folder. Replace all files. + +![image](https://github.com/user-attachments/assets/848289e3-d98f-4061-9ec3-d743374ecf47) + +4. Your project should be back to an usable state, if not, ask for help in the RoR2 modding community's ThunderKit channel. + +## Using RoR2 Thunder Burster + +RoR2 Thunder Burster consists of 2 new Compossable Objects added. + +| Compossable Object | Compossable Type | Description | +|--|--|--| +| BurstAssemblyDefinitionsDatum | Manifest Datum | A subclass of the AssemblyDefinitions Manifest Datum, it's used by the following pipeline job to burst the specified assemblies using the Burst compiler. | +| BurstStagedAssemblies | Pipeline Job | A custom pipeline job, that takes the main manifest's BurstAssemblyDefinitionsDatum and bursts the defined assemblies. | + +Begin by modifying your manifest and replacing it's "Assembly Definitions" datum for the "Burst Assembly Definitions Datum". You can lick on the cogwheel next to the manifest datum to remove it. + +![image](https://github.com/user-attachments/assets/a141c91e-2d26-43e4-a96e-d734628f762a) + +To burst your assemblies, add the Burst Staged Assemblies pipeline job to your build pipeline, this pipeline job should run **_After_** Stage Assemblies. It also contains a field that you must assign the previously executed Stage Assemblies job. this is used to obtain necesary metadata for the burst compiler to work. + +![image](https://github.com/user-attachments/assets/2f3a6d20-5cf0-4b89-8372-a846c3b76c6f) + +Executing your pipeline will build your assembly, and then burst said assembly thru the burst compiler. The bursted assemblies will be staged on the same folder as your Assembly. + +![image](https://github.com/user-attachments/assets/7b6a4787-81bf-4c73-b46d-e779435b6a42) + +## Enabling your assembly ingame + +To enable your assembly ingame, add a Precompiled Assembly Reference to Bursts of Rain. + +![image](https://github.com/user-attachments/assets/22d432a2-45e9-46be-ae95-6f2635605a27) + +Somewhere during your mod's initialization routine, you can utilize the main class of Bursts of Rain for loading your bursted assembly. Here it's being done in my mod's Awake call. + +![image](https://github.com/user-attachments/assets/c27a8cfe-242f-465e-903e-7017b93ee19c) + +Your bursted assembly is now loaded at runtime, and burst-compiled jobs will be used instead of their native C# jobs. \ No newline at end of file diff --git a/docs/Mod-Creation/Unity-Editor-Usage/Using-MonoBehaviour-Scripts-in-Editor.md b/docs/Mod-Creation/Unity-Editor-Usage/Using-MonoBehaviour-Scripts-in-Editor.md new file mode 100644 index 00000000..bacd4d89 --- /dev/null +++ b/docs/Mod-Creation/Unity-Editor-Usage/Using-MonoBehaviour-Scripts-in-Editor.md @@ -0,0 +1,107 @@ +MonoBehaviours are components that are attached to Unity GameObjects and perform various functions. See our article about them [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/C%23-Programming/Unity-and-MonoBehaviour/), and see Unity documentation about them [here](https://docs.Unity3d.com/Manual/ScriptingImportantClasses.html) + +MonoBehaviours are most commonly used in prefabs, created in the Unity Editor. From here, this article will assume you know how to create prefabs, attach scripts to them, and build those prefabs into assetbundles. See [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Assets/Loading-Assets/) +to learn how to load those assetbundles into your mod. + +If you are creating and loading prefabs for use in your mod, you have the ability to attach any of the game's MonoBehaviours, and any custom MonoBehaviours that you want to write as well. Refer to the respective sections on how to do each. +___ + +## Using RoR2 MonoBehaviours + +### Option 0: AddComponent +Possibly the simplest way is to skip the editor and simply call AddComponent in your code at runtime. + +This works perfectly fine, but does not scale, and doesn't take advantage of the editor. It can easily become tedious to the point of limiting. + +### Option 1: Dummy Scripts +Preferred if you are only using a few scripts + +#### Steps +1. Create a script with the same name as an existing RoR2 script. +1. Open this script, and make sure it has the same namespace as the in-game script you want to use. +2. Copy over any Serialized Fields in the script that you want to use in editor. + - For example, for the class `RagdollController`, a script like this will suffice: + ``` + namespace RoR2 + { + public class RagdollController : MonoBehaviour + { + public Transform[] bones; + + public MonoBehaviour[] componentsToDisableOnRagdoll; + } + } + ``` +3. You can now attach it to your prefab and assign fields in editor. +When built into an assetbundle and loaded into the game, RoR2 will recognize this script as its own. + +That's it. pretty simple, but this doesn't really scale. You will have to do this with *every* script you want to use in editor. +Consider the next option if you want to use many RoR2 scripts. + +### Option 2: Importing all RoR2 scripts +Preferred if you are using many RoR2 scripts, namely if you are creating projectiles. + +If you are currently creating your mod in code, and only using Unity to build assetbundles, you can gain access to all of the RoR2 components by importing the game into your project. +#### Notes +- This process uses Thunderkit, as it was built to do this, however you don't have to fully move to the thunderkit workflow of creating mods. You can continue creating your mod in code, and building your assetbundle as before. +- This will take some setup, but if you are using components a lot, and if you want to work with projectiles, it is definitely worth it. +- If you are creating a character using the Henry Template, refer to [this article](https://github.com/ArcPh1r3/HenryTutorial/wiki/Using-RoR2-Scripts-in-Unity-Editor-(Thunderkit-Import)). + +#### Steps +1. [See this guide](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Unity-Editor-Usage/ThunderKit/Crash-Course-and-Getting-Started/) all about how to create mods with thunderkit +1. Skip to steps 4 and 5 if you're not pursuing a full thunderkit setup. More on this below. +1. If you're building your mod in code, you may disable the following steps in the import process: + - MMHook Generator + - Ensure RoR2 Thunderstore Source + - Install Bepinex + - R2API Submodule Installer + - Install RoR2MultiplayerHLAPI + +#### If you are working with other people or in any case uploading your mod on github, make sure you .gitignore the RoR2 package. Otherwise, you are redistributing game assets and that's a big no-no. +Add this to the .gitignore: +``` +#RoR2 Packages Folder +Packages/Risk of Rain 2 +#ThunderKit root folder & Logs +ThunderKit/ +Assets/ThunderKitSettings/Logs/ +``` +### Option 3: Just Use Thunderkit +If you are more Unity-minded, Thunderkit is a mod creating workflow where everything is in editor. + +All objects, code, and mod creation happens in one place and you can simply attach any scripts as normal, RoR2 or custom, so you may be interested in that. However, it is not recommended for beginners, as it requires familiarity with Unity, ror2, and thunderkit itself. + +See [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Unity-Editor-Usage/ThunderKit/Crash-Course-and-Getting-Started/) to get started, and if you run into any issues pursuing this, reach out in the modding discord. +___ + +## Using Custom MonoBehaviours +If you try to write a component, attach it to your prefab, and build your bundle, the game will not recognize it. There are a few options to accomplish this + +### Option 0: AddComponent +Possibly the simplest way is to skip the editor and simply call AddComponent in your code at runtime. + +This works perfectly fine, but does not scale, and doesn't take advantage of the editor. It can easily become tedious to the point of limiting. + +### Option 1: Dummy Scripts + +1. Create a script with the same name and namespace as your MonoBehaviour class in your mod + - You can likely just copy the whole code over, but if you can't, you only need the class name and any serialized fields you want to use in editor. +2. Put this script in a folder in your Unity project +2. Right click and create an Assembly Definition in this folder, with the same name as the .csproj of your mod + +Now you can attach this script to your prefab and the game will recognize it. Have fun assigning things in the inspector instead of having to call AddComponent a million times! + +Note: If your code runs into errors because it references other RoR2 code, you will have to have that code in your project as well. Follow the RoR2 section above to find out how to do this. + +### Option 2: Whole Assembly in Unity +You can just take your whole mod dll and slap it in your Unity project. +To do this, you will need to use Thunderkit to add RoR2 and all other dependencies of your mod to your Unity project. + +In my experience, this just ended up slowing down my development, compared to Option 1. If you are considering this option because you are using a ton of components, it may be time to pursue a thunderkit setup + +### Option 3: Just Use Thunderkit +If you are more Unity-minded, Thunderkit is a mod creating workflow where everything is in editor. + +All objects, code, and mod creation happens in one place and you can simply attach any scripts as normal, RoR2 or custom, so you may be interested in that. However, it is not recommended for beginners, as it requires familiarity with Unity, ror2, and thunderkit itself. + +See [here](https://risk-of-thunder.github.io/R2Wiki/Mod-Creation/Unity-Editor-Usage/ThunderKit/Crash-Course-and-Getting-Started/) to get started, and if you run into any issues pursuing this, reach out in the modding discord.