====== Troubleshooting ======

This page lists common problems that may occur while working with the SubwaySim 2 Modding SDK, along with possible solutions or approaches.

<WRAP center round warning 900px>
The solutions listed on this page are **suggestions and troubleshooting approaches**.  
They may not resolve every issue, as some problems can have multiple or more complex causes.
</WRAP>

----

===== Unreal Project takes very long to load on first start =====

==== Problem ====

When opening the Modding SDK Unreal project for the **first time**, the editor takes a very long time to load or appears to be stuck indefinitely.

In some cases, it may look like:
  * the editor has frozen
  * the loading screen does not progress
  * the project is not responding for an extended period of time

----

==== Possible Cause ====

The Modding SDK is delivered **without precompiled shaders**.

This means:
  * Unreal Engine has to compile all required shaders on first launch
  * Shader cache folders and intermediate files must be generated
  * This process is **very GPU-intensive**

On systems with:
  * older graphics cards
  * slower CPUs
  * limited system resources

shader compilation can take a significant amount of time.

----

==== Possible Solution ====

  * **Wait until the shader compilation is completed**
  * Do **not** close Unreal Engine during this process
  * Monitor CPU and GPU usage to verify that the process is still active

Once the shaders are compiled:
  * the project will load normally
  * subsequent editor launches will be **much faster**

This behavior is expected and only occurs during the first startup or after major engine or SDK updates.

----

===== BuildMod.bat fails with an error =====

==== Problem ====

When running **BuildMod.bat**, the build process aborts with an error and does not complete.

A log file is created in the following directory:

`AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_5.4`

Inside the log file, an error message appears indicating that:
  * a file path is too long
  * or a file name exceeds the allowed character limit

This issue is related to a **Windows file system limitation**.

----

==== Possible Cause ====

Windows has a **maximum file path length of 255 characters**.

Unreal Engine and its Automation Tool strictly rely on this limitation.

If:
  * the Modding SDK is stored in a deeply nested directory
  * plugin folder structures are very deep
  * asset or folder names are very long

the combined path length can exceed **255 characters**, causing the build process to fail.

----

==== Possible Solution ====

  * Extract the Modding SDK to a directory with a **very short path**, for example:
    `C:\SubwaySimSDK\`
  * Avoid deeply nested folder structures inside your plugin
  * Shorten folder and asset names where possible
  * Keep paths inside the plugin as flat and concise as possible

After reducing path and file name lengths so that they remain below **255 characters**, run **BuildMod.bat** again.

{{page>manual:footer}}