acdream/src/AcDream.App/Rendering/Wb/WbDrawDispatcher.WalkClassify.cs

using System.Numerics;
using AcDream.App.Rendering.Scene;
using AcDream.App.Rendering.Selection;
using AcDream.App.Rendering.Walk;
using AcDream.Core.Lighting;
using AcDream.Core.Meshing;
using AcDream.Core.World;
using DatReaderWriter.Enums;

namespace AcDream.App.Rendering.Wb;

/// <summary>
/// Campaign FW stage FW3.2a: the walk-order population layer. This partial
/// holds two things.
///
/// <para><b>The shared per-batch classify core</b> (<see cref="TryClassifyBatch"/>):
/// extracted from <c>ClassifyBatches</c> (this file's sibling
/// <c>WbDrawDispatcher.cs</c>) and <c>ClassifyPackedBatches</c>
/// (<c>WbDrawDispatcher.PackedOracle.cs</c>), which carried byte-identical
/// per-batch logic (the #426 untextured-subset gate, the #188 opacity
/// promotion, texture resolution, Campaign VM foliage classification, the
/// <see cref="GroupKey"/> construction) with only their SURROUNDING
/// bookkeeping differing (classic appends to an <see cref="InstanceGroup"/>
/// via caller-scoped instance fields; packed appends via explicit
/// parameters). Both call sites now call this one method per batch and keep
/// their own append logic — the classic and packed paths are unchanged in
/// every observable way (same hermetic + <c>Lane=InstalledDat</c> suites
/// stay the referee); this stage's OWN new walk classifier
/// (<see cref="ClassifyEntityForWalk"/>) is the third caller.</para>
///
/// <para><b>The per-entity walk classify seam</b>
/// (<see cref="ClassifyEntityForWalk"/>): given ONE <see cref="RenderProjectionRecord"/>
/// — the same shape <c>ClassifyPackedEntity</c> consumes, but read straight
/// off the record's own <see cref="RenderEntityPayload"/> via
/// <c>RenderInstanceCandidate.FromProjection</c> rather than the packed
/// route's frame-arena mesh-part flattening — yields one
/// <see cref="WalkClassifiedBatch"/> per surviving (part, batch) pair WITHOUT
/// touching any <see cref="InstanceGroup"/>, plus the per-part selection
/// data <c>AddPackedSelectionPart</c> would have published, for
/// <c>WalkStaticStreamPopulator</c> to publish itself (deliverable
/// 1 leaves the publish decision — timing, stage/cell provenance — to the
/// caller; see <see cref="PublishWalkSelectionPart"/>, the thin internal seam
/// that keeps <c>_selectionSink</c> encapsulated).</para>
///
/// <para>Scope: this stage classifies static content only (no production
/// frame wiring — see plan §FW3.2a). Per-part translucency-fade
/// (<c>TranslucencyFadeManager</c>/<c>EntityOpacity</c>) is NOT threaded
/// through: that mechanic is <c>TransparentPartHook</c>, a retail LIVE-entity
/// behavior keyed by ServerGuid, not something world statics undergo — every
/// classified batch here carries <c>Alpha = 1f</c>. Likewise the async
/// mesh-miss self-heal request (<c>_missRequested</c>/<c>EnsureLoaded</c>,
/// frame-scoped state cleared by <c>BeginEntityDispatch</c>) is not fired
/// here — this seam has no production frame to be scoped to yet; a missing
/// mesh is simply skipped, matching every other unwired FW2/FW3.2a path.</para>
/// </summary>
public sealed partial class WbDrawDispatcher
{
    private readonly HashSet<WalkDrawnPartKey> _walkDrawnParts = new();
    private bool _walkPartFrameActive;
    private readonly Dictionary<string, string> _facilityStairProbeSignatures = new();
    private Dictionary<uint, FacilityStairProbeSnapshot> _facilityStairsCurrent = new();
    private Dictionary<uint, FacilityStairProbeSnapshot> _facilityStairsPrevious = new();
    private int _facilityStairsCurrentFrame = -1;
    private int _facilityStairsPreviousFrame = -1;

    private readonly record struct FacilityStairProbeSnapshot(
        uint CellId,
        int RouteIndex,
        bool Admitted,
        bool ScreenIntersect,
        string ScreenBounds,
        Vector3 WorldCenter);

    private readonly record struct WalkDrawnPartKey(
        RenderProjectionId ProjectionId,
        int PartIndex);

    /// <summary>
    /// Opens retail's per-part drawn-stamp scope. A CPartArray may be present
    /// in several cells from its retained CELLARRAY; CPhysicsPart::Draw stamps
    /// only a part that actually passed the current cell's portal test. That
    /// lets a rejected head/hair part retry through another crossed cell while
    /// preventing already-admitted torso parts from being submitted twice in
    /// one retail draw pass. PView::DrawCells advances the stamp between its
    /// landscape and interior-cell passes; <see cref="AdvanceWalkPartPassStamp"/>
    /// reproduces that mid-frame boundary.
    /// </summary>
    internal void BeginWalkPartFrame()
    {
        if (_walkPartFrameActive)
        {
            throw new InvalidOperationException(
                "A walk part frame was opened before the previous scope closed.");
        }

        _walkDrawnParts.Clear();
        BeginFacilityStairSubmissionProbeFrame();
        _walkPartFrameActive = true;
    }

