Engine.cs

using Gondwana.Configuration;
using Gondwana.Drawing;
using Gondwana.Drawing.Direct;
using Gondwana.Drawing.Sprites;
using Gondwana.Extensibility;
using Gondwana.Input.Gamepad;
using Gondwana.Input.Keyboard;
using Gondwana.Input.Mouse;
using Gondwana.Input.Touch;
using Gondwana.Logging;
using Gondwana.Rendering;
using Gondwana.Rendering.Backbuffers;
using Gondwana.Timers;
using Microsoft.Extensions.Logging;
using Timer = Gondwana.Timers.Timer;
 
namespace Gondwana;

public sealed class Engine : IDisposable
{
    #region static members
 
    private static readonly Lazy<Engine> _instance = new(() => new Engine());

    public static Engine Instance => _instance.Value;

    public static ILogger<Engine> Logger => EngineLogger.GetLogger<Engine>();
 
    #endregion
 
    #region private fields
 
    private long _startTick;
    private long _lastCPSSamplingTick;
    private long _lastBackgroundTick = HighResTimer.GetCurrentTick();
    private long _lastForegroundTick = HighResTimer.GetCurrentTick();
    private long _lastCycleTick = HighResTimer.GetCurrentTick();
    private readonly FixedStepAccumulator _timerDrivenSteps = new();
    private long _timerDrivenForegroundAccumulatedTicks;
    private long _lastTimerDrivenForegroundDriverTick;
    private int _timerDrivenForegroundTargetFps;
    private bool _isTimerDriven;
 
    private long _grossCyclesThisMeasure = 0;
    private long _netCyclesThisMeasure = 0;
    private double _grossCPS = 0;
    private double _netFPS = 0;
 
    private Task? _cycleTask;
    private IEngineConfigurationStore? _configurationStore;
    private bool _deferredDisposeScheduled;
 
    #endregion private fields
 
    #region events

    public event Action? PreInitialization;

    public event Action? PostInitialization;

    public event Action? InitializationComplete;

    public event Action? BeforeBackgroundTasksExecute;

    public event Action? AfterBackgroundTasksExecute;

    public event Action? BeforeFrameRender;

    public event Action? AfterFrameRender;

    [Obsolete(
        "Legacy CPS/FPS notifications are deprecated. Use Engine.Profiler for runtime telemetry; ProfilerWidget provides an optional in-game display.",
        DiagnosticId = "GOND0001")]
    public event Action<CyclesPerSecondCalculatedEventArgs>? CPSCalculated;

    public event Action? Disposing;

    public event Action? Disposed;
 
    #endregion events
 
    private readonly Diagnostics.TelemetrySource _engineTelemetry;

    public Diagnostics.RuntimeProfiler Profiler { get; } = new();
 
    private Engine()
    {
        _engineTelemetry = Profiler.RegisterSource("Engine", "Core")!;
        _engineTelemetry.Define("cycle.cpu.ms");
        _engineTelemetry.Define("background.cpu.ms");
        _engineTelemetry.Define("foreground.cpu.ms");
    }
 
    private volatile bool _isInitialized = false;
    private volatile bool _isInitializing = false;
    private readonly ManualResetEventSlim _initDone = new(false);

    public void Initialize(
        string? configFileName = null,
        bool? autoSaveConfig = null,
        IKeyboardAdapter? keyboardAdapter = null,
        IMouseAdapter? mouseAdapter = null,
        ITouchAdapter? touchAdapter = null,
        IGamepadManager<IGamepadAdapter>? gamepadManager = null)
        => InitializeCore(
            configFileName,
            autoSaveConfig,
            keyboardAdapter,
            mouseAdapter,
            touchAdapter,
            gamepadManager,
            configurationStore: null);

