Creating a Melody's Escape 2 mod

This guide covers the creation of a Melody's Escape 2 mod via the Unity Editor

Introduction

ME2's mods add cosmetic options to the game. Currently, mod support exists for Character Skins, Hairstyles and Headphones models as well as Character Color schemes.

A mod in ME2 consists of a single Unity "Asset Bundle" prefab, exported from the Unity Editor to a .mod file.
Mod files placed in the game's mods folder are loaded dynamically at startup.

A basic understanding of Unity is required, for its Asset importing workflow and the creation of Prefabs. No programming knowledge is necessary.

If you have any questions or need help with the process, feel free to join the Melody's Escape community on Discord[discord.gg].

Required External Resources

In order to create mods for ME2, you will need to download and install the latest version of Unity 2019, as well as the provided "Modding Creation Project" for Unity that contains the necessary tools and components to create and export your mods (as well as samples).

Unity 2019.4.40f1: https://unity.com/releases/editor/whats-new/2019.4.40

ME2's Modding Creation Project for Unity: v0.2: http://www.melodysescape.com/ME2_Modding_Project_v0.2.zip

Mod Structure

A mod consists of a single GameObject that acts as an empty parent for the content, with individual mod items set as children objects.

The parent object of this mod prefab must always have the ME2Mod Component, and no other additional component.

Each child object can have one of the following mod item components (and you can add as many children per mod as you wish):

• Character Skin model: CharacterSkinItem component
  
• Hairstyle model: HairstyleItem component
  
• Headphones model: HeadphonesItem component
  
• Character Colors scheme: CharacterColorsItem component

A mod can have multiple of the same type of items (for instance multiple Character Skins), but each child object must only have one type Mod Item component per object (so you are not allowed to place a CharacterSkinItem on the same GameObject as a HairstyleItem)

For cosmetic items using 3D models, you can then add the desired MeshRenderers and SkinnedMeshRenders under the child Game Object.

Example structure:

Please note that for security and design purposes, the game will NOT allow the loading of GameObjects with Components that are not specifically white-listed. Please make sure to remove any extra components before exporting your mod (like any Animator component, or collison related ones)

3D Models: General Information

To display 3D models, ME2's mods support the static mesh MeshRenderer component, as well as the SkinnedMeshRender component attached to a Rig and deforming it accordingly (for instance a character skin)

Shaders

At load time, the game will automatically replace the Material inside each mesh components with its own version, in order to use its own Toon Lightning Shader (for technical compatibility as well as artistic consistency).
The texture specificed in the material will be kept, as long as it was named "_MainTex" in its original shader (the standard naming convention in most Unity shaders)

Outline Effect

This shader comes with a stylistic outline by default, using the Inverted Hull method (displaying back faces of a mesh scaled accross their normals).
This outline method works great with curved meshes, but it will not have good results with rectangular meshes.
If you would like to disable this outline effect, you can do so on a per-mesh basis by simply adding the "DisableOutline" component to the Mesh game object.

It is recommended for instance to disable the outline for meshes on the inside of clothes if the model already has a regular mesh for the outside.

Color Mask

The Toon Shader comes with 2 variation: one displaying the regular texture colors, and a special one that will dynamically replace the colors by using a color mask, to allow the player to switch between different Character Colors palettes in the Customization menu.

The Color Mask shader of ME2 will automatically replace the primary color channels from your texture with the active Character Color Palette.

• Red channel: replaced with Skin color
  
• Green channel: replaced with Cloth color
  
• Blue channel: replaced with Hair color (dynamic)

Feel free to mix the values between each others to create interesting variations. The Mod Creation Project comes with a helpful texture with many different mixes and gradient to use, for you to UV map your models with.

Cloth Physics

ME2 uses the popular "Dynamic Bone" third-party Unity Asset to provide simple cloth physics for any SkinnedMeshRenderer.
For licensing reasons, this asset is not allowed to be provided with the Mod Creation Project, so you are unfortunately not able to preview its effect at creation time in the Unity Editor, but you can still add support for the functionality on your models and the game will apply the correct cloth physics when loading your mod.

To add this feature, simply navigate to your rig armature hierarchy and select the desired rig bone parent game object, then add a "Dynamic Bone Settings" component to it.
This Dynamic Bone Settings is a simple description of the settings that the game will need to use when loading your mod.
Please be mindful that the resulting Dynamic Bone will affect the entire chain of bones starting from the selected rig game object.