    /// <summary>
    /// Re-arms retail's per-part drawn stamp at the mid-DrawCells pass
    /// boundary. Retail increments RenderDevice::m_nFrameStamp at 0x005A4886
    /// after LScape::draw + FlushAlphaList and before the interior depth clear,
    /// so a shadow part drawn through the landscape may draw once more when
    /// the interior cell list repaints after that clear.
    /// </summary>
    internal void AdvanceWalkPartPassStamp()
    {
        if (!_walkPartFrameActive)
        {
            throw new InvalidOperationException(
                "The walk part pass stamp cannot advance outside an active frame.");
        }

        _walkDrawnParts.Clear();
    }

    internal void EndWalkPartFrame()
    {
        _walkPartFrameActive = false;
        _walkDrawnParts.Clear();
    }

    private bool TryStampWalkPart(
        in RenderProjectionRecord projection,
        int partIndex) =>
        !_walkPartFrameActive
        // RenderDeviceD3D::DrawMeshInternal @0x0059F360 explicitly bypasses
        // Get/SetDrawnThisFrame when IsPartOfPlayerObj is true. The local
        // player must repaint at every crossed-cell turn so later wall/depth
        // ordering cannot leave only the parts admitted by an earlier cell.
        || projection.EntityPayload.CasterIdentity
            == RenderCasterIdentityKind.LocalPlayer
        || _walkDrawnParts.Add(new WalkDrawnPartKey(projection.Id, partIndex));

    /// <summary>
    /// One walk-classified (entity, part, batch) draw candidate — exactly
    /// <c>OrderedDrawCommand</c>'s per-instance field set (minus
    /// the walk-provenance <c>Stage</c>/<c>CellId</c> fields, which the
    /// populator stamps on since the classifier has no notion of either)
    /// plus two fields an opaque command has no use for but a translucent
    /// one needs to reach the alpha queue: <see cref="IsOpaque"/> (so the
    /// populator can route without re-deriving it from
    /// <see cref="GroupKey.Translucency"/>) and <see cref="LocalSortCenter"/>
    /// (the authored GfxObj sort center <c>RetailAlphaOrdering.ComputeViewerDistance</c>
    /// transforms through <see cref="Transform"/> — the same value
    /// <c>InstanceGroup.LocalSortCenters</c> carries per instance today).
    /// </summary>
    internal readonly record struct WalkClassifiedBatch(
        GroupKey Key,
        Matrix4x4 Transform,
        uint ClipSlot,
        InstanceLightSet Lights,
        uint IndoorFlag,
        float Alpha,
        Vector2 SelectionLighting,
        uint DetailCategory,
        bool IsOpaque,
        Vector3 LocalSortCenter);

    /// <summary>
    /// One retail-picking part surfaced by <see cref="ClassifyEntityForWalk"/>
    /// — the exact argument tuple <c>AddPackedSelectionPart</c>'s
    /// <c>publishSelection: true</c> branch passes to
    /// <c>IRetailSelectionRenderSink.AddVisiblePart</c>. The classify seam
    /// surfaces this; <see cref="PublishWalkSelectionPart"/> is the caller's
    /// publish call.
    /// </summary>
    internal readonly record struct WalkClassifiedSelectionPart(
        uint ServerGuid,
        uint LocalEntityId,
        int PartIndex,
        uint GfxObjId,
        Matrix4x4 LocalToWorld);

