Unity Performance Checklist

Main Performance Impacts to Games Built on Unity Engine
How to Make GC Events Not Cause Unity to Hiccup
Unity Specific Documentation & Resources

Main Performance Impacts to Games Built on Unity Engine

Checklist of the primary performance impacts devs encounter in Unity games:

CPU Bottlenecks

GPU Bottlenecks

Memory Bottlenecks

Large Unoptimized Assets:
- High-resolution textures, uncompressed audio files, and excessively complex 3D models directly consume vast amounts of RAM.
Memory Leaks:
- Occur when objects are no longer needed by the game but are still referenced by other parts of the code, preventing the garbage collector from freeing that memory. This leads to steadily increasing memory usage over time, eventually crashes or severe performance degradation.
- Example: Subscribing to an event but never unsubscribing when the object is destroyed, leaving a reference to the destroyed object.
Frequent Instantiation/Destruction:
- As mentioned with GC, constantly creating and destroying objects not only triggers the garbage collector but can also lead to memory fragmentation, making it harder for the system to find large contiguous blocks of memory.
Read/Write Enabled Textures/Meshes:
- If you enable the "Read/Write Enabled" option for textures or meshes in their import settings, Unity keeps a copy of the asset in both CPU (system) memory and GPU (video) memory. This effectively doubles their memory footprint, consuming unnecessary resources if you don't actually need to read or modify their data at runtime (e.g., procedurally modify mesh data, or GetPixel from a texture).
  - Tip: Disable "Read/Write Enabled" unless specifically required by your code.

Asset Loading and Streaming Delays

Synchronous Loading:

Loading large assets or entire scenes all at once (synchronously) will block the main thread and freeze the game until the loading is complete, resulting in noticeable pauses or long loading screens.

Example (Bad):

// This will freeze your game until "HeavyScene" is loaded
SceneManager.LoadScene("HeavyScene");

Example (Good):

// Loads asynchronously without blocking the main thread
StartCoroutine(LoadYourAsyncScene("HeavyScene"));

IEnumerator LoadYourAsyncScene(string sceneName) {
    AsyncOperation asyncLoad = SceneManager.LoadSceneAsync(sceneName);
    // Wait until the asynchronous scene fully loads
    while (!asyncLoad.isDone) {
        yield return null;
    }
}

Unused Assets:
- Not properly unloading assets from memory when they are no longer needed (e.g., after leaving a level) can lead to unnecessary memory consumption, potentially causing memory issues later in the game session.
- Tip: Use Resources.UnloadUnusedAssets() strategically, often after loading a new scene, but be aware it can also cause a hitch.

How to Make GC Events Not Cause Unity to Hiccup

Here's a detailed checklist of strategies to minimize or eliminate GC spikes and ensure smooth gameplay:

1. Avoid Allocations in Hot Paths (The Golden Rule)

2. Understand and Manage Coroutines

Cache WaitForSeconds, WaitForEndOfFrame, etc.:

Strategy: yield return new WaitForSeconds(X); or yield return new WaitForEndOfFrame(); inside a loop or a frequently running coroutine creates a new object every time. Instead, declare these WaitUntil or WaitFor objects as static readonly fields once and reuse them.

Example (Caching WaitForSeconds):

// Cache these objects once globally for reuse across coroutines
private static readonly WaitForSeconds _waitOneSecond = new WaitForSeconds(1.0f);
private static readonly WaitForEndOfFrame _endOfFrame = new WaitForEndOfFrame();
private static readonly WaitForFixedUpdate _fixedUpdate = new WaitForFixedUpdate();

IEnumerator MySmoothCoroutine() {
    Debug.Log("Starting smooth coroutine...");
    while (true) {
        // No new allocations for these WaitFor objects each time they are yielded
        yield return _waitOneSecond; // Reuses the cached WaitForSeconds object
        Debug.Log("One second passed.");
        yield return _endOfFrame;   // Reuses the cached WaitForEndOfFrame object
        Debug.Log("End of frame.");
        yield return _fixedUpdate;  // Reuses the cached WaitForFixedUpdate object
        Debug.Log("Fixed update.");
    }
}

