Unity Workflow LibraryUWLAbout

Topic 13 · Shipping

Pitfalls: builds, editor automation & profiling

Batchmode skips, unfocused editors, rolling profiler buffers.

Markdown version

Generalized pitfalls from shipped and active projects. Record your own project's traps the same way: Keeping a project pitfall file. All entries LOCKED evidence. Status: locked (empirical, seen in shipped/active projects).

  • EXECUTEMETHOD-NEEDS-A-CLEAN-COMPILE — batchmode -executeMethod silently does not run when any package fails to compile. Check: read the log for compile errors and assert the method's own log line. Status: locked (empirical, seen in shipped/active projects).
  • UNFOCUSED-EDITOR-DOES-NOT-TICK — an unfocused Editor in Play Mode may not advance frames (Time.frameCount stays put), and script compilation requests just queue. Check: enable "run in background"/focus the Editor for automated runs; wait on a confirmed compile event. Status: locked (empirical, seen in shipped/active projects).
  • PROFILER-BUFFER-ROLLS — the Profiler keeps only a rolling window (~2000 frames); pausing Play does not pause recording, so idle editor frames evict the gameplay frames. Check: stop recording (not just Play) before reading; save captures. Status: locked (empirical, seen in shipped/active projects).
  • EDITORLOOP-IS-NOT-THE-GAME — in the Editor, EditorLoop self-time dominates frames; judge game cost by PlayerLoop, not total FPS. Check: perf claims cite PlayerLoop or a player build. Status: locked (empirical, seen in shipped/active projects).
  • SPACES-IN-PATHS-BREAK-SHELL-SWEEPS — $(find ...) word-splits folder names with spaces and checks nothing. Check: use null-delimited lists and assert a non-zero file count. Status: locked (empirical, seen in shipped/active projects).
  • RELEASE-PIPELINES-PRUNE-THEIR-OUTPUT — repeated platform exports and archives fill the build host disk. Check: the ship path deletes old exports/archives beyond N. Status: locked (empirical, seen in shipped/active projects).
  • DEVELOPMENT-PLAYERS-ARE-NOT-FOR-SHARING — a Development build carries debug symbols per assembly and a profiler listener with the build PC's address. Check: shared/test builds are non-Development unless profiling is the goal. Status: locked (empirical, seen in shipped/active projects).
  • CHECK-AND-ACTION-ARE-SEPARATE-COMMANDS — a guard ("is a compile running?") and the action it guards must not be one chained command. Check: read the guard result, then send the action. Status: locked (empirical, seen in shipped/active projects).
  • PIPELINE-EXIT-CODES-COME-FROM-THE-LAST-STAGE — tool | tail reports tail's status. Check: set -o pipefail or check the first stage's status. Status: locked (empirical, seen in shipped/active projects).
  • GREP-JSON-KEYS-NOT-WORDS — grepping a JSON status for "failed" matches "failed":false. Check: parse JSON for status checks. Status: locked (empirical, seen in shipped/active projects).
  • SERIALIZEDPROPERTY-NEXT-TRUE-WALKS-EVERYTHING — iterating SerializedObject with Next(true) over large assets enters every array element and can hold the main thread for minutes. Check: use NextVisible(false) or target properties by path. Status: locked (empirical, seen in shipped/active projects).