Skip to content

troubleshooting.md

Latest commit

 

History

History
159 lines (90 loc) · 5.92 KB

troubleshooting.md

File metadata and controls

159 lines (90 loc) · 5.92 KB
Raw

Troubleshooting

Compile errors on import

Symptom: Unity Console shows compile errors immediately after import.

Cause Fix
Existing code using Arish.RA namespace Replace using Arish.RA; with using RuntimeAtlas; and using Arish.RA.Editor; with using RuntimeAtlas.Editor;. See the Upgrade Guide.
Duplicate assembly definition from a prior import Delete Assets/RuntimeAtlas fully before re-importing. Do not merge old and new packages.
Unity version below minimum Runtime Atlas requires Unity 2021.3 LTS or later.

Window does not appear

Symptom: Tools Studio → Runtime Atlas menu is missing, or clicking Open has no effect.

  1. Confirm import completed with zero compile errors. Errors prevent [MenuItem] attributes from registering.
  2. Force a recompile: Assets → Reimport All, or delete Library/ and reopen the project.
  3. Confirm RuntimeAtlas.Editor.asmdef exists at Assets/RuntimeAtlas/Editor/RuntimeAtlas.Editor.asmdef.

IMGUI layout errors in Console

Symptom: Console shows EndLayoutGroup: BeginLayoutGroup must be called first or InvalidOperationException: Stack empty, pointing to AtlasWindow.OnGUI.

Cause: In v1.1.0 and earlier, a module's DrawGUI() could open IMGUI layout groups and then throw before closing them, corrupting the layout stack.

Fix: Resolved in v1.2.0. DrawActiveTabSafely now wraps each module in a BeginVertical/EndVertical buffer and calls GUIUtility.ExitGUI() on exception. Upgrade to v1.2.0 or later.

Missing script warnings in demo scene

Symptom: Yellow warning triangles on demo scene GameObjects; The referenced script (Unknown) on behaviour is missing in the Console.

Cause: Occurred in v1.0.0 due to an incomplete .meta file for a multi-class demo behaviour file.

Fix: Resolved in v1.1.0. Delete Assets/RuntimeAtlas fully before re-importing if upgrading from v1.0.0.

ExecuteMenuItem console error (Add Component button)

Symptom: Console shows ExecuteMenuItem target for Scripts does not exist when clicking + Add Component in the Inspector tab.

Cause: Occurred in v1.0.0 on Unity 6. The Component/Scripts menu path was removed in Unity 6.

Fix: Resolved in v1.1.0. Upgrade to v1.1.0 or later.

Console tab shows no messages

Symptom: The Console tab shows No messages captured yet during active Play Mode.

Explanation: The Console tab captures only messages beginning with [RA], [Runtime Atlas], or [RuntimeAtlas]. It does not mirror all Unity Console output.

To emit a capturable message:

Debug.Log("[RA] My diagnostic message");
Debug.LogWarning("[Runtime Atlas] High GC alloc detected");

Stats bar shows zero cameras or sources

Symptom: Stats bar shows Cameras: 0 or Sources: 0 during Play Mode.

Cause: Components instantiated via prefab or inactive at the first poll cycle may not be counted immediately.

Fix: Wait one to two frames after Play Mode entry. Ensure cameras and audio sources are active before entering Play Mode.

Profiler flags every frame as slow

Symptom: All frames in the Profiler tab are flagged regardless of actual FPS.

Cause: SlowFrameThresholdMS is set below the target frame time.

Fix: Open Edit → Project Settings → Tools Studio → Runtime Atlas and increase SlowFrameThresholdMS. Default is 33.3 ms (30 FPS target). For 60 FPS: 16.7 ms. For 120 FPS: 8.3 ms.

Report export fails or produces an empty file

Symptom: Clicking Export produces no file, an empty file, or logs an error.

  1. Click Generate Preview before Export. Export operates on the preview snapshot, not live data.
  2. Choose a writable destination. Avoid Program Files, system-protected paths, or paths with non-ASCII characters on Windows.
  3. Check the Unity Console for the specific IO error.

Mixer tab shows no parameters

Symptom: The Mixer tab is empty or prompts to configure a mixer.

Cause: No AudioMixer with exposed parameters has been configured.

Fix: Run the auto-config utility:

Tools Studio → Runtime Atlas → Auto-Config Audio Mixer

Or configure a mixer manually. See Audio Mixer Setup.

Build fails with Runtime Atlas editor types

Symptom: Player build fails with errors referencing RuntimeAtlas.Editor types.

Cause: A custom .asmdef references RuntimeAtlas.Editor, which is editor-only.

Fix:

  1. Locate every .asmdef in your project that references RuntimeAtlas.Editor
  2. Ensure those assemblies have Editor listed under Platforms, or remove the reference if not needed
  3. Editor-only assemblies must only be referenced by other editor-only assemblies

First-run dialog appears on every launch

Symptom: The Runtime Atlas installed dialog appears on every Unity startup.

Cause: The RuntimeAtlas.Upgrade.1.0.0.EditorUX EditorPrefs key is not persisting.

Fix: If UserSettings/EditorUserSettings.asset is excluded from version control, EditorPrefs keys will not persist across sessions. Ensure that file is not forcibly cleared by your VCS setup.

Input does not work in demo scene

Symptom: Pressing H or T in the demo scene has no effect.

Cause Fix
Game view does not have focus Click the Game view before pressing keys
Legacy Input Manager not configured Set Project Settings → Player → Active Input Handling to Input Manager (Old) or Both
New Input System not installed Install com.unity.inputsystem via Package Manager

RADemoInputCompat checks the Input System first (via reflection) and falls back to legacy input. Either backend works.

Getting further help

  • Discord — #runtime-atlas channel
  • Purchase or licensing issues: contact support through the platform you purchased from