    public void InitializeWithConfigurationStore(
        IEngineConfigurationStore configurationStore,
        bool? autoSaveConfig = null,
        IKeyboardAdapter? keyboardAdapter = null,
        IMouseAdapter? mouseAdapter = null,
        ITouchAdapter? touchAdapter = null,
        IGamepadManager<IGamepadAdapter>? gamepadManager = null)
    {
        ArgumentNullException.ThrowIfNull(configurationStore);
 
        InitializeCore(
            configFileName: null,
            autoSaveConfig,
            keyboardAdapter,
            mouseAdapter,
            touchAdapter,
            gamepadManager,
            configurationStore);
    }
 
    private void InitializeCore(
        string? configFileName,
        bool? autoSaveConfig,
        IKeyboardAdapter? keyboardAdapter,
        IMouseAdapter? mouseAdapter,
        ITouchAdapter? touchAdapter,
        IGamepadManager<IGamepadAdapter>? gamepadManager,
        IEngineConfigurationStore? configurationStore)
    {
        if (_isInitialized || _isInitializing)
            return;
 
        // reset in case this instance has been initialized before
        _initDone.Reset();
 
        _isInitializing = true;
        try
        {
            if (UiDispatcher == null)
                PreInitialization?.Invoke();
            else
                UiDispatcher!.Post(() => PreInitialization?.Invoke());
 
            try
            {
                _configurationStore?.Dispose();
            }
            catch (Exception ex)
            {
                Logger.LogError(ex, "Error saving the engine configuration during initialization.");
            }
 
            _configurationStore = configurationStore ?? EngineConfigurationFile.Load(configFileName, autoSaveConfig);
            if (configurationStore is not null && autoSaveConfig.HasValue)
                _configurationStore.AutoSave = autoSaveConfig.Value;
 
            Configuration = _configurationStore.Configuration;
 
            ConfigureLogging(Configuration);
 
            if (Configuration.StateFiles?.Any() ?? false)
            {
                foreach (var stateFile in Configuration.StateFiles)
                {
                    EngineState.MergeFromFile(stateFile.File, stateFile.IsCompressed, stateFile.OverwriteExisting, stateFile.EngineStateParts);
                }
            }
 
            if (keyboardAdapter != null)
                KeyboardEventPoller.Initialize(keyboardAdapter);
 
            if (mouseAdapter != null)
                MouseEventPoller.Initialize(mouseAdapter);
 
            if (touchAdapter != null)
                Input.TouchAdapter = touchAdapter;
 
            if (gamepadManager is not null)
                Input.GamepadManager = gamepadManager;
 
            if (UiDispatcher == null)
                PostInitialization?.Invoke();
            else
                UiDispatcher!.Post(() => PostInitialization?.Invoke());
 
            EnginePluginRegistry.InvokeInitialize(this);
 
            _isInitialized = true;
 
            if (UiDispatcher == null)
                InitializationComplete?.Invoke();
            else
                UiDispatcher!.Post(() => InitializationComplete?.Invoke());
        }
        finally
        {
            _isInitializing = false;
            _initDone.Set();
        }
    }

    public void SaveConfiguration()
    {
        var store = _configurationStore
            ?? throw new InvalidOperationException("The engine has no initialized configuration store.");
 
        store.Save();
    }

    public void Start()
    {
        if (SynchronizationContext.Current == null)
            throw new InvalidOperationException("SynchronizationContext cannot be null.");
 
        Start(SynchronizationContext.Current);
    }

    public void Start(SynchronizationContext uiContext)
    {
        if (IsRunning)
            return;
 
        UiDispatcher = new UiDispatcher(uiContext);
 
        if (!IsInitialized)
        {
            if (IsInitializing)
            {
                var initializationWaitTimeoutSeconds = Configuration.StartInitializationWaitTimeout;
                var initializationWaitTimeout = TimeSpan.FromSeconds(initializationWaitTimeoutSeconds);
                if (!_initDone.Wait(initializationWaitTimeout))
                    throw new InvalidOperationException(
                        $"Engine initialization did not complete within {initializationWaitTimeoutSeconds:0.###} seconds.");
 
                if (!IsInitialized)
                    throw new InvalidOperationException(
                        "Engine initialization failed on another thread. Call Initialize() again and resolve the initialization error.");
            }
            else
            {
                Initialize();            // we're the initializer—do it now
            }
 
            if (!IsInitialized)
                throw new InvalidOperationException("Engine failed to initialize.");
        }
 
        _isTimerDriven = false;
        EngineSimulationClock.UseWallClock();
        IsRunning = true;
 
        _startTick = HighResTimer.GetCurrentTick();
        _lastCPSSamplingTick = _startTick;
        _lastCycleTick = _startTick;
 
        _cycleTask = Task.Run(() =>
        {
            EngineDispatcher.BindToCurrentThread();
 
            while (Instance.IsRunning)
            {
                Instance.Cycle();
                Thread.Yield(); // optional
            }
        });
    }