// Example usage:
void Start() {
    StartCoroutine(MySmoothCoroutine());
}

3. Be Mindful of Generics and Boxing

Use Generic Collections:
- Strategy: Always prefer generic collections (List<T>, Dictionary<TKey, TValue>, HashSet<T>) over their non-generic counterparts (ArrayList, Hashtable). Non-generic collections store elements as object, which forces value types (like int, float, structs) to be "boxed" (wrapped in a new heap object) when added and "unboxed" (extracted) when retrieved, creating garbage.
- Example (Bad - Boxing with ArrayList):
```
ArrayList myList = new ArrayList();
myList.Add(10); // int (value type) is boxed into an object
myList.Add(20);
int sum = 0;
foreach (int i in myList) { // int is unboxed here
    sum += i;
}
```
- Example (Good - No Boxing with List):
```
List<int> myList = new List<int>();
myList.Add(10); // No boxing
myList.Add(20);
int sum = 0;
foreach (int i in myList) { // No unboxing
    sum += i;
}
```

Avoid Unnecessary Boxing with Value Types:

Strategy: Be cautious when passing value types to methods that expect object or when performing operations that implicitly box.

Example (Implicit boxing with string.Format in some contexts):

int health = 50;
// String.Format can sometimes cause boxing if not optimized by runtime/compiler
// It's generally better than + for complex strings but be aware.
// Less likely to cause explicit boxing in modern C# / Unity for simple cases.
string message = string.Format("Player health: {0}", health);

Example (Generally safer approach, often more readable and optimized):

int health = 50;
string message = $"Player health: {health}"; // String interpolation, often optimized

4. Optimize UI Updates

Update Text Only When Necessary:
- Strategy: Don't update myText.text every frame if the value displayed hasn't changed. Implement logic to check if the new value is different from the old one before assigning the text. (See StringBuilder example under "Minimize String Manipulations" above for combined approach).
Disable Layout Rebuilders:
- Strategy: UnityUI's layout system can be CPU-intensive. If your UI elements' sizes or positions are static, you can disable components like ContentSizeFitter, HorizontalLayoutGroup, VerticalLayoutGroup, or even the entire Canvas's CanvasScaler or GraphicRaycaster if not needed, to prevent unnecessary recalculations.
Ensure UI Elements Batch Effectively:
- Strategy: UI elements on the same canvas using the same material (e.g., same atlas texture for images, or same font for text) can be batched together by Unity's UI system, reducing draw calls. Breaking batching (e.g., by inserting elements with different materials or a Canvas within another Canvas) will increase draw calls and potentially CPU overhead.

5. Profile, Profile, Profile! (Your Best Friend)

6. Adjust Garbage Collector Settings (With Caution)

Enable Incremental Garbage Collection:
- Location: Go to Project Settings > Player > Other Settings > Optimization > Use Incremental GC.
- Strategy: When enabled, Unity attempts to spread the work of garbage collection over multiple frames by performing smaller, more frequent collections. This reduces the duration of any single GC pause, making "hiccups" less noticeable, even if the total time spent on GC might slightly increase. This is generally recommended for smoother gameplay and is often enabled by default in modern Unity versions. Only disable it if specific profiling reveals it's causing new issues in a very particular scenario.

Unity Specific Documentation & Resources

General Performance and Optimization:
- Performance and optimization
Modeling & Asset Optimization:
- Creating models for optimal performance
- Optimize Sprite Atlas usage and size for improved performance
UI Performance:
- Performance consideration for runtime UI
Rendering & Graphics Performance:
Profiling & Data Collection:
- Collect performance data
- Collect performance data introduction
- Collect performance data in Play mode
- Collect performance data on a target platform
- Collecting performance data on an Android device
- Collecting performance data on an iOS device (Note: While titled "Device Simulator for iOS", it contains a section on collecting performance data on iOS devices)
- CPU performance data
- Memory performance data
- Measure performance with the built-in profiler (Note: This refers to an older, deprecated internal profiler on iOS, but the page still contains general profiling insights)
Platform-Specific Optimizations:

drawcode/unity-performance-checklist-cpu-gpu-bound.md