    /// <summary>
    /// The shared per-batch classify core. Given one already-resolved
    /// <paramref name="renderData"/> and the batch at <paramref name="batchIndex"/>,
    /// applies — in this exact order, matching both <c>ClassifyBatches</c> and
    /// <c>ClassifyPackedBatches</c> before this extraction — the #426
    /// untextured-subset-on-a-shell-only gate, the #188 mid-fade-forces-
    /// AlphaBlend promotion, texture resolution, and Campaign VM foliage
    /// classification, then builds the surviving batch's <see cref="GroupKey"/>.
    ///
    /// <para>Returns false when the batch does not survive — either the
    /// untextured-subset gate rejected it (in which case
    /// <paramref name="compositePending"/> is always false: <c>ResolveTexture</c>
    /// is never called) or its resolved texture slot is unassigned (in which
    /// case <paramref name="compositePending"/> still reflects whatever
    /// <c>ResolveTexture</c> reported — a caller must apply it to its own
    /// reusability/readiness tracking regardless of the false return, exactly
    /// as both existing callers did before this extraction).</para>
    /// </summary>
    private bool TryClassifyBatch(
        ObjectRenderData renderData,
        int batchIndex,
        in RenderInstanceCandidate entity,
        MeshRef meshRef,
        PaletteCompositeIdentity paletteIdentity,
        float opacityMultiplier,
        bool entityHasCutoutSubset,
        out GroupKey key,
        out bool compositePending)
    {
        key = default;
        compositePending = false;
        ObjectRenderBatch batch = renderData.Batches[batchIndex];

        // #426 — see RetailUntexturedSubsetPolicy for the retail citation.
        // ONE shared predicate for every classifier so they cannot drift.
        if (!RetailUntexturedSubsetPolicy.Draws(entity.IsBuildingShell, batch.Key.IsSolid))
            return false;

        TranslucencyKind translucency = batch.Translucency;

        // #188: a mid-fade instance whose surface is otherwise Opaque/ClipMap
        // must route through the alpha-blend pass so mesh_modern.frag's
        // (blend-enabled) shader actually composites the reduced alpha — the
        // no-blend opaque pass would ignore it.
        if (opacityMultiplier < 1.0f && IsOpaque(translucency))
            translucency = TranslucencyKind.AlphaBlend;

        ResolvedTexture texture = ResolveTexture(
            in entity, meshRef, batch, paletteIdentity, out compositePending);
        if (!texture.Slot.IsAssigned)
            return false;

        // Classify from the RAW (pre-#188-promotion) batch.Translucency — a
        // mid-fade trunk is still a trunk, it just landed in the alpha-blend
        // group instead of opaque (Campaign VM VM6 review fix round).
        uint foliageFlags = FoliageWindClassification.Classify(
            entity.LocalEntityId,
            FoliageWindExclusions.Contains(meshRef.GfxObjId),
            batch.Translucency,
            entityHasCutoutSubset);
        key = new GroupKey(
            batch.FirstIndex, (int)batch.BaseVertex,
            batch.IndexCount, texture.Slot, texture.Layer, translucency,
            FoliageFlags: foliageFlags,
            CullMode: batch.CullMode);
        return true;
    }

