Modding: Troubleshooting Guide

An overview of common and less common issues that can happen during the development of mods for UEBS2.

📚 Intro

This guide collects an overview of common and some less common issues that can happen during UEBS2 mod development. Please consider adding this guide to your Favorites to be able to find it again later.

If you are new to mod development, please refer to this official guide.

📚 A few recommendations upfront

• If you do 3D modelling and use Blender[www.blender.org], your model should be facing into Blender's -Y direction and Blender's Z axis should be upward. Use the latest Blender version. Use the FBX export with default settings to export models to Unity.
  
• In Unity, use "Apply Hierarchy" on imported 3D models, at least if you having problems with rotations etc.
  
• In Unity, use "SkinnedMeshRenderer" and not "MeshRenderer" for everything in UEBS2, even unorganic things like weapons etc.
  
• If you want to, use CharacterModSetup Plus[github.com] instead of the CharacterModSetup.cs from the official guide for additional features, error diagnosis and tips. Please be aware that this is not an official tool by Brilliant Game Studios.

⁉ Unit invisible / under the map in-game

A unit is visible in the customization menu, but invisible or under the map in-game.

💡 Reason 1: "All Meshes" is empty

Frequency: Common
Automated Diagnosis: 0.3Plus or newer

Check in CharacterModSetup if "All meshes" is empty, i.e., if you expand "All Meshes" it shows Size 0. You need to increase the number, then Unity will show some additional fields. Drag all meshes into the new fields. This is only possible if the meshes use "SkinnedMeshRenderer". Make sure that you forget no part at all - all parts of the unit are important!

Tip: If you use 0.3Plus or newer, use "Exchange MeshRenderers" and "Reset AllMeshes" to speed up these steps.

💡 Reason 2: Incomplete Animation Controller

Frequency: Unknown
Automated Diagnosis: None

If you are using a Custom animation set for your character, this may have this effect. Make sure that the animation clips you are using are all added to the Animator Controller.

💡 Note

• SkinnedMeshRenderers that are not added to AllMeshes will be invisible at runtime
  
• MeshRenderers (non-Skinned) will be invisible at runtime except in possession mode and customization menu
  
• SkinnedMeshRenderers added to AllMeshes will not have emission unless in customization menu (affects lightsabers etc.)

⁉ Unit does not spawn in-game

💡 Reason: Invalid name

Frequency: Rare
Automated Diagnosis: 0.3Plus or newer

In this case, the unit will not even appear in the customization menu. Check the prefab / GameObject's name. It must not contain certain characters, e.g. "AT-AT" is not permitted, while "AT AT" is okay.

⁉ No animations played in-game, only in the customization menu

💡 Reason 1: Incomplete Animator Controller

Frequency: Common
Automated Diagnosis: None

Check that your animation clips are in the animator controller. They do not need to be linked with each other via arrows, but they must be there in order to function properly.

💡 Reason 2: Using included Animations

Frequency: Common
Automated Diagnosis: None

If your animation set is set to "Common", you need to add your own animations instead of those provided by the game. Check if your animation clips are separate files and not only "in" the FBX file: expand the FBX, click on the animation file and press Ctrl+D (Duplicate) to bring the animation file outside.

💡 Reason 3: Troll animations

Frequency: Rare
Automated Diagnosis: 0.3Plus or newer

"Troll" animations do not seem to work on standard humanoid characters. You need to use another animation set.

💡 Other reasons

If none of the above things help, try this:

• Replace your custom Animator Controller by a new one in which you include the animation clips from inside the FBX. In the CharacterModSetup, point towards the animation clips outside the FBX.
  
• More on Custom Animations can be found in this forum thread.

⁉ Large unit looks weird in-game but normal in customization menu

💡 Reason: Aggressive LOD optimization by UEBS2

Frequency: Common
Automated Diagnosis: None

This probably has to do with UEBS2 automatically applied LOD system (level of detail). This means that the farther away your camera is from the model, the less detailed it is. This optimization saves enormous amounts of resources, but in this case, lower-resolution variants are displayed too early. For determining the correct LOD, UEBS2 apparently uses the size of the collider box ("Collision Width" / "Collision Height"). Make sure that your unit fits into the collider box in Unity and otherwise expand the collider box.

There is currently no definite fix to this issue. Maybe future releases of UEBS2 will allow modders to take care of LOD themselves, but this is currently not possible.

⁉ Camera not movable or otherwise unusable

💡 Reason: Camera in 3D model

Frequency: Common
Automated Diagnosis: 0.3Plus or newer

Sometimes, 3D models you download contain a GameObject "Camera". This conflicts with the game's camera if you leave it there. Remove or disable the "Camera". By the way, also delete "Sun" object if that is included in your prefab, too.

⁉ Camera "on the floor" or under the character in "possession" mode

💡 Reason: Wrong Root Node

Frequency: Unknown
Automated Diagnosis: None

Change the "Root Node" in the Character Mod Setup script. Remember that confusions with GameObjects with the same name can arise, or between "Scene" and "Project".