You can add multiple Dynamic Bone Settings components per model, on different parent bones. While there isn't a budget limit yet, it is very likely that this feature will have some sort of limit in the future to limit performance impact in case it's been mis-used, so please try to stay reasonable if you would like your mod to keep functioning in future updates.

Here is a look at the component in Unity:



The first settings have an optional Distribution Curve that you can add. This curve will change the value from the bones chain start up to its end. It's usually not needed in the majority of cases.

• Damping: the friction force applied to the bones to slow down their movement over time. Recommended values: from 0.01 to 0.3.
  
• Elasticity: the amount of force applied to the bones to make them go back to their initial position/shape. Recommended values: from 0.1 to 0.3.
  
• Stiffness: the amount of force required to start moving the bones. Recommended values: from 0 to 0.1
  
• Wind Impact: this is a multiplier value of the wind resulting from Melody's movement. The faster she moves, the more forces will be applied from the air friction. A value of 0 is equivalent to a car wind screen in front of Melody. You can go above 1 if you would like to exaggerate the impact of movement speed on the bones chain. Recommended values: 1
  
• Radius: The radius of the sphere collision bounds for the bones of the chain.
  
• Gravity: The constant gravity force applied to the bones. For best effect, especially for hairstyles, it is recommended to avoid using this force and instead to model meshes in a resting position as if it was affected by gravity (instead of horizontal behind the head), as it is difficult to balance this force correctly for a realistic looking effect. Recommended values: 0 in most cases, and -0.05 to -0.1 for Y value if you need to apply vertical gravity
  
• Collision Mask: Here you can select which body parts of the Character the bones in your chain will collide against. Please keep in mind that this collision check is not very accurate, and can easily lead to janky results. Every collision check impacts performance, so please limit the collision targets to a strict minimum.

Character Skin

Unity component: CharacterSkinItem

A Character Skin in ME2 consists of a valid Humanoid rig.
The game does NOT support non-humanoid rigs.



Thanks to the Unity animation retargeting system, all the in-game animations will be automatically retargeted to your character without any required changes on your end or need to provide your own animations.

• Use Color Mask: check this box if you would like your 3D model to use the Character Colors from the Customization menu.
  
• Avatar: the Unity Avatar used by your Humanoid Rig must be selected in this field
  
• Model Axis Rotation Offset: This optional rotation offset is useful to fix 90 degrees angle differences introduced by some 3D modelling software (due to left-handed/right-handed and Reference Axis differences). If your character is rotated incorrectly in game, try the following value for Rotation Offset: x: -90; y: 90; w: 0
  
• Hand IK Strength: The strength of the Inverse Kinematics used on your character's left hand during Walking Mode, to place the hand model in the correct position to grab note bubbbles. Do make sure to test in-game that the hand placement in Walking mode is correct.
  
• Colliders Settings: Under this section you can individually configure the collision bounding circles for each body parts, in case you need to adjust the default boundary values to fit your character. This collision data is only use by the "Dynamic Bones" simulations.

Hairstyle and Headphones support

By default, Character Skins that you create will not display the Hairstyles and Headphones from the Customization menu.
You can easily add support for each of them individually by simply placing an empty game object(s) in the armature rig hierarchy, as child objects below the "Head" bone.

Then, add the following Unity Components on each GameObject:

• HairstylePivot component
  
• HeadphonesPivot component

Each of those 2 game objects will act as "pivot" attachment points to indicate to the game where to place the hairstyle and headphones models.
You can use their Position parameter to offset the hairstyle/headphones to fit your character model correctly.

Here is an exemple of where to place those pivot GameObjects in the hierarchy:

Hairstyle

Unity component: HairstyleItem

Use Color Mask: check this box if you would like your 3D model to use the Character Colors from the Customization menu.

Headphones

Unity component: HeadphonesItem

Use Color Mask: check this box if you would like your 3D model to use the Character Colors from the Customization menu.

Character Colors

Unity component: CharacterColorsItem

This component is very simple, you just need to specify a skin color and a cloth color. Any in-game models using the "color mask" technique will then be able to use those colors dynamically.

While selecting colors, it is important to keep in mind that game applies a strong post-processing graphical filter at runtime for artistic purposes that greatly enhances the color brightness and saturation, to give the game its unique art style.
Therefore the base colors that you select when configuring this component should be much darker than your end goal.

In the following example, the "Cloth Color" will appear almost white in-game (those are the default Melody colors)


This post-processing filter is always active in the test scene provided in the Modding Unity Project, so feel free to test how your color would render in-game by adding a 3D cube in the scene and changing its Material color.