    /// <summary>
    /// Classifies one static entity for the walk populator: resolves its clip
    /// slot / light set / selection lighting exactly as
    /// <c>ClassifyPackedEntity</c> does (via the shared
    /// <see cref="ResolveSlotForFrame"/> / <c>ResolveWalkLightSet</c>
    /// helpers), walks its Setup parts or single mesh (mirroring
    /// <c>ClassifyPackedEntity</c>'s own shape), and appends one
    /// <see cref="WalkClassifiedBatch"/> per surviving batch to
    /// <paramref name="batches"/> plus one <see cref="WalkClassifiedSelectionPart"/>
    /// per part to <paramref name="selectionParts"/> — WITHOUT touching
    /// <c>_groups</c>/<c>_packedGroups</c> or publishing selection itself (see
    /// this file's type doc comment).
    ///
    /// <para>S3 review fix round 1 (F5): <see cref="ResolveSlotForFrame"/>
    /// never culls (the clip-slot routing it used to gate on had zero
    /// production callers, so it is deleted, not merely inactive) — the
    /// cull check below is retained for shape parity with every other
    /// classifier's cull gate but never actually fires.</para>
    /// </summary>
    internal void ClassifyEntityForWalk(
        in RenderProjectionRecord projection,
        uint tupleLandblockId,
        List<WalkClassifiedBatch> batches,
        List<WalkClassifiedSelectionPart> selectionParts,
        bool liveDynamic = false,
        IWalkLookInViewSource? lookInViews = null,
        int lookInRouteIndex = -1,
        uint lookInCellId = 0,
        Matrix4x4 diagnosticViewProjection = default)
    {
        ArgumentNullException.ThrowIfNull(batches);
        ArgumentNullException.ThrowIfNull(selectionParts);

        // Retail CPhysicsObj::set_nodraw -> CPartArray::SetNoDrawInternal
        // removes the PartArray from drawing immediately; logical object,
        // cell, script, particle, and eventual DeleteObject lifetimes remain
        // independent.  The retained render scene expresses that exact edge
        // by clearing RenderProjectionFlags.Draw.  The pre-FW dispatcher read
        // WorldEntity.IsDrawVisible before classifying, but the production
        // frame-walk consumes immutable RenderProjectionRecords and therefore
        // must honor the equivalent record flag here.  Without this gate an
        // impacted spell projectile remained visible until ACE's delayed
        // DeleteObject five seconds later even though its SetState had already
        // set NoDraw.
        if ((projection.Flags & RenderProjectionFlags.Draw) == 0)
            return;

        RenderInstanceCandidate entity =
            RenderInstanceCandidate.FromProjection(
                in projection,
                tupleLandblockId,
                animated: liveDynamic);

        (uint slot, bool culled) = ResolveSlotForFrame();
        if (culled)
            return;

        ResolveWalkLightSet(in entity, out InstanceLightSet lights, out bool indoor);
        Vector2 selectionLighting =
            _selectionLighting?.TryGetLighting(
                entity.ServerGuid, entity.LocalEntityId, out RetailSelectionLighting lighting) == true
                ? new Vector2(lighting.Luminosity, lighting.Diffuse)
                : new Vector2(0f, 1f);
        uint detailCategory = entity.IsBuildingShell ? 1u : 0u;

        PaletteCompositeIdentity paletteIdentity = default;
        if (entity.PaletteOverride is not null)
            paletteIdentity = TextureCache.GetPaletteIdentity(entity.PaletteOverride);

        IReadOnlyList<MeshRef>? meshRefs = projection.EntityPayload.MeshRefs;
        if (meshRefs is null)
            return;

        for (int partIndex = 0; partIndex < meshRefs.Count; partIndex++)
        {
            MeshRef meshRef = meshRefs[partIndex];
            if (_meshAdapter.IsRuntimeHiddenMarker(meshRef.GfxObjId))
                continue;

            ObjectRenderData? renderData = _meshAdapter.TryGetRenderData(meshRef.GfxObjId);
            if (renderData is null)
            {
                if (_missRequested.Add(meshRef.GfxObjId))
                    _meshAdapter.EnsureLoaded(meshRef.GfxObjId);
                continue;
            }

            if (renderData.IsSetup && renderData.SetupParts.Count > 0)
            {
                // Same entity-scoped OR the classic/packed classifiers compute
                // — a Setup composite's parts are separate GfxObjs with their
                // own independently cached HasCutoutSubset (Campaign VM VM6
                // review fix round A4/F1).
                bool entityHasCutoutSubset = FoliageWindClassification.ComputeEntityHasCutoutSubset(
                    renderData.SetupParts,
                    _meshAdapter,
                    static (adapter, part) => adapter.TryGetRenderData(part.GfxObjId)
                        is { HasCutoutSubset: true });

                for (int setupPartIndex = 0; setupPartIndex < renderData.SetupParts.Count; setupPartIndex++)
                {
                    (ulong gfxObjId, Matrix4x4 partTransform) = renderData.SetupParts[setupPartIndex];
                    if (_meshAdapter.IsRuntimeHiddenMarker((uint)gfxObjId))
                        continue;

                    ObjectRenderData? partData = _meshAdapter.TryGetRenderData(gfxObjId);
                    if (partData is null)
                    {
                        if (AcDream.Core.Rendering.RenderingDiagnostics.ProbeFacilityStairsEnabled
                            && entity.LocalEntityId == 0x4F41806Cu
                            && gfxObjId == 0x01001FE8u)
                        {
                            Console.WriteLine(
                                $"[facility-part] frame={WalkPView.MasterTimestampForDiagnostics} "
                                + $"local=0x{entity.LocalEntityId:X8} "
                                + $"cell=0x{lookInCellId:X8} gfx=0x{gfxObjId:X8} "
                                + $"part={setupPartIndex} route={lookInRouteIndex} "
                                + "decision=render-data-miss");
                        }
                        if (_missRequested.Add(gfxObjId))
                            _meshAdapter.EnsureLoaded(gfxObjId);
                        continue;
                    }

                    float opacity = liveDynamic
                        ? WalkPartOpacity(
                            entity.ServerGuid,
                            entity.LocalEntityId,
                            (uint)setupPartIndex)
                        : 1f;
                    if (opacity <= 0f)
                    {
                        EmitFacilityStairPartProbe(
                            in projection, in entity, lookInCellId,
                            lookInRouteIndex, (uint)gfxObjId, setupPartIndex,
                            partData, default, diagnosticViewProjection,
                            default, 0f, hasSphere: false,
                            opacity, "opacity-zero", lookInViews);
                        continue;
                    }

                    Matrix4x4 restPose = partTransform * meshRef.PartTransform;
                    Matrix4x4 model = restPose * entity.RootWorld;
                    int selectionPartIndex = unchecked((partIndex << 16) | (setupPartIndex & 0xFFFF));

                    bool visible = ResolvePartVisible(
                        lookInViews,
                        lookInRouteIndex,
                        partData,
                        model,
                        out Vector3 sphereCenter,
                        out float sphereRadius,
                        out bool hasSphere);
                    bool firstAdmission = visible
                        && TryStampWalkPart(in projection, selectionPartIndex);
                    EmitFacilityStairPartProbe(
                        in projection, in entity, lookInCellId,
                        lookInRouteIndex, (uint)gfxObjId, setupPartIndex,
                        partData, model, diagnosticViewProjection,
                        sphereCenter, sphereRadius, hasSphere,
                        opacity,
                        !visible
                            ? "sphere-reject"
                            : firstAdmission ? "admit" : "already-drawn",
                        lookInViews);
                    if (!firstAdmission)
                        continue;
                    EmitClassifiedBatches(
                        partData, model, in entity, meshRef, paletteIdentity,
                        entityHasCutoutSubset, slot, lights, indoor,
                        selectionLighting, detailCategory, opacity,
                        batches);
                    selectionParts.Add(new WalkClassifiedSelectionPart(
                        entity.ServerGuid, entity.LocalEntityId, selectionPartIndex,
                        (uint)gfxObjId, model));
                }
            }
            else
            {
                float opacity = liveDynamic
                    ? WalkPartOpacity(
                        entity.ServerGuid,
                        entity.LocalEntityId,
                        (uint)partIndex)
                    : 1f;
                if (opacity <= 0f)
                {
                    EmitFacilityStairPartProbe(
                        in projection, in entity, lookInCellId,
                        lookInRouteIndex, (uint)meshRef.GfxObjId, partIndex,
                        renderData, default, diagnosticViewProjection,
                        default, 0f, hasSphere: false,
                        opacity, "opacity-zero", lookInViews);
                    continue;
                }

                Matrix4x4 model = meshRef.PartTransform * entity.RootWorld;
                bool visible = ResolvePartVisible(
                    lookInViews,
                    lookInRouteIndex,
                    renderData,
                    model,
                    out Vector3 sphereCenter,
                    out float sphereRadius,
                    out bool hasSphere);
                bool firstAdmission = visible
                    && TryStampWalkPart(in projection, partIndex);
                EmitFacilityStairPartProbe(
                    in projection, in entity, lookInCellId,
                    lookInRouteIndex, (uint)meshRef.GfxObjId, partIndex,
                    renderData, model, diagnosticViewProjection,
                    sphereCenter, sphereRadius, hasSphere,
                    opacity,
                    !visible
                        ? "sphere-reject"
                        : firstAdmission ? "admit" : "already-drawn",
                    lookInViews);
                if (!firstAdmission)
                    continue;
                EmitClassifiedBatches(
                    renderData, model, in entity, meshRef, paletteIdentity,
                    entityHasCutoutSubsetOverride: null, slot, lights, indoor,
                    selectionLighting, detailCategory, opacity,
                    batches);
                selectionParts.Add(new WalkClassifiedSelectionPart(
                    entity.ServerGuid, entity.LocalEntityId, partIndex,
                    (uint)meshRef.GfxObjId, model));
            }
        }
    }