⁉ Character is lying on the ground animatedly but stands up when possessed

💡 Reason: Confusion with coordinate systems

Frequency: Unknown
Automated Diagnosis: None

Chances are, the coordinate systems between Unity (Y Up) and your 3D Model (e.g. Z Up) do not match. In Unity, select the 3D Model (e.g. FBX file) and activate "Preserve Hierarchy" there. Hit "Apply".

⁉ Character is halfway stuck in the ground

💡 Reason 1: Missing hierarchy level

Frequency: Unknown
Automated Diagnosis: None
The vertical offset (Y axis) in Unity is overridden by the animations. In Unity, select the 3D Model (e.g. FBX file) and activate "Preserve Hierarchy" there. Hit "Apply".

💡 Reason 2: Troll animations

Frequency: Rare
Automated Diagnosis: 0.3Plus or newer
"Troll" animations do not seem to work on standard humanoid characters. You need to use another animation set.

⁉ Animation is played too slow

The unit moves around the map, but the animations are played too slowly, like in slow motion. This can happen especially with large models, like the "AT-AT from STAR WARS".

💡 Reason: High Collision Width

UEBS2 decides how fast to play a walk/jog/run cycle based on your character's "Collision Width" setting. Setting a multiplier does not seem to fix this currently. Decreasing "Collision Width" speeds up animations but has other drawbacks.

Hack: Create a new animation and glue the walk cycle multiple times into it. E.g.: Including 2 walk cycles in 1 clip may be redundant, but will be played 2x as fast by UEBS2. You can use the same technique to increase the speed by 3x, 4x, etc.

⁉ Unit is facing up or down, lying on the floor instead of standing

💡 Reason 1: Missing hierarchy level

Frequency: Common
Automated Diagnosis: None

The vertical offset (Y axis) in Unity is overridden by the animations. In Unity, select the 3D Model (e.g. FBX file) and activate "Preserve Hierarchy" there. Hit "Apply".

💡 Reason 2: Animations not playing

If the unit is not playing animations, fixing that issue might also fix this one.

💡 Reason 3: Unapplied rotations in the 3D model

Frequency: Unknown
Automated Diagnosis: None

In a 3D program, see if there rotation values that are not 0. They should all be 0°. If not, do something like Model>Apply>Rotation in Blender. Then all rotations are 0° and the FBX exporter will work with the default settings.

⁉ Camera sometimes freezes when viewing my unit

When trying to view specific parts of my model, all animations and camera movement freezes, while time still passes and bullets still fly. My model "blocks the render thread".

💡 Reason: Negative Scales in 3D model

Frequency: Unknown
Automated Diagnosis: None

While creating or editing the 3d model, did you mirror any geometry? If so, this might be why one or multiple meshes of your character has a negative scale. Check if you have a scale of -1|-1|-1 somewhere instead of 1|1|1. In Blender, you can change this via Object > Apply > Scale. Since this flips the normals as well, you also need to flip them back via Mesh > Normals > Flip. In Unity, also change the scale in the affected parts of your prefab and do not forget its bounds (also flip signs here) - or build a completely new prefab from the 3D model.

📚 Outro

Even though downloading a 3D model from the internet and exporting it to UEBS2 might sound easy when following a tutorial, it's not always straightforward. A big shoutout to all modders! There are many factors that can cause problems, including mismatched coordinate systems, various 3D formats, inconvenient texture maps, overly complex models, custom animations, and more.

It's normal for such issues to arise and require time to resolve. Be prepared for errors, take the time to research and experiment before seeking help. If you still need assistance, consider visiting the workshop forum.

[smileAndWin]

@ben10peake: Please let us move over to this thread: https://steamcommunity.com/workshop/discussions/18446744073709551615/4632609113412526043/?appid=1468720

[ben10peake]

Found a new bug: Character is standing up on last LOD, so from a distance it looks like the character is standing up, but when you get closer, it goes back to the lying down death animation. This happens with custom and preset animations and it definitely appears to be an LOD issue.

[smileAndWin]

I just upgraded the custom CharacterModSetup script from version 0.3Plus to version 0.4Plus, reflecting the latest changes to the game.

[jamie_adam_derry]

Hey man, not sure if it's just me but your script no longer works, gives no mono behaviour every time, it used to give that if i didn't remove the plus from your file, but just downloaded it fresh and no longer has the plus in the name.

[jamie_adam_derry]

Thanks,i think i found the part in your script before i seen this, and set the installation path, but in unity it always says location isn't set, but oddly the bit you mentioned it's below (Use Ultra Low Poly Human Lod) doesn't seem to exist when searching the script.

[smileAndWin]

@jamie_adam_derry: If you are using my (modified) version 0.3Plus, you can set "Game Installation Path" inside CharacterModSetup, it is the last entry of the menu, just below "Use Ultra Low Poly Human Lod". If you are however using the original CharacterModSetup, there will be no such field and you need to copy the files manually. This is just a small convenience feature I added for my own modding projects, found it very useful.

[jamie_adam_derry]

Where do we set our game folder for the script?