Resolving Android AudioTrack Driver Crashes and AdMob Thread Contention

The Android Audio Crash: During early Android playtesting on budget devices, the game would consistently freeze or crash within the first three seconds of launch. The system logs pointed to a critical hardware driver error: AudioTrack: write error -38 (Buffer Underrun / Latency Starvation).

The AdMob Thread Contention Cause: Maze Point utilizes a custom real-time audio synthesizer running on Godot's primary audio stream thread. On game startup, the Android AdMob SDK was initialized simultaneously. The AdMob initialization triggers heavy background WebView loading, network requests, and tracking setups. On budget Android devices with limited CPU cores, this massive thread load blocks the primary CPU scheduling threads, preventing the game's audio loop from filling the hardware PCM buffer in time, causing immediate driver underruns and crashes.

The Thread-Delayed Initialization Solution

To resolve this contention, we separated the initialization sequences. Instead of initializing the AdMob SDK on startup, we delay the setup until after the procedural synthesis engine has initialized its stable double-buffer loops:

# scripts/game.gd
extends Node

func _ready():
    # 1. Initialize stable procedural music first
    $ProceduralAudio.start_synthesis_loop()
    
    # 2. Delay AdMob SDK setup by 2.5 seconds to bypass thread contention
    await get_tree().create_timer(2.5).timeout
    _initialize_admob_sdk()

func _initialize_admob_sdk():
    if Engine.has_singleton("MobileAds"):
        var mobile_ads = Engine.get_singleton("MobileAds")
        mobile_ads.initialize()
        print("AdMob SDK successfully initialized after audio thread stabilization.")

Fine-Tuning Android Export Configuration

Additionally, we fine-tune the thread priorities inside the Godot export configuration settings to ensure the real-time audio thread is assigned high-priority scheduling by the Android OS scheduler:

# export_presets.cfg
[preset.0.options]
audio/thread_model=2 (Separate Audio Thread)
audio/android_audio_latency_samples=1024
audio/android_high_priority_audio_thread=true

Delaying SDK initializations by a few seconds and enabling dedicated high-priority audio threads completely eliminated Android AudioTrack starvation crashes. The game now runs smoothly on low-end hardware, with ads loading perfectly in the background after the audio engine has stabilized.