    private float WalkPartOpacity(
        uint serverGuid,
        uint localEntityId,
        uint setupPartIndex)
    {
        float opacity = EntityOpacity(serverGuid);
        if (opacity <= 0f)
            return 0f;
        if (!_translucencyFades.TryGetCurrentValue(
                localEntityId,
                setupPartIndex,
                out float translucency))
        {
            return opacity;
        }

        return translucency >= 1f
            ? 0f
            : opacity * (1f - translucency);
    }

    private void ResolveWalkLightSet(
        in RenderInstanceCandidate entity,
        out InstanceLightSet lights,
        out bool indoor)
    {
        indoor = IndoorObjectReceivesTorches(entity.ParentCell);
        lights = InstanceLightSet.Disabled;
        IReadOnlyList<LightSource>? snapshot = _pointSnapshot;
        if (!indoor || snapshot is null || snapshot.Count == 0)
            return;

        Vector3 center =
            (entity.Bounds.Minimum + entity.Bounds.Maximum) * 0.5f;
        float radius =
            (entity.Bounds.Maximum - entity.Bounds.Minimum)
            .Length() * 0.5f;
        Span<int> selected =
            stackalloc int[LightManager.MaxLightsPerObject];
        selected.Fill(-1);
        LightManager.SelectForObject(
            snapshot,
            center,
            radius,
            selected);
        lights = InstanceLightSet.From(selected);
    }

    /// <summary>
    /// Campaign OVERHAUL S3 chunk 4 (§10.2): retail asks exactly one
    /// question per part — <c>RenderDeviceD3D::DrawMesh</c> @0x005A0860
    /// tests the authored drawing sphere against each active PortalList
    /// view, and once ANY view admits it, <c>DrawMeshInternal</c>
    /// @0x0059F360 submits the complete constructed mesh WHOLE. The former
    /// <c>ResolvePartClipSlots</c> asked the walk's now-deleted
    /// <c>VisibleClipSlotsInLookInTurn</c> for the
    /// per-view slot LIST and then collapsed it to either "nothing" or the
    /// single-element <c>RetailWholeMeshSlot</c> sentinel regardless of how
    /// many views actually admitted — the list was never anything but a
    /// Boolean wearing a list-shaped costume (the portal polygon is never
    /// forwarded as a GPU mesh clip). This method asks the Boolean
    /// directly.
    /// </summary>
    private static bool ResolvePartVisible(
        IWalkLookInViewSource? lookInViews,
        int routeIndex,
        ObjectRenderData renderData,
        Matrix4x4 localToWorld,
        out Vector3 sphereCenter,
        out float sphereRadius,
        out bool hasSphere)
    {
        sphereCenter = default;
        sphereRadius = 0f;
        hasSphere = false;
        if (lookInViews is null)
            return true;

        if (renderData.SelectionSphere is not { Radius: > 0f } sphere)
        {
            // No authored drawing sphere: retail has nothing to sphere-test
            // against, so any admitted view already means "draw" —
            // testSphere:false asks exactly that (any surviving slice for
            // this route, geometry ignored).
            return lookInViews.SphereVisibleInLookInTurn(
                routeIndex, Vector3.Zero, radius: 0f, testSphere: false);
        }

        hasSphere = true;
        TransformDrawingSphere(sphere, localToWorld, out sphereCenter, out sphereRadius);
        return lookInViews.SphereVisibleInLookInTurn(routeIndex, in sphereCenter, sphereRadius);
    }