    public void StartTimerDriven(SynchronizationContext uiContext)
    {
        if (IsRunning)
            return;
 
        UiDispatcher = new UiDispatcher(uiContext);
 
        if (!IsInitialized)
        {
            if (IsInitializing)
                throw new InvalidOperationException(
                    "Engine initialization is already in progress on another thread. " +
                    "Blocking waits are not supported in timer-driven (single-threaded) mode.");
 
            Initialize();
        }
 
        // Bind the dispatcher to the calling (UI) thread — Tick() will be called from here.
        EngineDispatcher.BindToCurrentThread();
 
        _startTick = HighResTimer.GetCurrentTick();
        _lastCPSSamplingTick = _startTick;
        _lastCycleTick = _startTick;
        _lastBackgroundTick = _startTick;
        _lastForegroundTick = _startTick;
        _timerDrivenSteps.Reset(_startTick);
        _timerDrivenForegroundAccumulatedTicks = 0;
        _lastTimerDrivenForegroundDriverTick = _startTick;
        _timerDrivenForegroundTargetFps = Configuration.TargetFPS;
        EngineSimulationClock.BeginTimerDriven(_startTick);
 
        _isTimerDriven = true;
        IsRunning = true;
 
        // _cycleTask is intentionally left null; the caller drives the loop via Tick().
    }

    public void Tick()
    {
        if (!IsRunning)
            return;
 
        if (!_isTimerDriven)
        {
            Cycle();
            return;
        }
 
        lock (RenderStateSynchronization.SyncRoot)
        {
            EngineDispatcher.Drain();
 
            long driverTick = HighResTimer.GetCurrentTick();
            var batch = _timerDrivenSteps.Advance(
                driverTick,
                Configuration.TimerDrivenSimulationRate,
                Configuration.MaxTimerDrivenSimulationSteps);
 
            bool render = IsTimerDrivenForegroundDue(driverTick);
            double frameDelta = HighResTimer.GetDuration(_lastForegroundTick, driverTick);
 
            if (batch.StepCount == 0)
            {
                if (render)
                    RenderFrame(driverTick, frameDelta);
 
                if (Configuration.LegacyCpsSamplingTime > 0)
                    CalculateCPS(driverTick);
 
                return;
            }
 
            double fixedDelta = batch.StepTicks / (double)HighResTimer.TicksPerSecond;
 
            for (int step = 0; step < batch.StepCount && IsRunning; step++)
            {
                long simulationTick = batch.GetStepTick(step);
                EngineSimulationClock.SetTimerDrivenTick(simulationTick);
 
                bool isLastStep = step == batch.StepCount - 1;
                RunSimulationCycle(
                    simulationTick,
                    fixedDelta,
                    render && isLastStep,
                    driverTick,
                    frameDelta,
                    sampleCps: isLastStep);
            }
        }
    }

    public void Stop()
    {
        if (!IsRunning)
            return;
 
        IsRunning = false;
        _isTimerDriven = false;
        EngineSimulationClock.UseWallClock();
        InvokeShutdownAfterCycleStops();
    }

    public void StopAndWait()
    {
        var cycleTask = _cycleTask;
        if (cycleTask is not null && !cycleTask.IsCompleted && EngineDispatcher.IsOnEngineThread)
            throw new InvalidOperationException("StopAndWait must be called outside the background engine thread.");
 
        Stop();
        cycleTask?.GetAwaiter().GetResult();
    }
 
