namespace AcDream.Core.World;

/// <summary>
/// Should the streaming/render pipeline be allowed to run this frame?
///
/// <para>
/// <b>Why this exists (#192, 2026-07-09).</b> Login to a non-Holtburg position
/// sometimes showed stabs/scenery floating in the wrong place. Root cause: the
/// old gate opened as soon as <c>WorldSession</c> reached <c>InWorld</c> — but
/// <c>InWorld</c> fires immediately after the login handshake completes
/// (<c>WorldSession.cs:608</c>), BEFORE the player's own spawn <c>CreateObject</c>
/// (which carries their real position) has even arrived over the network. Any
/// landblock streamed in that window baked its world offset from
/// <c>GameWindow._liveCenterX/Y</c>'s startup placeholder (Holtburg, 0xA9B4) — a
/// real position, not a "not known yet" sentinel — because the streaming worker
/// reads that field fresh at build time with no way to know it's still a guess.
/// That stale-baked geometry still got applied once its build finished, landing
/// wherever the guess put it relative to whatever streamed in afterward using the
/// corrected center.
/// </para>
///
/// <para>
/// The fix is not "pick a better placeholder" — any placeholder racing against
/// the real answer reproduces the same bug. It's gating on whether the real
/// position is actually known yet (<paramref name="liveCenterKnown"/>, set true
/// exactly when the player's own spawn is processed), independent of session
/// state. <paramref name="liveInWorld"/> alone is deliberately no longer
/// sufficient in live mode.
/// </para>
/// </summary>
public static class StreamingReadinessGate
{
    /// <param name="liveModeEnabled">Whether a live ACE session is configured at all.
    /// False (offline / fly-camera) always streams — there is no real position to
    /// wait for, so no race exists.</param>
    /// <param name="chaseModeEverEntered">Latches true the first time chase mode
    /// engages and stays true for the rest of the session — well past the login
    /// race window.</param>
    /// <param name="liveInWorld">The live session has completed the login handshake
    /// (<c>WorldSession.State.InWorld</c>). Necessary but NOT sufficient on its
    /// own — see class remarks.</param>
    /// <param name="liveCenterKnown">The player's own spawn <c>CreateObject</c> has
    /// been received and processed, so <c>_liveCenterX/Y</c> reflects a real,
    /// server-confirmed position rather than the startup placeholder.</param>
    public static bool ShouldStream(
        bool liveModeEnabled, bool chaseModeEverEntered, bool liveInWorld, bool liveCenterKnown)
    {
        bool isWaitingForLogin = liveModeEnabled && !chaseModeEverEntered;
        return !isWaitingForLogin || (liveInWorld && liveCenterKnown);
    }
}