acdream/src/AcDream.App/Rendering/Wb/LandblockSpawnAdapter.cs

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

namespace AcDream.App.Rendering.Wb;

/// <summary>
/// Bridges landblock streaming events to <see cref="IWbMeshAdapter"/>'s
/// reference-count lifecycle. <b>Tier-aware by design</b>: only atlas-tier
/// entities (procedural / dat-hydrated, identified by
/// <c>ServerGuid == 0</c>) drive ref counts. Server-spawned entities
/// (per-instance tier) are skipped — those go through
/// <c>EntitySpawnAdapter</c> + <c>TextureCache.GetOrUploadWithPaletteOverride</c>
/// (see Phase N.4 spec, Architecture → Two-tier rendering split).
///
/// <para>
/// On load: walks the landblock's atlas-tier entities, collects unique
/// GfxObj ids from their <c>MeshRefs</c>, calls
/// <c>IncrementRefCount</c> per id. Snapshots the id-set per landblock so
/// unload can match the load 1:1.
/// </para>
///
/// <para>
/// On unload: looks up the snapshot, calls <c>DecrementRefCount</c> per id,
/// drops the snapshot. Unknown / never-loaded landblocks no-op.
/// </para>
///
/// <para>
/// Idempotency: repeated notifications for the same landblock only register
/// newly-seen ids. This matters for two-tier streaming: a far-tier terrain
/// load first snapshots an empty entity set, then a later Far-to-Near promotion
/// supplies the actual stabs/buildings. Treating the second notification as a
/// blanket no-op leaves the world-state entity list populated while the WB
/// mesh cache never pins the promoted GfxObj ids.
/// </para>
///
/// <para>
/// Thread safety: the underlying <see cref="IWbMeshAdapter"/> implementation
/// uses <c>ConcurrentDictionary</c>, so the streaming worker thread may call
/// this safely. The internal snapshot dictionary is NOT thread-safe and must
/// be called from a single streaming thread (the same thread that fires
/// AddLandblock / RemoveLandblock events).
/// </para>
/// </summary>
public sealed class LandblockSpawnAdapter
{
    private readonly IWbMeshAdapter _adapter;

    // Maps landblock id → unique GfxObj ids registered for that landblock.
    // Written on load, read+cleared on unload. Single-threaded (streaming worker).
    private readonly Dictionary<uint, HashSet<ulong>> _idsByLandblock = new();

    public LandblockSpawnAdapter(IWbMeshAdapter adapter)
    {
        System.ArgumentNullException.ThrowIfNull(adapter);
        _adapter = adapter;
    }

    /// <summary>
    /// Called when a landblock finishes streaming in or receives promoted
    /// atlas-tier entities. Registers a ref-count increment with WB for each
    /// unique atlas-tier GfxObj id that has not already been registered for
    /// this landblock.
    /// </summary>
    public void OnLandblockLoaded(LoadedLandblock landblock)
    {
        System.ArgumentNullException.ThrowIfNull(landblock);

        var unique = new HashSet<ulong>();
        foreach (var entity in landblock.Entities)
        {
            // Atlas-tier filter: server-spawned entities (ServerGuid != 0)
            // belong to the per-instance path and are NOT registered with WB.
            if (entity.ServerGuid != 0) continue;

            foreach (var meshRef in entity.MeshRefs)
                unique.Add((ulong)meshRef.GfxObjId);
        }

        if (!_idsByLandblock.TryGetValue(landblock.LandblockId, out var registered))
        {
            _idsByLandblock[landblock.LandblockId] = unique;
            foreach (var id in unique) _adapter.IncrementRefCount(id);
            return;
        }

        foreach (var id in unique)
        {
            if (registered.Add(id))
                _adapter.IncrementRefCount(id);
        }
    }

    /// <summary>
    /// Called when a landblock is unloaded from the streaming window.
    /// Releases the ref-count for every GfxObj id that was registered on load.
    /// Unknown landblock ids (never loaded, or already unloaded) are no-ops.
    /// </summary>
    public void OnLandblockUnloaded(uint landblockId)
    {
        if (!_idsByLandblock.TryGetValue(landblockId, out var unique)) return;
        foreach (var id in unique) _adapter.DecrementRefCount(id);
        _idsByLandblock.Remove(landblockId);
    }
}