acdream/src/AcDream.App/Input/PlayerModeAutoEntry.cs

using System;

namespace AcDream.App.Input;

/// <summary>
/// Phase K.2 — one-shot guard that auto-enters player mode after a
/// successful login once every prerequisite is satisfied. Owned by
/// <c>GameWindow</c> and ticked each frame from <c>OnUpdate</c>.
///
/// <para>
/// Why is this its own class? The auto-entry has four independent
/// preconditions (live session reaches <c>InWorld</c>, the player
/// entity has been streamed into the world dictionary, the player
/// movement controller is constructible, and the terrain under the
/// spawn position has streamed in) plus a manual-override path
/// (the user can flip into fly mode before the auto-entry fires —
/// their choice wins). All five interact with each other in a way
/// that's painful to test through GameWindow but trivial here against
/// fakes.
/// </para>
///
/// <para>
/// The public surface is:
/// <list type="bullet">
/// <item><see cref="Arm"/> — call after <c>EnterWorld</c> succeeds to
/// arm the entry trigger.</item>
/// <item><see cref="Cancel"/> — call when the user manually enters
/// fly mode (or any other code path that pre-empts the auto-entry).</item>
/// <item><see cref="TryEnter"/> — call once per frame; runs the
/// guard and fires the entry callback when armed AND every
/// precondition is satisfied; returns true on the firing tick.</item>
/// </list>
/// </para>
///
/// <para>
/// All preconditions are passed in as predicates so the class doesn't
/// pull in <c>WorldSession</c>, <c>PlayerMovementController</c>, or
/// any GameWindow-internal types — the unit test wires them to plain
/// boolean fields.
/// </para>
/// </summary>
public sealed class PlayerModeAutoEntry
{
    private readonly Func<bool> _isLiveInWorld;
    private readonly Func<bool> _isPlayerEntityPresent;
    private readonly Func<bool> _isPlayerControllerReady;
    private readonly Func<bool> _isSpawnGroundReady;
    private readonly Action     _enterPlayerMode;

    private bool _armed;

    /// <summary>
    /// Build an auto-entry guard.
    /// </summary>
    /// <param name="isLiveInWorld">True iff the live session is in the
    /// <c>InWorld</c> state. Skip auto-entry when the session is null
    /// or hasn't reached InWorld yet.</param>
    /// <param name="isPlayerEntityPresent">True iff the player's
    /// server-guid is already in the local entity dictionary (server
    /// has streamed at least one CreateObject for the character).</param>
    /// <param name="isPlayerControllerReady">True iff the per-frame
    /// PlayerMovementController is set up. Stays true once player mode
    /// is established; the auto-entry's job is to flip it from false
    /// to true exactly once.</param>
    /// <param name="isSpawnGroundReady">True iff the terrain under the
    /// player's spawn position has streamed into the physics engine.
    /// #106 gate-2 (2026-06-09): entering player mode earlier integrates
    /// gravity against an empty world and free-falls the player into the
    /// void. Retail never has this state — it loads cells synchronously;
    /// this hold is the async-streaming equivalent of that invariant.</param>
    /// <param name="enterPlayerMode">Action invoked on the firing
    /// tick. The same routine the manual Tab handler invokes (fly →
    /// player transition). Must construct the controller + chase
    /// camera and switch the active camera; the auto-entry doesn't
    /// reach inside.</param>
    public PlayerModeAutoEntry(
        Func<bool> isLiveInWorld,
        Func<bool> isPlayerEntityPresent,
        Func<bool> isPlayerControllerReady,
        Func<bool> isSpawnGroundReady,
        Action     enterPlayerMode)
    {
        _isLiveInWorld           = isLiveInWorld           ?? throw new ArgumentNullException(nameof(isLiveInWorld));
        _isPlayerEntityPresent   = isPlayerEntityPresent   ?? throw new ArgumentNullException(nameof(isPlayerEntityPresent));
        _isPlayerControllerReady = isPlayerControllerReady ?? throw new ArgumentNullException(nameof(isPlayerControllerReady));
        _isSpawnGroundReady      = isSpawnGroundReady      ?? throw new ArgumentNullException(nameof(isSpawnGroundReady));
        _enterPlayerMode         = enterPlayerMode         ?? throw new ArgumentNullException(nameof(enterPlayerMode));
    }

    /// <summary>True iff <see cref="TryEnter"/> would still fire if the
    /// preconditions become true. Flips false on a successful entry
    /// (one-shot) or when <see cref="Cancel"/> is invoked.</summary>
    public bool IsArmed => _armed;

    /// <summary>
    /// Arm the trigger. Call after <c>WorldSession.EnterWorld</c>
    /// returns successfully. Calling again while already armed is a
    /// no-op.
    /// </summary>
    public void Arm() => _armed = true;

    /// <summary>
    /// Disarm the trigger without firing the callback. Call when the
    /// user has manually entered fly mode (or any other code path
    /// that pre-empts the auto-entry) — the user's choice wins.
    /// </summary>
    public void Cancel() => _armed = false;

    /// <summary>
    /// Guard tick. If the trigger is armed AND every precondition is
    /// satisfied, invokes <c>enterPlayerMode</c>, disarms, and
    /// returns true. Returns false otherwise (no side effects).
    /// </summary>
    public bool TryEnter()
    {
        if (!_armed) return false;
        if (!_isLiveInWorld()) return false;
        if (!_isPlayerEntityPresent()) return false;
        if (!_isPlayerControllerReady()) return false;
        if (!_isSpawnGroundReady()) return false;

        _armed = false;
        _enterPlayerMode();
        return true;
    }
}