Differences

This shows you the differences between two versions of the page.

--- manual:troubleshooting [2026/01/13 09:47] – created dcs
+++ manual:troubleshooting [2026/01/13 10:05] (current) – dcs
@@ Line 7: / Line 7: @@
 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.
 ----
@@ Line 24: / Line 69: @@
   * or a file name exceeds the allowed character limit
-This is a known limitation related to Unreal Engine and Windows file system path lengths.
+This issue is related to a **Windows file system limitation**.
 ----
@@ Line 30: / Line 75: @@
 ==== Possible Cause ====
-Unreal Engine (and the Automation Tool) has a **maximum path length limit**.
+Windows has a **maximum file path length of 255 characters**.
+Unreal Engine and its Automation Tool strictly rely on this limitation.
 If:
-  * the SDK is located in a deeply nested directory
+  * the Modding SDK is stored in a deeply nested directory
-  * asset folder names are very long
+  * plugin folder structures are very deep
-  * file names are excessively long
+  * asset or folder names are very long
-the combined path length can exceed the allowed limit, causing the build process to fail.
+the combined path length can exceed **255 characters**, causing the build process to fail.
 ----
@@ Line 43: / Line 90: @@
 ==== Possible Solution ====
-  * Move the Modding SDK to a directory with a **short path**, for example:
+  * Extract the Modding SDK to a directory with a **very short path**, for example:
     `C:\SubwaySimSDK\`
-  * Check your plugin folder structure for:
+  * Avoid deeply nested folder structures inside your plugin
-    * very long folder names
+  * Shorten folder and asset names where possible
-    * deeply nested directories
+  * Keep paths inside the plugin as flat and concise as possible
-  * Shorten asset names where possible
-  * Avoid unnecessary subfolder depth inside your plugin
-After reducing path and file name lengths, run **BuildMod.bat** again.
+After reducing path and file name lengths so that they remain below **255 characters**, run **BuildMod.bat** again.
-----
+{{page>manual:footer}}