acdream/src/AcDream.App/Streaming/StreamingController.cs

using System;
using System.Collections.Generic;
using AcDream.Core.World;

namespace AcDream.App.Streaming;

/// <summary>
/// Called once per frame from <c>GameWindow.OnUpdate</c>. Owns the
/// <see cref="StreamingRegion"/> and uses delegates into
/// <see cref="LandblockStreamer"/> so tests can inject fakes. All work
/// happens on the render thread; the streamer itself is background.
///
/// <remarks>
/// Threading: not thread-safe. All calls must happen on the render thread.
/// </remarks>
/// </summary>
public sealed class StreamingController
{
    private readonly Action<uint> _enqueueLoad;
    private readonly Action<uint> _enqueueUnload;
    private readonly Func<int, IReadOnlyList<LandblockStreamResult>> _drainCompletions;
    private readonly Action<LoadedLandblock> _applyTerrain;
    private readonly Action<uint>? _removeTerrain;
    private readonly GpuWorldState _state;
    private StreamingRegion? _region;

    public int Radius { get; set; }

    /// <summary>
    /// Cap on completions drained per <see cref="Tick"/> call. The cap is
    /// the GPU upload budget for one frame: terrain mesh + per-entity GfxObj
    /// sub-mesh uploads + texture uploads for one landblock take a few ms;
    /// applying 25 of them in a single frame produces a memory spike
    /// (observed: out-of-memory crash on the 5×5 first-frame load).
    ///
    /// <para>
    /// 4 is the original async-streamer value; it spreads a 5×5 first-frame
    /// load over ~7 frames (~116ms at 60fps), which is below the human
    /// perception threshold. Spawn races that previously dropped entities
    /// while landblocks were in flight are now handled by
    /// <see cref="GpuWorldState"/>'s pending-spawn list, so spreading
    /// completions doesn't lose any data.
    /// </para>
    /// </summary>
    public int MaxCompletionsPerFrame { get; set; } = 4;

    public StreamingController(
        Action<uint> enqueueLoad,
        Action<uint> enqueueUnload,
        Func<int, IReadOnlyList<LandblockStreamResult>> drainCompletions,
        Action<LoadedLandblock> applyTerrain,
        GpuWorldState state,
        int radius,
        Action<uint>? removeTerrain = null)
    {
        _enqueueLoad = enqueueLoad;
        _enqueueUnload = enqueueUnload;
        _drainCompletions = drainCompletions;
        _applyTerrain = applyTerrain;
        _removeTerrain = removeTerrain;
        _state = state;
        Radius = radius;
    }

    /// <summary>
    /// Advance one frame. <paramref name="observerCx"/>/<paramref name="observerCy"/>
    /// are landblock coordinates (0..255) of the current viewer — the camera
    /// in offline mode, the server-sent player position in live.
    /// </summary>
    public void Tick(int observerCx, int observerCy)
    {
        // First-tick bootstrap: no region yet, so the whole visible window
        // is a load diff.
        if (_region is null)
        {
            _region = new StreamingRegion(observerCx, observerCy, Radius);
            foreach (var id in _region.Visible)
                _enqueueLoad(id);
        }
        else if (_region.CenterX != observerCx || _region.CenterY != observerCy)
        {
            var diff = _region.RecenterToSingleTier(observerCx, observerCy);
            foreach (var id in diff.ToLoad) _enqueueLoad(id);
            foreach (var id in diff.ToUnload) _enqueueUnload(id);
        }

        // Drain up to N completions per frame so a big diff doesn't spike
        // GPU upload time. Remaining completions wait for the next frame.
        var drained = _drainCompletions(MaxCompletionsPerFrame);
        foreach (var result in drained)
        {
            switch (result)
            {
                case LandblockStreamResult.Loaded loaded:
                    _applyTerrain(loaded.Landblock);
                    _state.AddLandblock(loaded.Landblock);
                    break;
                case LandblockStreamResult.Unloaded unloaded:
                    _state.RemoveLandblock(unloaded.LandblockId);
                    _removeTerrain?.Invoke(unloaded.LandblockId);
                    break;
                case LandblockStreamResult.Failed failed:
                    Console.WriteLine(
                        $"streaming: load failed for 0x{failed.LandblockId:X8}: {failed.Error}");
                    break;
                case LandblockStreamResult.WorkerCrashed crashed:
                    Console.WriteLine(
                        $"streaming: worker CRASHED: {crashed.Error}");
                    break;
                case LandblockStreamResult.Promoted:
                    // TODO(A.5 T13): merge promoted entities into existing
                    // GpuWorldState entry via AddEntitiesToExistingLandblock.
                    // Today the streamer never produces Promoted (only LoadNear /
                    // LoadFar), so this arm is unreachable and silently consumed.
                    break;
            }
        }
    }
}