    private void InvokeShutdownAfterCycleStops()
    {
        var cycleTask = _cycleTask;
 
        if (cycleTask is not null && !cycleTask.IsCompleted)
        {
            cycleTask.ContinueWith(
                _ => EnginePluginRegistry.InvokeShutdown(this),
                System.Threading.CancellationToken.None,
                System.Threading.Tasks.TaskContinuationOptions.ExecuteSynchronously,
                System.Threading.Tasks.TaskScheduler.Default);
            return;
        }
 
        EnginePluginRegistry.InvokeShutdown(this);
    }
 
    #region public properties

    public IUiDispatcher? UiDispatcher { get; private set; }

    public IEngineDispatcher EngineDispatcher { get; } = new EngineDispatcher();

    public bool IsInitialized => _isInitialized;

    public bool IsInitializing => _isInitializing;

    public bool IsRunning { get; private set; }

    public long TotalTicksEngineRunning => HighResTimer.GetCurrentTick() - _startTick;

    public double TotalSecondsEngineRunning => TotalTicksEngineRunning / (double)HighResTimer.TicksPerSecond;

    [Obsolete(
        "Legacy CPS/FPS properties are deprecated. Use Engine.Profiler for runtime telemetry; ProfilerWidget provides an optional in-game display.",
        DiagnosticId = "GOND0001")]
    public double CyclesPerSecond => _grossCPS;

    [Obsolete(
        "Legacy CPS/FPS properties are deprecated. Use Engine.Profiler for runtime telemetry; ProfilerWidget provides an optional in-game display.",
        DiagnosticId = "GOND0001")]
    public double FramesPerSecond => _netFPS;

    public EngineState State { get; } = new EngineState();
 
    private EngineConfiguration? _config = new();

    public EngineConfiguration Configuration
    {
        get => Volatile.Read(ref _config!);
        private set => Volatile.Write(ref _config, value);
    }

    public EngineManagers Managers { get; } = new();

    public EngineInputSystems Input { get; } = new();

    public bool IsDisposed { get; private set; } = false;

    public bool IsDisposing { get; private set; }
 
    #endregion public properties
 
    #region private methods
 
    private void Cycle()
    {
        // Give a GPU paint callback that is already waiting for live render state
        // a chance to acquire the shared gate before this unconstrained loop takes
        // another simulation cycle.
        RenderStateSynchronization.WaitForPendingGpuRenderers();
 
        lock (RenderStateSynchronization.SyncRoot)
        {
            EngineDispatcher.Drain();
 
            long tick = HighResTimer.GetCurrentTick();
            var deltaSeconds = HighResTimer.GetDuration(_lastCycleTick, tick);
            _lastCycleTick = tick;
 
            RunSimulationCycle(
                tick,
                deltaSeconds,
                IsForegroundDue(tick),
                tick,
                deltaSeconds,
                sampleCps: true);
        }
    }
 
    private void RunSimulationCycle(
        long simulationTick,
        double simulationDelta,
        bool render,
        long renderTick,
        double frameDelta,
        bool sampleCps)
    {
        // Refresh native gamepad state before any simulation callbacks consume it.
        // Use the real driver/render tick rather than the fixed-step simulation clock so
        // timer-driven catch-up steps cannot compress or delay hardware polling cadence.
        Input.RefreshGamepads(renderTick, Configuration);
 
        long telemetryGeneration = _engineTelemetry.BeginSample();
        long telemetryStarted = telemetryGeneration == 0 ? 0 : HighResTimer.GetCurrentTick();
        EnginePluginRegistry.InvokePreCycle(this, simulationDelta);
 
        DoBackgroundTasks(simulationTick);
 
        if (render)
            RenderFrame(renderTick, frameDelta);
 
        _grossCyclesThisMeasure++;
 
        if (sampleCps && Configuration.LegacyCpsSamplingTime > 0)
            CalculateCPS(renderTick);
 
        EnginePluginRegistry.InvokePostCycle(this, simulationDelta);
        if (telemetryGeneration != 0)
            _engineTelemetry.Record(telemetryGeneration, "cycle.cpu.ms",
                HighResTimer.GetDuration(telemetryStarted, HighResTimer.GetCurrentTick()) * 1000d);
    }
 
