00. Unity's Event Functions.md

Unity Event Functions for Application Flow

Unity provides several event functions to manage the application’s lifecycle:

1. OnApplicationFocus()

Called when the app gains or loses focus.

• Input: bool hasFocus (true = focused, false = unfocused).
• Use Case: Pause or resume real-time processes like music or updates.

2. OnApplicationPause()

Called when the app is paused or resumed.

• Input: bool isPaused (true = paused, false = running).
• Use Case: Save the game state or pause timers.

3. OnApplicationQuit()

Called when the app is about to quit.

• Use Case: Save data or send a shutdown signal to the server.

---

⚠️ Mobile-Specific Warning for OnApplicationQuit()

On desktop platforms (Windows, macOS, Linux), OnApplicationQuit() is reliably called when the app closes normally.

However, on mobile (iOS, Android):

• The OS can terminate the app at any time to reclaim resources (e.g., swiping the app away, memory cleanup).
• In such cases, OnApplicationQuit() may not be called, making it unreliable for critical shutdown logic.

Recommendation:

• Use OnApplicationPause() for saving data on mobile.
• Consider periodic autosaving or real-time syncing to ensure critical data is preserved.

GameManager.cs

using UnityEngine;

/// <summary>
/// Manages application lifecycle events such as focus, pause, and quit.
/// Ensures the GameManager persists across scenes.
/// </summary>
public class GameManager : MonoBehaviour
{
    /// <summary>
    /// Ensures the GameManager instance is not destroyed when switching scenes.
    /// </summary>
    private void Awake()
    {
        DontDestroyOnLoad(gameObject);
    }

    /// <summary>
    /// Called when the application gains or loses focus.
    /// </summary>
    /// <param name="hasFocus">True if the app is now in focus; false if it is out of focus.</param>
    private void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            HandleAppGainedFocus();
        }
        else
        {
            HandleAppLostFocus();
        }
    }

    /// <summary>
    /// Called when the application is paused or resumed.
    /// This is typically triggered on mobile when the app is minimized or restored.
    /// </summary>
    /// <param name="pauseStatus">True if the app is paused; false if it is resumed.</param>
    private void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            HandleAppPaused();
        }
        else
        {
            HandleAppResumed();
        }
    }

    /// <summary>
    /// Called before the application quits.
    /// </summary>
    private void OnApplicationQuit()
    {
        HandleAppQuitting();
    }

    /// <summary>
    /// Handles logic when the application gains focus.
    /// </summary>
    private void HandleAppGainedFocus()
    {
        Debug.Log("Application regained focus. Resuming updates, refreshing data, or unmuting sound.");
        // Implement logic for resuming app functionality.
    }

    /// <summary>
    /// Handles logic when the application loses focus.
    /// </summary>
    private void HandleAppLostFocus()
    {
        Debug.Log("Application lost focus. Pausing updates or halting time-sensitive operations.");
        // Implement logic for pausing app functionality.
    }

    /// <summary>
    /// Handles logic when the application is paused.
    /// </summary>
    private void HandleAppPaused()
    {
        Debug.Log("Application is paused. Saving state, reducing resource usage, or pausing gameplay.");
        // Implement logic for saving state or pausing processes.
    }

    /// <summary>
    /// Handles logic when the application is resumed.
    /// </summary>
    private void HandleAppResumed()
    {
        Debug.Log("Application is resumed. Restoring gameplay, refreshing data, or resuming updates.");
        // Implement logic for restoring app functionality.
    }

    /// <summary>
    /// Handles logic when the application is about to quit.
    /// </summary>
    private void HandleAppQuitting()
    {
        Debug.Log("Application is quitting. Performing final save and resource cleanup.");
        // Implement logic for final save and cleanup.
    }
}