    private void EmitFacilityStairPartProbe(
        in RenderProjectionRecord projection,
        in RenderInstanceCandidate entity,
        uint cellId,
        int routeIndex,
        uint gfxObjId,
        int partIndex,
        ObjectRenderData renderData,
        Matrix4x4 localToWorld,
        Matrix4x4 viewProjection,
        Vector3 sphereCenter,
        float sphereRadius,
        bool hasSphere,
        float opacity,
        string decision,
        IWalkLookInViewSource? lookInViews)
    {
        if (!AcDream.Core.Rendering.RenderingDiagnostics.ProbeFacilityStairsEnabled)
            return;

        bool targetStairCell = cellId is 0x8A02015Eu or 0x8A02015Fu;
        bool targetPlayerCell = targetStairCell || cellId == 0x8A0201C1u;
        bool targetStair = targetStairCell && gfxObjId == 0x010000DEu;
        bool targetPlayer = targetPlayerCell
            && projection.EntityPayload.CasterIdentity
                == RenderCasterIdentityKind.LocalPlayer;
        // Static render projections carry the local render identity here;
        // SourceId is not guaranteed to retain the Setup DID after the
        // landblock projection has been materialized.
        // Cathedral floating stair Setup 0x020009A2 is seven independent
        // visual parts (0x01001FE8 + six 0x01001FE6 slabs). Tracing only the
        // first GfxObj hid the actual camera-angle failure on the six visible
        // slabs, so keep the probe keyed to the complete PartArray owner.
        bool targetCathedralRamp = entity.LocalEntityId == 0x4F41806Cu;
        if (!targetStair && !targetPlayer && !targetCathedralRamp)
            return;

        int frame = WalkPView.MasterTimestampForDiagnostics;
        string screenBounds = "unavailable";
        bool screenIntersect = false;
        if (targetStair || targetCathedralRamp)
        {
            AdvanceFacilityStairProbeFrame(frame);
            screenIntersect = TryProjectFacilityStairBounds(
                renderData,
                localToWorld,
                viewProjection,
                out screenBounds);
            var snapshot = new FacilityStairProbeSnapshot(
                cellId,
                routeIndex,
                string.Equals(decision, "admit", StringComparison.Ordinal),
                screenIntersect,
                screenBounds,
                hasSphere ? sphereCenter : localToWorld.Translation);
            if (!_facilityStairsCurrent.TryGetValue(
                    entity.LocalEntityId,
                    out FacilityStairProbeSnapshot existing)
                || (!existing.Admitted && snapshot.Admitted))
            {
                _facilityStairsCurrent[entity.LocalEntityId] = snapshot;
            }
        }

        string key = $"{entity.ServerGuid:X8}:{entity.LocalEntityId:X8}:"
            + $"{cellId:X8}:{gfxObjId:X8}:{partIndex}";
        // A route index is allocated afresh every frame. Including it in the
        // signature made a stationary cathedral trace print at frame rate and
        // obscure the useful admit/reject transition. Cell + part are already
        // in the key; emit again only when that route's decision changes.
        string signature = targetCathedralRamp
            ? $"{decision}:{(hasSphere ? 1 : 0)}:"
                + $"{(opacity <= 0f ? 0 : opacity < 1f ? 1 : 2)}"
            : $"{routeIndex}:{decision}:{(hasSphere ? 1 : 0)}:"
                + $"{(opacity <= 0f ? 0 : opacity < 1f ? 1 : 2)}";
        if (_facilityStairProbeSignatures.TryGetValue(key, out string? prior)
            && string.Equals(prior, signature, StringComparison.Ordinal))
        {
            return;
        }
        _facilityStairProbeSignatures[key] = signature;

        string authored = renderData.SelectionSphere is { } sourceSphere
            ? $" authored=({sourceSphere.Origin.X:F4},{sourceSphere.Origin.Y:F4},"
                + $"{sourceSphere.Origin.Z:F4};r={sourceSphere.Radius:F4})"
            : " authored=none";
        string world = hasSphere
            ? $" world=({sphereCenter.X:F4},{sphereCenter.Y:F4},"
                + $"{sphereCenter.Z:F4};r={sphereRadius:F4})"
            : " world=none";
        string cone = targetCathedralRamp && hasSphere && lookInViews is not null
            ? " cone={" + lookInViews.DescribeLookInTurn(
                routeIndex, in sphereCenter, sphereRadius) + "}"
            : string.Empty;
        Console.WriteLine(
            $"[facility-part] frame={frame} "
            + $"kind={projection.EntityPayload.CasterIdentity} "
            + $"guid=0x{entity.ServerGuid:X8} local=0x{entity.LocalEntityId:X8} "
            + $"cell=0x{cellId:X8} parent=0x{entity.ParentCellId:X8} "
            + $"gfx=0x{gfxObjId:X8} part={partIndex} route={routeIndex} "
            + $"opacity={opacity:F4} decision={decision} "
            + $"screen={(screenIntersect ? 1 : 0)} ndc={screenBounds}"
            + authored + world + cone);
    }