    private bool IsForegroundDue(long tick) =>
        Configuration.TargetFPS <= 0
        || (tick - _lastForegroundTick) >= HighResTimer.TicksPerSecond / Configuration.TargetFPS;
 
    private bool IsTimerDrivenForegroundDue(long tick)
    {
        int targetFps = Configuration.TargetFPS;
        long elapsedTicks = Math.Max(0, tick - _lastTimerDrivenForegroundDriverTick);
        _lastTimerDrivenForegroundDriverTick = tick;
 
        if (targetFps <= 0)
        {
            _timerDrivenForegroundAccumulatedTicks = 0;
            _timerDrivenForegroundTargetFps = targetFps;
            return true;
        }
 
        if (_timerDrivenForegroundTargetFps != targetFps)
        {
            _timerDrivenForegroundTargetFps = targetFps;
            _timerDrivenForegroundAccumulatedTicks = 0;
        }
 
        _timerDrivenForegroundAccumulatedTicks += elapsedTicks;
 
        long frameIntervalTicks = Math.Max(1, HighResTimer.TicksPerSecond / targetFps);
        if (_timerDrivenForegroundAccumulatedTicks < frameIntervalTicks)
            return false;
 
        // Render at most once per externally driven Tick(), but preserve the fractional
        // remainder so small requestAnimationFrame timing jitter cannot permanently lower
        // the effective render rate. Whole missed intervals are discarded rather than
        // causing an unbounded render catch-up sequence after a long browser stall.
        _timerDrivenForegroundAccumulatedTicks %= frameIntervalTicks;
        return true;
    }
 
    private void RenderFrame(long tick, double delta)
    {
        long telemetryGeneration = _engineTelemetry.BeginSample();
        long telemetryStarted = telemetryGeneration == 0 ? 0 : HighResTimer.GetCurrentTick();
        EnginePluginRegistry.InvokePreFrameRender(this, delta);
 
        DoForegroundTasks(tick);
 
        EnginePluginRegistry.InvokePostFrameRender(this, delta);
 
        _lastForegroundTick = tick;
        _netCyclesThisMeasure++;
        if (telemetryGeneration != 0)
            _engineTelemetry.Record(telemetryGeneration, "foreground.cpu.ms",
                HighResTimer.GetDuration(telemetryStarted, HighResTimer.GetCurrentTick()) * 1000d);
    }
 
    private void DoBackgroundTasks(long tick)
    {
        long telemetryGeneration = _engineTelemetry.BeginSample();
        long telemetryStarted = telemetryGeneration == 0 ? 0 : HighResTimer.GetCurrentTick();
        // find total real seconds passed since last background loop
        var deltaSeconds = HighResTimer.GetDuration(_lastBackgroundTick, tick);
 
        BeforeBackgroundTasksExecute?.Invoke();
 
        // raise pre-cycle timer events
        Timer.RaiseTimerEvents(TimerType.PreCycle, tick);
 
        // check for keyboard events
        KeyboardEventPoller.Instance?.PollForEvents(tick);
 
        // check for mouse events
        MouseEventPoller.Instance?.PollForEvents(tick);
 
        // check for touch events
        TouchEventPoller.Instance?.PollForEvents(tick);
 
        // check for gamepad events
        GamepadEventPoller.Instance?.PollForEvents(tick);
 
        // cycle Animator frames
        for (int i = 0; i < Tile.TilesAnimating.Count; i++)
            Tile.TilesAnimating[i].TileAnimator.CycleAnimation(tick);
 
        // advance Sprite Movement paths
        SpriteManager.Instance.MoveSprites(tick);
 
        // resolve collisions after movement
        foreach (var scene in Scenes.Scene.GetAllScenes())
        {
            foreach (var layer in scene.SceneLayers)
                layer.CollisionResolver.Resolve();
        }
 
        // update cameras so any movement can mark RefreshNeeded = All.
        foreach (var surface in RenderSurfaceHostRegistry.All)
            surface.ViewManager.UpdateCameras(deltaSeconds);
 
        AfterBackgroundTasksExecute?.Invoke();
 
        _lastBackgroundTick = tick;
        if (telemetryGeneration != 0)
            _engineTelemetry.Record(telemetryGeneration, "background.cpu.ms",
                HighResTimer.GetDuration(telemetryStarted, HighResTimer.GetCurrentTick()) * 1000d);
    }
 
