Skip to main content

Building Your Game

It is always a great idea to incrementally build your game. In fact, make it at least a weekly habit for your project. It is also an opportunity to test your game. This is because it would be very hard to debug what's wrong with your game if some features are available on Editor but not on Build.

Build Setting / Profile​

Unity provides a very simple UI to build your game. Simply go to File >> Build Profile/Build Setting (depending on OS):

Add or Edit Scenes​

Click Open Scene List to add more scenes. Then simply drag the scenes from your Project window as follows:

Reorder Scene​

You can highlight and drag each Scene around to ensure that the order makes sense:

Build​

Finally, choose the platform that you want and click Build:

Test for Bugs​

Ensure that you have a list of features that you want to playtest with the actual build. Sometimes, things might work in the Editor but not during build. This is likely due to user error (misunderstanding).

Here are the following common issues that we have found so far. This list is not exhaustive. You are free to make a PR if you found new ones.

Assets & Build Content​

Scene not in build settings: Works when you hit Play, but SceneManager.LoadScene("X") fails in build.
Fix: Add scenes to File >> Build Settings… or load by the included build index.

Using unityeditor APIs at runtime: Any UnityEditor.* or AssetDatabase call compiles in Editor but is missing in builds.
Fix: Gate with #if UNITY_EDITOR or replace with Resources, Addressables, or serialized references.

#if unity_editor hides real load paths: Editor-only code runs correctly while the player path is broken.
Fix: Test the non editor path inside the Editor with a toggle or consolidate to one runtime safe path.

Resources or Addressables not included or not built: Resources.Load returns null or Addressables fail.
Fix: Place assets under Resources, mark Addressable, build Addressables, and verify catalog or profile URLs.

Implicit references stripped: Assets only referenced via strings or reflection are not bundled.
Fix: Keep strong references in a linker ScriptableObject or MonoBehaviour or use Addressables labels.

Tag or layer mismatches: Code checks a tag or layer that is not present in the shipped project.
Fix: Audit Project Settings >> Tags and Layers for parity.

Code & Compilation​

Managed code stripping breaks reflection: The linker removes types used via reflection, JSON, or the new Input System.
Fix: Add a link.xml, use [Preserve], or relax stripping temporarily to confirm.

Aot generics on il2cpp: Generic methods only invoked via reflection fail on iOS or consoles.
Fix: Instantiate representative generic types at compile time or keep them via link.xml.

Editor or runtime assembly leaks: A runtime asmdef references an Editor only asmdef.
Fix: Split Editor and Runtime assemblies and set Include Platforms correctly.

Editor only initialization attributes: [InitializeOnLoad] or ExecuteInEditMode logic does not run in player.
Fix: Use [RuntimeInitializeOnLoadMethod] or a bootstrap scene.

Script execution order assumptions: Editor timing masks races that appear in build.
Fix: Remove order coupling and explicitly initialize dependencies.

Domain reload differences: Static state persists between Editor plays while builds start clean.
Fix: Initialize all static fields on load and do not rely on Editor reload behavior.

File I/O & Paths​

Writing into application.datapath: This works on disk in Editor but is read only in builds.
Fix: Write to Application.persistentDataPath and ship read only files via StreamingAssets.

Loading streamingassets on android or ios: Direct File access fails because the data is inside the package.
Fix: Use UnityWebRequest or a platform correct loader for StreamingAssets.

Case sensitivity: Paths work on Windows or macOS but fail on Android or Linux.
Fix: Match filename case exactly in code and data.

Playerprefs not saved: Data appears to vanish after quit or crash.
Fix: Call PlayerPrefs.Save() at safe points.

Platform & Permissions​

Missing runtime permissions: Camera, microphone, gallery, location, or Bluetooth work in Editor but not on device.
Fix: Add iOS Info.plist usage strings and Android permissions and request them at runtime.

Http blocked by transport security: Http calls work locally while the device or OS blocks cleartext.
Fix: Use https or configure ATS on iOS or Network Security Config on Android when unavoidable.

