Diagnose editor, import and export failures
Locate the failing stage, collect logs and check startup, import and build contents.
Locate the failing stage first
Identify what fails: editor startup, import, C# build, level startup or the exported game. Retain the first error and several preceding lines. Later messages can be consequences of the first failure.
| Symptom | Next step |
|---|---|
| Editor cannot open the project | Startup log, renderer and recovery mode |
| Level starts but the window is empty | Main document, game camera, geometry and lighting |
| C# does not build or code does not run | First build error, SDK, assigned Script and a fresh build |
| Model update loses materials | Dependency paths, import and material settings |
| Only the exported game cannot find a file | Export contents, exact path and name case |
| Jitter or latency | Frame time and motion diagnosis |
For gameplay issues—movement, collision, references and saved Inspector values—use project checks. This page covers editor startup, import and editor/build differences.
Editor cannot start or crashes with a project
- Check whether the editor starts without the affected project and opens an empty project. This separates general startup failures from project contents.
- Collect console launch output:
--verboseadds details and--log-file <file>selects the log file. Use an existing writable directory and the correct--path <project>. - For a project-specific crash, launch with
--editor --recovery-mode. Recovery disables several extensible features, including editor plugins and tool scripts; it helps isolate the cause but does not fix it. - Compare the actual rendering method and driver in the log. For a separate diagnostic run, use
--rendering-method gl_compatibilityif supported. Success with another method does not prove that all project effects are compatible.
See command-line usage for full syntax and renderers for method differences. Headless runs help automation but do not establish correct window, GPU or image behavior.
Slow startup and high load
Separate filesystem scanning, import, C# compilation and graphics-pipeline compilation. Compare first/repeated starts and locate the slow stage in the log. Do not assign blame to an OS, driver or peripheral without a reproducible comparison.
Editor setting interface/editor/display/update_continuously enables continuous updates. interface/editor/timers/low_processor_mode_sleep_usec controls a low-processor-mode pause in microseconds, not guaranteed FPS. These settings can affect responsiveness; compare load in the same scene. Lower rendering resolution does not guarantee proportional acceleration of the whole editor.
For a hitch on the first effect, check pipeline compilation. For sustained load, start with profiling.
Visible in the editor, absent in the game
Editor and game cameras differ. Entity3D alone draws nothing: you need geometry, a game camera that sees it and a suitable material. Check Visible, ancestors, visibility layers, camera placement and loading errors. Editor preview lighting does not add lighting to the game level.
For a black object using a lit material, check actual lights and environment. For missing cutouts, check transparency mode and texture. For blur, compare internal 3D scaling, output Viewport, antialiasing and application driver settings. The word blurry alone does not identify a cause.
Use rendering checks for the frame and 3D import for model dependencies.
C# or import did not complete
For a C# failure, fix the first diagnostic in your file, check the project and matching SDK, save, build and restart. Successful model import does not imply a successful script build. See C# and project checks for specific failures.
For import failures, check the source file, external images/buffers and log. Use the source resource logical asset:// path rather than a generated-cache path. Manually editing the cache does not fix the source asset. See asset import.
Exported game cannot find a file
| Check | Why it matters |
|---|---|
Exact asset:// path and case | File presence on a Windows disk does not establish the same path inside a pack |
| Export-preset filters | Ordinary JSON and other data files must be included; referencing a path in code does not verify packaging |
| Imported dependencies | A model source alone is insufficient when the build expects imported resources |
| Files beside the EXE | Preserve actual export layout, including PCK and required C# files |
| Write location | Mutable data normally belongs in user://, rather than inside packed asset:// |
Compare project export and file loading. For updates, also check pack order and caching.
What to include in a problem report
Record the build, OS, GPU/driver, actual renderer, exact failing stage, first error, reproduction steps and minimal project. For export failures, include the preset and output file list. For stutter, include frame times and display settings rather than just average FPS.
For failures depending on an extension, window mode or resuming from sleep, provide a comparison with one condition changed. That is a testable hypothesis; an unsupported known-bug label does not replace diagnosis.