    private void AdvanceFacilityStairProbeFrame(int frame)
    {
        if (frame == _facilityStairsCurrentFrame)
            return;

        if (_facilityStairsCurrentFrame >= 0)
        {
            if (_facilityStairsPreviousFrame >= 0)
            {
                foreach ((uint localId, FacilityStairProbeSnapshot previous)
                         in _facilityStairsPrevious)
                {
                    if (!_facilityStairsCurrent.TryGetValue(localId, out _))
                    {
                        Console.WriteLine(
                            $"[facility-stair-drop] frame={_facilityStairsCurrentFrame} "
                            + $"previousFrame={_facilityStairsPreviousFrame} "
                            + $"local=0x{localId:X8} cell=0x{previous.CellId:X8} "
                            + $"route={previous.RouteIndex} admitted={(previous.Admitted ? 1 : 0)} "
                            + $"screen={(previous.ScreenIntersect ? 1 : 0)} "
                            + $"lastNdc={previous.ScreenBounds} "
                            + $"world=({previous.WorldCenter.X:F4},{previous.WorldCenter.Y:F4},"
                            + $"{previous.WorldCenter.Z:F4}) reason=cell-not-walked");
                    }
                }

                foreach ((uint localId, FacilityStairProbeSnapshot current)
                         in _facilityStairsCurrent)
                {
                    if (_facilityStairsPrevious.TryGetValue(
                            localId,
                            out FacilityStairProbeSnapshot previous)
                        && current.Admitted != previous.Admitted)
                    {
                        Console.WriteLine(
                            $"[facility-stair-decision] frame={_facilityStairsCurrentFrame} "
                            + $"local=0x{localId:X8} cell=0x{current.CellId:X8} "
                            + $"admitted={(previous.Admitted ? 1 : 0)}->"
                            + $"{(current.Admitted ? 1 : 0)} "
                            + $"screen={(current.ScreenIntersect ? 1 : 0)} "
                            + $"ndc={current.ScreenBounds}");
                    }
                }
            }

            Dictionary<uint, FacilityStairProbeSnapshot> swap =
                _facilityStairsPrevious;
            _facilityStairsPrevious = _facilityStairsCurrent;
            _facilityStairsCurrent = swap;
            _facilityStairsCurrent.Clear();
            _facilityStairsPreviousFrame = _facilityStairsCurrentFrame;
        }

        _facilityStairsCurrentFrame = frame;
    }

    private static bool TryProjectFacilityStairBounds(
        ObjectRenderData renderData,
        Matrix4x4 localToWorld,
        Matrix4x4 viewProjection,
        out string bounds)
    {
        Vector3 min = renderData.BoundingBox.Min;
        Vector3 max = renderData.BoundingBox.Max;
        float minX = float.PositiveInfinity;
        float minY = float.PositiveInfinity;
        float maxX = float.NegativeInfinity;
        float maxY = float.NegativeInfinity;
        int projected = 0;

        for (int corner = 0; corner < 8; corner++)
        {
            var local = new Vector3(
                (corner & 1) == 0 ? min.X : max.X,
                (corner & 2) == 0 ? min.Y : max.Y,
                (corner & 4) == 0 ? min.Z : max.Z);
            Vector3 world = Vector3.Transform(local, localToWorld);
            Vector4 clip = Vector4.Transform(new Vector4(world, 1f), viewProjection);
            if (!float.IsFinite(clip.W) || clip.W <= 0.0001f)
                continue;

            float x = clip.X / clip.W;
            float y = clip.Y / clip.W;
            if (!float.IsFinite(x) || !float.IsFinite(y))
                continue;
            minX = MathF.Min(minX, x);
            minY = MathF.Min(minY, y);
            maxX = MathF.Max(maxX, x);
            maxY = MathF.Max(maxY, y);
            projected++;
        }

        if (projected == 0)
        {
            bounds = "behind";
            return false;
        }

        bounds = $"({minX:F3},{minY:F3})-({maxX:F3},{maxY:F3});corners={projected}";
        return maxX >= -1f && minX <= 1f && maxY >= -1f && minY <= 1f;
    }

    internal static bool LookInDrawingSphereVisible(
        IWalkLookInViewSource lookInViews,
        int routeIndex,
        DatReaderWriter.Types.Sphere sphere,
        Matrix4x4 localToWorld,
        out Vector3 center,
        out float radius)
    {
        ArgumentNullException.ThrowIfNull(lookInViews);
        ArgumentNullException.ThrowIfNull(sphere);

        TransformDrawingSphere(sphere, localToWorld, out center, out radius);
        return lookInViews.SphereVisibleInLookInTurn(
            routeIndex,
            in center,
            radius);
    }

    private static void TransformDrawingSphere(
        DatReaderWriter.Types.Sphere sphere,
        Matrix4x4 localToWorld,
        out Vector3 center,
        out float radius)
    {
        center = Vector3.Transform(sphere.Origin, localToWorld);
        float scaleX = new Vector3(
            localToWorld.M11,
            localToWorld.M12,
            localToWorld.M13).Length();
        float scaleY = new Vector3(
            localToWorld.M21,
            localToWorld.M22,
            localToWorld.M23).Length();
        float scaleZ = new Vector3(
            localToWorld.M31,
            localToWorld.M32,
            localToWorld.M33).Length();
        radius = sphere.Radius
            * MathF.Max(scaleX, MathF.Max(scaleY, scaleZ));
    }