Track Colors

Unity component: TrackColorsItem

While selecting colors, it is important to keep in mind that game applies a strong post-processing graphical filter at runtime, for artistic purposes, that greatly enhances the color brightness and saturation, to give the game its unique art style.
Therefore the base colors that you select when configuring this component should be much darker than your end goal.
If you are familiar with Unity, the Modding Project comes with this Post-Processing effect enabled by default on the test scene, so you can test the colors on your own (for instance on a dummy cube and your own testing Material)

The "Dark" part of the sky refers to its top color, and the "Light" part at the bottom. The game will create a gradient between both colors.

Obstacle Colors

Unity component: ObstacleColorsItem

With this component you can create your own Color Theme for Obstacles.

• A, X, Y, B refer to their corresponding XBOX gamepad buttons
  
• "Intense" color refers to solid obstacles in Intense mode, that require direction inputs
  
• The "PSX" color is a special palette swap for the "Square" button for players using the "Playstation" gamepad input mode in the Gamepad Settings. If you are creating your own theme, it is a good idea to turn this feature ON and OFF to test it before releasing your theme, as not all players are using the default XBOX input mode.

Exporting your Mod

In order to export your mod, you first need to mark your ME2Mod parent GameObject as a Unity Prefab.
Only the content in that Prefab will exported, not the values set on any GameObject in the Scene Hierarchy of the test Unity Scene.

Then select that prefab in the Assets Browser (not the scene list!), and assign a new Unity Asset Bundle name to that prefab, ending the name in ".mod".

The game only supports one Prefab ME2Mod per .mod file, please make sure to use a new assetbundle name for each .mod if you are creating multiple ones.

You can then begin the Export Process by clicking the ME2 Modding menu in the Unity menu bar and selecting "Build AssetBundles".



Once the building process is successful, all your mods will be exported inside the following subfolder of the ME2 Modding Project:

\Assets\StreamingAssets\ExportedMods\

You only need the .mod files, you can ignore the auto-generated Unity .meta file.

In order to load your exported mods in Melody's Escape 2, you need to place them in the following user folder (paste this path inside Explorer's address bar):

%UserProfile%\AppData\LocalLow\Icetesy\Melody's Escape 2\Mods\

You always need to restart the game to apply any changes to .mod files.

Uploading on the Steam Workshop

This functionality will be available in the upcoming v0.6.0 patch!

Once your mod is finished and correctly loading in game, you can upload it to the Steam Workshop directly from the game's interface (not from Unity!).

Go to the Customization menu, and press the Q key.

This will bring you to the Mod Upload menu, where your own mods will be listed, ready for upload. Only valid mods are listed.
If you've added a new mod file while the game was already running, you need to restart the game.

If you would like to provide a thumbnail for your Workshop Submission (which is strongly recommended), simply place a PNG square image file inside the Mods folder where you've placed your .mod file, and name it with the exact same name as your .mod file but ending in .png instead.
This thumbnail file needs to be smaller than 1MB.

Once you are ready, press the "Upload to Workshop" button.
You can make future updates to your mod by going to the same menu and using the "Update" button (but make sure to restart the game after any .mod change!)

Troubleshooting

If your mod isn't loaded when launching Melody's Escape 2, the first step is to check the Unity generated Player.log text file.

You can find this file at the following path:

%UserProfile%\AppData\LocalLow\Icetesy\Melody's Escape 2\Player.log

Any error will be documented and will help you troubleshoot the problem.

The most common issue that will block your mods from being loaded are optional non-whitelisted Unity Components left on your GameObjects, like an Animator component. In such cases, the log file will document every problematic component and affected gameobjects.

F.A.Q.

Why do I need to use Unity to create mods?
The main advantage of using Unity is the ability to use its Animation Retargeting system with its Humanoid Avatar support for characters.
Thanks to this Unity's feature, Melody's in-game animations will seamlessly adapt to any humanoid 3D model that you provide. As a mod creator, this means that you don't have to create dozens of custom animations each time that you create a character skin, significantly reducing the workload required the create a mod.

Using Unity also greatly streamlines the modding creation process, as well as the import of 3D models, at the cost of having to learn some basics of using Unity.

How can I peek inside a .mod file to check its content?
If you would like to peek inside a .mod AssetBundle, you can use Unity and download the official Asset Bundle Browser package, but the use of this optional tool is outside the scope of this guide. I recommend the Youtube video "Unite Austin 2017 - Using the New Asset Bundle Browser & Graph Tool" on the subject.