Using the ModelReplacementSDK Unity Workflow

Requirements

• The Unity 2022.3.9f1 editor
• Git installed.
• Visual Studio or other IDE with the C# package installed
• A rigged 3D model with human shaped armature, preferably as FBX

Notes

• You will have to restart your computer after installing Git otherwise the package won't install in Unity.
• You must have the C# package installed in your IDE, otherwise you won't be able to build your mod.

Model Setup

After you have installed the unity editor and created a new 3D HDRP project, (it is important that it is HDRP) enter the package manager via the Window/Package Manager button on your taskbar. Click on the + in the upper left, and click Add package from git URL..

Enter https://github.com/BunyaPineTree/LethalCompany_ModelReplacementSDK.git#upm and click Add. This will import the ModelReplacementSDK package into your unity project.

You can now import your 3D model by dragging it into the Assets section, or any folders therein. Don't forget to fix all of its materials and textures.

After that ensure your model has a humanoid avatar by clicking on the FBX you imported in the assets section and going to the Rig tab in the inspector window.

Select the settings Animation Type: Humanoid and Avatar Definition: Create From This Model and click Apply. Finally, click Configure to enter the humanoid avatar inspector.

Ensure that all of your bones are correctly mapped to the avatar. In the Scout's case the head wasn't mapped correctly, the fingertips on the left hand were backwards, and the head needed to be tilted to eye level, which all needed to be corrected.

Additionally, ensure that your model is in a T-pose (rather than A-Pose) with palms facing downwards. Your model's rotation offsets will have a higher fidelity the closer your mode's T-Pose is to the Scavenger's.

Once finished click Apply and exit. Drag your model out of the hierarchy view back into the Assets section to create a new prefab of your model. Preparation is complete and you can now configure your model for use in ModelReplacementAPI. Select your model's prefab in the hierarchy view and click ModelReplacementSDK/Setup Model.

This will do the following

• Places a Model Replacement Properties component on your model, it can be found next to the animator.
• Places a Rotation Offset component on each HumanBodyBone on your model (these are the same bones as in your humanoid avatar) so long as it has a corresponding bone on the base game player model.
• Instantiates two different version of the base game player prefab, and a circular base and indicator to help in positioning your model.
• Rescales your model to the same height as the base game player prefab.
• Automatically sets position offset and rotation offsets for all of the human bones on your model.
• Note that due to an unknown bug it doesn't automatically set your position offset. Press Reinitialize to offset correctly, however if your model doesn't have a "Toe" bone, it still may be incorrect and need manual modification

At this point you can manually

• Set any rotation offsets that weren't automatically set well via scripts, or change your character's position offset.
• Position the item's position to be properly held in your hand. It is likely that you will have to see the results in game to fine tune this.

This can be achieved in the following ways:

• When you have the gameobject that holds the Model Replacement Properties component selected, the handles are overridden to set player model and item offsets.

  • When in position mode, you can adjust the model's positional offset and the item's positional offset.

• Item rotation offsets are currently disabled and managed via script in game. In the future we may set item specific rotation offsets for fine tuning.

• When in scale mode, you will be able to adjust your model's scale in proportion to the scavenger.

• Note that offsets can always be set manually in the ModelReplacementAPI Properties component

• To adjust bone rotation offsets, navigate to the bone you want to adjust in the Hierarchy view and rotate it with the overridden rotation handle, or set it manually in the Rotation Offset component. It is recommended that you try setting it manually, as the rotation handles are currently not functioning well.

Features of the ModelReplacementAPI Properties Component

1. Sets the position offset of your entire model with respect to the player model.
2. Sets your model scale with respect to the player model's scale.
3. If checked, this will except your model from the Lethal Company post process. This is recommended for models that utilize cell shading, as the heavy posterization used in game does not work well with cell shading.
4. this sets your item positional offset. There is no good way to see exactly what items will look like from the editor, and it is recommended that you verify this in game.
5. This is the Project Scriptable Object that handles assetbundle build locations and can generate mod files. It is recommended that you use this instead of just building an assetbundle.
6. This is the name of your prefab. This must be unique if you have multiple models in your project or assetbundle.
7. This will build your assetbundle or project.
8. This renders the player that your model is bound to. It can verify your position offset being correct.
9. This renders the held item.
10. This will reinitialize all of your offsets if something went astray.

Creating a Project

As mentioned in the previous section, it is recommended that you use a project scriptable object to handle assetbundle creation. If you currently have a working project, it will allow you to post changes to your visual studio build immediately without moving assetbundles, and if you are just starting this is the only automated way of creating a mod with ModelReplacementAPI.

First right click on the Assets section of the unity editor and navigate the menus to create your project like so. The name is not important.

This will create a scriptable object with the following properties:

1. Self explanatory. You must give your assetbundle a unique name. Unity cannot have multiple assetbundles loaded with the same name, and if you do not change your assetbundle's name then it will conflict with every other mod using the name templatebundle.
2. This is the path to your project. If you have a working mod this will be the directory your assetbundle is in, if you are generating a mod then don't worry about it, a file explorer window will open when you generate your mod where you will be able to create and select the directory.
3. This is the directory to your Lethal Company folder, and only needs to be changed if your game is not in the default C: drive. Regardless it will be requested on Build if the directory does not exist.
4. This will build your project. It will place your assetbundle at the Project Path, and generate a project if requested
5. If checked, this will generate a project on build

Using your Project

In order for a model replacement to be bound to a project it must have that project in its Project field. This can be achieved by dragging your Project Scriptable Object to the Project field of a model's ModelReplacementAPI Properties Component, like so.

This will also place your prefab in a Scene Prefabs section on your Project, which is the easiest way to identify which prefabs are bound to a project.

At this point if you have a working mod and only need to update your assetbundle all that is needed is setting the correct Project Path location and pressing Build Project

If you are just starting and wish to create a new ModelReplacementAPI mod, check the Generate New Project On Build box, and fill in the following details:

1. This is your mod's unique identifier that differentiates it from every other mod in bepinex and thunderstore. Pick something descriptive with little chance of collision, such as com.{yourName}.{yourModName}
2. This is your mod's name as it will be seen on Thunderstore.
3. This is a short description of what your mod does.
4. This allows you to choose your mod's namespace in Visual studio, however is not remotely necessary.

Once all these details are set you can click Build Project. If you haven't set a Project Path at this point it will request a path via File Explorer, and if you haven't updated your LC Path it will detect whether the standard LC Path exists, and request that you enter the correct one if it is missing.

The following files will be generated at your requested location.

You now need to go to the ModelReplacementAPI releases page, download the latest release ModelReplacementAPI.dll, and place it in your project location

Finally, double click on the .csproj file to open it in Visual Studio or your IDE of choice, and build it like below

Your mod's .dll will be copied to the Build Folder, which also contains everything else needed to create a thunderstore compliant .zip folder. Don't forget to replace icon.png and modify README.md to your liking.

Some Other Details for Larger Mods

The generated project will include a BodyReplacement class for each included prefab, but will only assign the first model to replace the default suit. It also includes basic config options for that first model. For any complex functionality like multiple model replacements or texture changes per suit, see the wiki Examples page.