    /// <summary>
    /// Walks one resolved mesh's batches through <see cref="TryClassifyBatch"/>
    /// and appends every surviving one to <paramref name="sink"/> at
    /// <c>Alpha = 1f</c> (see this file's type doc comment for why statics
    /// never carry a per-part opacity multiplier here). Campaign OVERHAUL S3
    /// chunk 4 (§10.2): both call sites now gate on <see
    /// cref="ResolvePartVisible"/>'s plain Boolean before calling this method
    /// at all — the FORMER per-view clip-SLOT list this method used to loop
    /// over always collapsed to either nothing (never reached this method;
    /// the caller's <c>firstAdmission</c> gate skips it) or the single
    /// <c>RetailWholeMeshSlot</c> sentinel, so looping was never anything but
    /// one iteration in practice. <paramref name="slot"/> (the entity's OWN
    /// clip slot — always 0, see <see cref="ResolveSlotForFrame"/>'s own doc
    /// comment for why the routing that used to vary this is deleted) is
    /// therefore the ONE clip slot every surviving batch carries.
    /// </summary>
    private void EmitClassifiedBatches(
        ObjectRenderData renderData,
        Matrix4x4 model,
        in RenderInstanceCandidate entity,
        MeshRef meshRef,
        PaletteCompositeIdentity paletteIdentity,
        bool? entityHasCutoutSubsetOverride,
        uint slot,
        InstanceLightSet lights,
        bool indoor,
        Vector2 selectionLighting,
        uint detailCategory,
        float opacity,
        List<WalkClassifiedBatch> sink)
    {
        bool entityHasCutoutSubset = entityHasCutoutSubsetOverride ?? renderData.HasCutoutSubset;
        for (int batchIdx = 0; batchIdx < renderData.Batches.Count; batchIdx++)
        {
            bool survives = TryClassifyBatch(
                renderData, batchIdx, in entity, meshRef, paletteIdentity,
                opacityMultiplier: opacity, entityHasCutoutSubset,
                out GroupKey key, out _);
            if (!survives)
                continue;

            sink.Add(new WalkClassifiedBatch(
                key, model, slot, lights, indoor ? 1u : 0u, Alpha: opacity,
                selectionLighting, detailCategory, IsOpaque: IsOpaque(key.Translucency),
                LocalSortCenter: renderData.SortCenter));
        }
    }

    /// <summary>
    /// The thin internal publish seam <c>WalkStaticStreamPopulator</c>
    /// calls for every <see cref="WalkClassifiedSelectionPart"/>
    /// <see cref="ClassifyEntityForWalk"/> surfaced — same call shape as
    /// <c>AddPackedSelectionPart</c>'s <c>publishSelection: true</c> branch.
    /// Keeps <c>_selectionSink</c> encapsulated: the populator lives outside
    /// the dispatcher and must not reach the field directly.
    /// </summary>
    internal void PublishWalkSelectionPart(in WalkClassifiedSelectionPart part) =>
        _selectionSink?.AddVisiblePart(
            part.ServerGuid, part.LocalEntityId, part.PartIndex, part.GfxObjId, part.LocalToWorld);

    /// <summary>
    /// The walk populator's per-instance sibling of <c>DeferTransparentGroups</c>
    /// (see that method for the retail citations this mirrors): submits ONE
    /// translucent <see cref="WalkClassifiedBatch"/> into the same
    /// <c>_deferredAlpha</c>/<see cref="RetailAlphaQueue"/> machinery the
    /// classic material-grouped path uses, so scenery, particles, and walk
    /// content share retail's one stable far-to-near stream. Same
    /// view-projection consistency check, same
    /// <see cref="RetailAlphaOrdering.ComputeViewerDistance"/> call, same
    /// <c>queue.Submit</c> contract — the walk path denormalizes to one
    /// instance per call instead of flattening a material group.
    /// </summary>
    internal void SubmitWalkAlphaInstance(
        in WalkClassifiedBatch batch,
        Vector3 cameraWorldPosition,
        Matrix4x4 viewProjection)
    {
        RetailAlphaQueue queue = _alphaQueue
            ?? throw new InvalidOperationException(
                "SubmitWalkAlphaInstance requires an active RetailAlphaQueue.");

        if (_deferredAlpha.Count == 0)
            _deferredAlphaViewProjection = viewProjection;
        else if (_deferredAlphaViewProjection != viewProjection)
            throw new InvalidOperationException(
                "One retail alpha scope cannot combine different view-projection matrices.");

        float viewerDistance = RetailAlphaOrdering.ComputeViewerDistance(
            batch.LocalSortCenter, batch.Transform, cameraWorldPosition);
        if (!float.IsFinite(viewerDistance) || viewerDistance <= 0f)
            viewerDistance = 0f;

        int token = _deferredAlpha.Count;
        _deferredAlpha.Add(new DeferredAlphaInstance(
            batch.Key, batch.Transform, batch.ClipSlot, batch.Lights,
            batch.IndoorFlag, batch.DetailCategory, batch.Alpha, batch.SelectionLighting));
        queue.Submit(_alphaSource, token, viewerDistance);
    }
}