    private void DoForegroundTasks(long tick)
    {
        // raise event
        BeforeFrameRender?.Invoke();
 
        // Effects are presentation state, so advance them on the foreground/render cadence.
        foreach (var surface in RenderSurfaceHostRegistry.All)
            surface.Effects.Update(tick);
 
        // update the DirectDrawing instances' states
        DirectDrawingManager.Instance.UpdateAll(tick);
 
        // Resolve desktop GPU visual state at foreground cadence before requesting repaint.
        foreach (var surface in RenderSurfaceHostRegistry.All)
            surface.ProduceRenderFrameSnapshot(tick);
 
        // Bitmap rendering remains on the engine thread.
        foreach (var surface in RenderSurfaceHostRegistry.All)
            if (!surface.Backbuffer.IsGlThreadRendered)
                surface.RenderToBackbuffer(tick);
 
        // render each Backbuffer to RenderSurfaceHost adapter (skip GL-thread surfaces)
        foreach (var surface in RenderSurfaceHostRegistry.All)
            if (!surface.Backbuffer.IsGlThreadRendered)
                surface.PresentBackbufferToAdapter();
 
        // raise event
        // GL thread rendering is done as part of this invocation
        AfterFrameRender?.Invoke();
 
        // raise post-cycle timer events
        Timer.RaiseTimerEvents(TimerType.PostCycle, tick);
    }
 
    private void CalculateCPS(long tick)
    {
        // Has the sampling interval elapsed?
        long elapsedTicks = tick - _lastCPSSamplingTick;
        if (elapsedTicks < Configuration.LegacyCpsSamplingTicks)
            return;
 
        // SNAPSHOT the counters BEFORE resetting or posting
        long grossCycles = _grossCyclesThisMeasure;
        long netCycles = _netCyclesThisMeasure;
 
        // Compute using the snapshot
        double elapsedSec = elapsedTicks / (double)HighResTimer.TicksPerSecond;
        double grossCps = grossCycles * HighResTimer.TicksPerSecond / (double)elapsedTicks;
        double netCps = netCycles * HighResTimer.TicksPerSecond / (double)elapsedTicks;
 
        // Collect actual GPU FPS from all registered GPU-rendered backbuffers.
        long totalGpuFrames = 0;
        int gpuSurfaceCount = 0;
        foreach (var surface in RenderSurfaceHostRegistry.All.ToArray())
        {
            if (surface.Backbuffer is GpuBackbuffer gpuBb)
            {
                totalGpuFrames += gpuBb.ConsumeFrameCount();
                gpuSurfaceCount++;
            }
        }
        double? gpuFps = gpuSurfaceCount > 0
            ? totalGpuFrames * HighResTimer.TicksPerSecond / (double)elapsedTicks
            : null;
 
        // Build immutable args NOW (so lambda doesn't read changing fields later)
        var args = new CyclesPerSecondCalculatedEventArgs(
            grossCycles,
            netCycles,
            grossCps,
            netCps,
            elapsedSec,
            gpuFps
        );
 
        // Post the snapshot
        UiDispatcher!.Post(() => CPSCalculated?.Invoke(args));
 
        _grossCPS = grossCps;
        _netFPS = netCps;
 
        // Reset for next window
        _lastCPSSamplingTick = tick;
        _grossCyclesThisMeasure = 0;
        _netCyclesThisMeasure = 0;
    }
 