Input system mismatch: New Input APIs are used while Player is set to the old input.
Fix: Set Active Input Handling to Both or New and regenerate actions per target.

Serialization & Data​

Non serialized fields lost: References assigned in Editor are not serialized for player.
Fix: Mark fields with [SerializeField] and validate with pre build checks.

Reflection heavy json or binaryformatter: This breaks under IL2CPP or AOT or gets stripped.
Fix: Use Newtonsoft with link.xml and [Preserve] or Unity JsonUtility with simple POCOs.

Prefab or variant drift: Built content uses a different prefab or variant than the one you tested.
Fix: Verify which asset loads at runtime and reduce hidden overrides.

Timing, Threads & Lifecycle​

Using Unity API from background threads: This sometimes works in Editor but crashes or no ops in player.
Fix: Marshal calls to the main thread using a SynchronizationContext.

Coroutine races: A faster player frame rate exposes ordering bugs.
Fix: Await explicit readiness and avoid relying on frame delays.

dontdestroyonload duplicates: Multiple singletons survive across scene loads.
Fix: Add robust singleton guards and instance handoff.

Graphics & Shaders​

Shader variant stripping: Runtime keywords are used while variants are removed in the build.
Fix: Add a Shader Variant Collection or Always Included shaders and prewarm if needed.

Mismatched graphics APIs: The Editor uses DirectX 11 while the player uses Metal, Vulkan, or OpenGL ES.
Fix: Align the target Graphics APIs and gate features per platform.

Srp asset not assigned: URP or HDRP looks fine in Editor but is broken in build.
Fix: Assign the correct Render Pipeline Asset in Graphics and Quality settings.

Tmp or fonts or materials missing: Editor auto fallbacks hide missing assets.
Fix: Include TextMeshPro resources and explicit font assets.

Networking & Backends​

Cors or webgl restrictions: Local tests pass while the browser blocks cross origin requests in build.
Fix: Configure server CORS and use https and same origin rules for WebGL.

Addressables remote content not deployed: The player cannot find the catalog or bundles.
Fix: Build and upload content for the correct profile and verify remote URLs and clear the cache.

Tls or certificate issues on device: Calls work on the dev box but fail on mobile or console.
Fix: Use valid certificate chains and avoid self signed certificates in production.

UI & Events​

Missing or multiple eventsystems: UI does not respond or behaves erratically.
Fix: Ensure exactly one EventSystem exists in the active scene.

Wrong input module: Touch and mouse differences are mishandled.
Fix: Use the correct Input System UI Input Module and test on the target device.

Canvas scaling differences: The UI looks fine in the Editor Game view but breaks on the device.
Fix: Configure the Canvas Scaler, reference resolution, and anchors for target aspects.

Build or Player Settings & Misc​

Development only flags: Code behind #if DEVELOPMENT_BUILD works in dev builds but not in release.
Fix: Do not rely on development only branches for core behavior.

Scripting define symbols mismatch: Features are compiled in Editor but not in player or the reverse.
Fix: Align Player Scripting Define Symbols per target.

Time scale or vsync differences: Editor window settings mask timing bugs.
Fix: Match device frame caps and vsync in testing.

note

Quick Pre Build Audit

  • Search for UnityEditor, AssetDatabase, #if UNITY_EDITOR, ExecuteInEditMode, and InitializeOnLoad.
  • Confirm that all loadable scenes are in Build Settings.
  • Ensure anything loaded via string or reflection is in Resources or Addressables or is strongly referenced.
  • Provide a link.xml or [Preserve] for reflection, JSON, Input System, and third party libraries.
  • Write to persistentDataPath and read packaged files from StreamingAssets using platform correct loaders.
  • Add mobile permissions and request them at runtime.
  • Align the Graphics API, SRP/URP asset, and shader variants.
  • Set Active Input Handling properly and test actions on device.
  • Initialize static state at runtime and remove execution order assumptions.
  • Use a Development Build with Script Debugging and inspect device logs.

Good luck!