    private static void ConfigureLogging(EngineConfiguration configuration)
    {
        // Logging may already be active because hosts can configure it before
        // Engine.Initialize. Recreate the async pipeline so its channel uses
        // the capacity loaded from this configuration.
        EngineLogger.StopAsyncLogging(flush: true);
 
        if (configuration.LoggingMode == EngineLoggingMode.Asynchronous)
        {
            EngineLogger.SwitchToAsync(configuration.LoggingQueueCapacity);
            return;
        }
 
        EngineLogger.Mode = EngineLoggingMode.Synchronous;
    }
 
    #endregion private methods
 
    #region IDisposable support
 
    private void Dispose(bool disposing)
    {
        if (!IsDisposed)
        {
            if (disposing)
            {
                if (IsDisposing)
                    return;
 
                IsDisposing = true;
 
                // stop the loop first so handlers don't race the cycle thread
                try
                {
                    Stop();
                }
                catch (Exception ex)
                {
                    Logger.LogError(ex, "Unhandled exception calling Stop()");
                }
 
                // wait for the background loop to actually exit unless we're already on it
                try
                {
                    var cycleTask = _cycleTask;
                    if (cycleTask is not null && EngineDispatcher.IsOnEngineThread && !cycleTask.IsCompleted)
                    {
                        if (!_deferredDisposeScheduled)
                        {
                            _deferredDisposeScheduled = true;
                            cycleTask.ContinueWith(
                                _ => CompleteManagedDisposal(),
                                System.Threading.CancellationToken.None,
                                System.Threading.Tasks.TaskContinuationOptions.ExecuteSynchronously,
                                System.Threading.Tasks.TaskScheduler.Default);
                        }
 
                        return;
                    }
 
                    if (cycleTask is not null && !EngineDispatcher.IsOnEngineThread)
                        cycleTask.Wait();
                }
                catch (Exception ex)
                {
                    Logger.LogError(ex, "Error waiting for engine loop to exit.");
                }
 
                CompleteManagedDisposal();
            }
            else
            {
                // unmanaged cleanup...
                IsDisposed = true;
            }
        }
    }
 
    private void CompleteManagedDisposal()
    {
        if (IsDisposed)
            return;
 
        // raise Disposing on UI thread if possible; otherwise inline
        if (UiDispatcher is not null)
            UiDispatcher.Post(() => SafeInvoke(Disposing));
        else
            SafeInvoke(Disposing);
 
        Profiler.Dispose();
 
        // managed cleanup...
        Input.KeyboardEventPoller?.StopMonitoringAllKeys();
        MouseEventPoller.Reset();
        TouchEventPoller.Reset();
 
        if (Input.GamepadManager is not null)
            foreach (var gamepadAdapter in Input.GamepadManager.ConnectedAdapters)
                Input.GamepadEventPoller?.StopMonitoringAllButtons(gamepadAdapter.GamepadId);
 
        try
        {
            _configurationStore?.Dispose();
        }
        catch (Exception ex)
        {
            Logger.LogError(ex, "Error saving the engine configuration during disposal.");
        }
        finally
        {
            _configurationStore = null;
        }
 
        if (EngineLogger.Mode == EngineLoggingMode.Asynchronous)
            EngineLogger.StopAsyncLogging(flush: Configuration.FlushAsyncLogsOnShutdown);
 
        Timer.ClearAll();
        State.Clear();
 
        // unmanaged cleanup...
        IsDisposed = true;
 
        // now signal we're fully torn down
        if (UiDispatcher is not null)
            UiDispatcher.Post(() => SafeInvoke(Disposed));
        else
            SafeInvoke(Disposed);
    }
 
    private static void SafeInvoke(Action? evnt)
    {
        try { evnt?.Invoke(); }
        catch (Exception ex)
        {
            // Keep disposal robust; log and continue
            Logger.LogError(ex, "Unhandled exception in disposal event handler.");
        }
    }

    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
    }
 
    ~Engine()
    {
        // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
        Dispose(disposing: false);
    }
 
    #endregion IDisposable support
}