acdream/src/AcDream.App/Rendering/GameWindow.cs

using AcDream.Core.Plugins;
using DatReaderWriter;
using DatReaderWriter.Options;
using Silk.NET.Input;
using Silk.NET.Maths;
using Silk.NET.OpenGL;
using Silk.NET.Windowing;

namespace AcDream.App.Rendering;

public sealed class GameWindow : IDisposable
{
    private readonly string _datDir;
    private readonly WorldGameState _worldGameState;
    private readonly WorldEvents _worldEvents;
    private IWindow? _window;
    private GL? _gl;
    private IInputContext? _input;
    private TerrainChunkRenderer? _terrain;
    private Shader? _shader;
    private CameraController? _cameraController;
    private IMouse? _capturedMouse;
    private DatCollection? _dats;
    private float _lastMouseX;
    private float _lastMouseY;
    private InstancedMeshRenderer? _staticMesh;
    private Shader? _meshShader;
    private TextureCache? _textureCache;
    private DebugLineRenderer? _debugLines;
    // K-fix4 (2026-04-26): default OFF. The orange BSP / green cylinder
    // wireframes are noisy outdoors and confuse first-time users into
    // thinking they're a rendering bug. Ctrl+F2 toggles, the DebugPanel
    // → Diagnostics → "Toggle collision wires" button toggles too.
    private bool _debugCollisionVisible = false;
    private int _debugDrawLogOnce = 0;

    // Phase I.2: the old StbTrueTypeSharp DebugOverlay was deleted in
    // favor of the ImGui-backed DebugPanel (see _debugVm below). The
    // TextRenderer + BitmapFont fields stay alive because they're shared
    // with UiHost and reserved for the future world-space HUD (D.6 —
    // damage floaters, name plates) where ImGui can't reach into the 3D
    // scene. They are no longer used for any debug overlay.
    private TextRenderer? _textRenderer;
    private BitmapFont? _debugFont;
    // Last-computed perf values so the HUD always has something to show even
    // though the title-bar FPS is only updated every 0.5s.
    private double _lastFps = 60.0;
    private double _lastFrameMs = 16.7;

    // Phase I.2: per-frame counters surfaced through the ImGui DebugPanel
    // VM closures. Computed once per render pass alongside the frustum
    // walk + nearest-object scan; the VM closures just read the cached
    // values. Skipped when DevTools are off (zero cost).
    private int    _lastVisibleLandblocks;
    private int    _lastTotalLandblocks;
    private float  _lastNearestObjDist = float.PositiveInfinity;
    private string _lastNearestObjLabel = "-";
    private bool   _lastColliding;

    // Phase A.1: streaming fields replacing the one-shot _entities list.
    private AcDream.App.Streaming.LandblockStreamer? _streamer;
    private readonly AcDream.App.Streaming.GpuWorldState _worldState = new();
    private AcDream.App.Streaming.StreamingController? _streamingController;
    private int _streamingRadius = 2;  // default 5×5
    private uint? _lastLivePlayerLandblockId;

    // Phase B.3: physics engine — populated from the streaming pipeline.
    private readonly AcDream.Core.Physics.PhysicsEngine _physicsEngine = new();

    // Task 4: physics data cache — BSP trees + collision shapes extracted from
    // GfxObj/Setup dats during streaming. Populated on the worker thread;
    // ConcurrentDictionary inside makes cross-thread access safe.
    private readonly AcDream.Core.Physics.PhysicsDataCache _physicsDataCache = new();

    // Step 4: portal-based interior cell visibility.
    private readonly CellVisibility _cellVisibility = new();

    // Phase A.1 hotfix: DatCollection is NOT thread-safe. The streaming worker
    // thread and the render thread both read dats (BuildLandblockForStreaming
    // on the worker; ApplyLoadedTerrain + live-spawn handlers on the render
    // thread). Concurrent reads corrupt internal caches and produce
    // half-populated LandBlock.Height[] arrays, which caused terrain to render
    // as "a giant ball with spikes" before this lock was added. All _dats.Get
    // calls that can race with the worker thread MUST acquire this lock.
    private readonly object _datLock = new();

    // Terrain build context shared across all streamed landblocks. Stored as
    // fields so ApplyLoadedTerrain (render-thread callback) can call
    // LandblockMesh.Build without re-deriving these each time.
    private float[]? _heightTable;
    private AcDream.Core.Terrain.TerrainBlendingContext? _blendCtx;
    private Dictionary<uint, AcDream.Core.Terrain.SurfaceInfo>? _surfaceCache;

    // Phase A.1 Task 8: worker thread pre-builds EnvCell room-mesh sub-meshes
    // (CPU only) and stores them here. ApplyLoadedTerrain (render thread) drains
    // this dict and uploads them via EnsureUploaded before the per-MeshRef loop.
    // ConcurrentDictionary is required because the worker and render threads
    // access this simultaneously without a broader lock.
    private readonly System.Collections.Concurrent.ConcurrentDictionary<
        uint, System.Collections.Generic.IReadOnlyList<AcDream.Core.Meshing.GfxObjSubMesh>>
        _pendingCellMeshes = new();

    // Step 4: pending LoadedCell objects built on the worker thread, drained
    // to _cellVisibility on the render thread in ApplyLoadedTerrain.
    private readonly System.Collections.Concurrent.ConcurrentBag<LoadedCell> _pendingCells = new();

    /// <summary>
    /// Phase 6.4: per-entity animation playback state for entities whose
    /// MotionTable resolved to a real cycle. The render loop ticks each
    /// of these every frame, advances the current frame number, then
    /// rebuilds the entity's MeshRefs by re-flattening the Setup against
    /// the new <see cref="DatReaderWriter.Types.AnimationFrame"/>.
    /// Static decorations and entities with no motion table never
    /// appear in this map.
    /// </summary>
    private readonly Dictionary<uint, AnimatedEntity> _animatedEntities = new();

    private sealed class AnimatedEntity
    {
        public required AcDream.Core.World.WorldEntity Entity;
        public required DatReaderWriter.DBObjs.Setup Setup;
        public required DatReaderWriter.DBObjs.Animation Animation;
        public required int LowFrame;
        public required int HighFrame;
        public required float Framerate;     // frames per second
        public required float Scale;         // server ObjScale baked into part transforms each tick
        /// <summary>
        /// Per-part identity carried over from the hydration pass: the
        /// (post-AnimPartChanges) GfxObjId and the (post-resolution)
        /// surface override map. The transform is recomputed every tick
        /// from the current animation frame; only these two fields are
        /// reused unchanged.
        /// </summary>
        public required IReadOnlyList<(uint GfxObjId, IReadOnlyDictionary<uint, uint>? SurfaceOverrides)> PartTemplate;
        public float CurrFrame;              // monotonically increasing within [LowFrame, HighFrame]
        public AcDream.Core.Physics.AnimationSequencer? Sequencer;
    }

    private AcDream.Core.Physics.DatCollectionLoader? _animLoader;

    // Phase E.1: central fan-out for animation hooks. Audio (E.2),
    // particles (E.3), combat (E.4), and renderer state mutators all
    // register sinks at startup. The router is always non-null so the
    // per-entity tick loop can just call it unconditionally.
    private readonly AcDream.Core.Physics.AnimationHookRouter _hookRouter = new();

    // Phase E.2 audio. Null when ACDREAM_NO_AUDIO=1 or the OpenAL driver
    // failed to init; all three are set together.
    private AcDream.App.Audio.OpenAlAudioEngine? _audioEngine;
    private AcDream.Core.Audio.DatSoundCache? _soundCache;
    private AcDream.App.Audio.DictionaryEntitySoundTable? _entitySoundTables;
    private AcDream.App.Audio.AudioHookSink? _audioSink;

    // Phase E.3 particles.
    private readonly AcDream.Core.Vfx.EmitterDescRegistry _emitterRegistry = new();
    private AcDream.Core.Vfx.ParticleSystem? _particleSystem;
    private AcDream.Core.Vfx.ParticleHookSink? _particleSink;
    // Phase 6 — retail PhysicsScript runtime. Receives PlayScript (0xF754)
    // from the server and schedules the dat-defined hooks (particle spawns,
    // sounds, light toggles) at their StartTime offsets.
    private AcDream.Core.Vfx.PhysicsScriptRunner? _scriptRunner;
    private AcDream.App.Rendering.ParticleRenderer? _particleRenderer;

    // Remote-entity motion inference: tracks when each remote entity last
    // moved meaningfully. Used in TickAnimations to swap to Ready when
    // position has stalled for >StopIdleMs — retail observer pattern per
    // ACE Player_Tick.cs line 368: the client never sends "released forward"
    // MoveToState, so the server never broadcasts an explicit stop. Observer
    // must infer it from position deltas.
    private readonly Dictionary<uint, (System.Numerics.Vector3 Pos, System.DateTime Time)>
        _remoteLastMove = new();

    /// <summary>
    /// Per-remote-entity dead-reckoning state for smoothing between server
    /// UpdatePosition broadcasts. Without this, remote characters teleport
    /// every ~100–200 ms when the server pushes a new position (the retail
    /// client hides the gap by integrating <c>CMotionInterp</c>-surfaced
    /// velocity forward each tick — see chunk_00520000.c
    /// <c>apply_current_movement</c> L7132-L7189 and holtburger's
    /// <c>spatial/physics.rs::project_pose_by_velocity</c>).
    ///
    /// <para>
    /// Each entry records the last authoritative server position + time + a
    /// measured velocity inferred from the delta between consecutive
    /// UpdatePositions. The client's per-tick integrator uses the
    /// sequencer's <c>CurrentVelocity</c> (rotated into world space by the
    /// entity's orientation) as the primary source and falls back to the
    /// inferred velocity when the motion table doesn't carry one (e.g. NPC
    /// motion tables with HasVelocity=0).
    /// </para>
    /// </summary>
    private readonly Dictionary<uint, RemoteMotion> _remoteDeadReckon = new();

    /// <summary>
    /// Per-remote-entity physics + motion stack — verbatim application of
    /// retail's client-side motion pipeline to every remote. Mirrors
    /// retail <c>FUN_00515020</c> <c>update_object</c> → <c>FUN_00513730</c>
    /// <c>UpdatePositionInternal</c> → <c>FUN_005111D0</c>
    /// <c>UpdatePhysicsInternal</c>, and ACE's <c>PhysicsObj.cs</c> port.
    ///
    /// <para>
    /// Retail has NO special "interpolator" for remote entities — it runs
    /// the full motion state machine on every entity, local or remote,
    /// and reconciles via hard-snap on UpdatePosition. This class simply
    /// pairs a <see cref="AcDream.Core.Physics.PhysicsBody"/> with its
    /// <see cref="AcDream.Core.Physics.MotionInterpreter"/> so each
    /// remote gets the same treatment as the local player.
    /// </para>
    /// </summary>
    private sealed class RemoteMotion
    {
        public AcDream.Core.Physics.PhysicsBody Body;
        public AcDream.Core.Physics.MotionInterpreter Motion;
        /// <summary>Last UpdatePosition timestamp — drives body.update_object sub-stepping.</summary>
        public double LastServerPosTime;
        /// <summary>Last known server position — kept for diagnostics / HUD.</summary>
        public System.Numerics.Vector3 LastServerPos;
        /// <summary>
        /// Legacy field — no longer used for slerp (retail hard-snaps
        /// per FUN_00514b90 set_frame). Kept to avoid churn.
        /// </summary>
        public System.Numerics.Quaternion TargetOrientation = System.Numerics.Quaternion.Identity;
        /// <summary>
        /// Angular velocity seeded from UpdateMotion TurnCommand/TurnSpeed
        /// (π/2 × turnSpeed, signed). Applied per tick to body orientation
        /// via manual integration (bypassing <c>PhysicsBody.update_object</c>'s
        /// MinQuantum 30fps gate that would otherwise skip most ticks).
        /// Zeroed on UM with TurnCommand absent.
        /// </summary>
        public System.Numerics.Vector3 ObservedOmega;
        /// <summary>
        /// Full 32-bit cell ID from the latest UpdatePosition. High 16 bits
        /// = landblock (LBx,LBy), low 16 bits = cell index (outdoor 0x0001-
        /// 0x0040, indoor 0x0100+). Fed into
        /// <see cref="AcDream.Core.Physics.PhysicsEngine.ResolveWithTransition"/>
        /// so the retail sphere-sweep can look up the right terrain/EnvCell
        /// polygons for each remote's per-frame motion. Zero until the first
        /// UP lands, which disables the transition step for that frame
        /// (Euler alone, matching pre-wire behavior).
        /// </summary>
        public uint CellId;

        /// <summary>
        /// K-fix9 (2026-04-26): true while the remote is airborne (jump
        /// arc in flight). Set when a 0xF74E VectorUpdate arrives with
        /// non-trivial +Z velocity; cleared when the next UpdatePosition
        /// snaps to a new ground location. While true, the per-tick
        /// remote update SKIPS the "force OnWalkable + apply_current_movement"
        /// step that would otherwise stomp the body's Z velocity each
        /// frame, AND enables gravity so the parabolic arc actually plays
        /// out between server snaps.
        /// </summary>
        public bool Airborne;

        public RemoteMotion()
        {
            Body = new AcDream.Core.Physics.PhysicsBody
            {
                // Remotes don't simulate gravity — server owns Z. Force
                // Contact + OnWalkable + Active so apply_current_movement
                // writes velocity through every tick (the gate in
                // MotionInterpreter.apply_current_movement is
                // PhysicsObj.OnWalkable).
                State = AcDream.Core.Physics.PhysicsStateFlags.ReportCollisions,
                TransientState = AcDream.Core.Physics.TransientStateFlags.Contact
                               | AcDream.Core.Physics.TransientStateFlags.OnWalkable
                               | AcDream.Core.Physics.TransientStateFlags.Active,
            };
            Motion = new AcDream.Core.Physics.MotionInterpreter(Body);
        }
    }

    /// <summary>Soft-snap decay rate (1/sec). At this rate the residual
    /// halves every 1/rate seconds. 8.0 → ~100ms half-life, so even a
    /// 2m residual fades within ~300ms without visible snap.</summary>
    private const float SnapResidualDecayRate = 8.0f;
    /// <summary>
    /// When the prediction error exceeds this many meters, we treat the
    /// update as a teleport / rubber-band and hard-snap (no soft lerp).
    /// Prevents the soft-snap logic from trying to smooth a genuine portal
    /// or force-move event.
    ///
    /// <para>
    /// Matches retail's <c>GetAutonomyBlipDistance</c> (ACE
    /// <c>PhysicsObj.cs:545</c>): 20m for creatures, 25m for players.
    /// We use 20m as a conservative default — any delta larger than this
    /// must be a teleport (portal, recall, spawn). A running character
    /// with 1-second UpdatePosition cadence at 9.5 m/s produces deltas
    /// of ~9.5m, well below this threshold, so normal movement flows
    /// through the interpolation queue instead of hard-snapping.
    /// </para>
    /// </summary>
    private const float SnapHardSnapThreshold = 20.0f;

    /// <summary>
    /// Soft-snap window in seconds: after an UpdatePosition arrives for a
    /// remote entity, dead-reckoning continues but the "origin" for
    /// predicted position is the server pos. This matches retail's snap
    /// behavior — the server is authoritative, we just interpolate between
    /// authoritative samples.
    /// </summary>
    private const float DeadReckonMaxPredictSeconds = 1.0f;

    // Phase F.1-H.1 — client-side state classes fed by GameEventWiring.
    // Exposed publicly so plugins + UI panels can bind directly.
    public readonly AcDream.Core.Chat.ChatLog Chat = new();
    // Phase I.6 — runtime state for retail's TurbineChat (0xF7DE) global
    // chat rooms. Empty/disabled until the server fires
    // SetTurbineChatChannels (0x0295) shortly after EnterWorld.
    public readonly AcDream.Core.Chat.TurbineChatState TurbineChat = new();
    public readonly AcDream.Core.Combat.CombatState Combat = new();
    // Issue #11 — load static spell metadata from data/spells.csv at startup.
    // Provides Family for buff stacking (issue #6) + names + icons + tooltips
    // for the future Spellbook panel. The CSV is copied to bin/<config>/net10.0/data/
    // by the csproj <None Include="...spells.csv"> entry. Loads silently to
    // SpellTable.Empty if the file is missing (e.g. tooling contexts).
    public readonly AcDream.Core.Spells.SpellTable SpellTable = LoadSpellTable();
    public readonly AcDream.Core.Spells.Spellbook SpellBook = null!;
    public readonly AcDream.Core.Items.ItemRepository Items = new();
    // Issue #5 — caches CreatureProfile.{Stamina, Mana, *Max} from
    // PlayerDescription so the Vitals HUD can render those bars.
    // Issue #6 — wired to SpellBook so GetMaxApprox folds enchantment
    // buffs into the max formula via Spellbook.GetVitalMod.
    public readonly AcDream.Core.Player.LocalPlayerState LocalPlayer = null!;

    // Phase D.2a — ImGui devtools UI overlay. Null unless ACDREAM_DEVTOOLS=1.
    // See docs/plans/2026-04-24-ui-framework.md for the staged UI strategy.
    private AcDream.UI.ImGui.ImGuiBootstrapper? _imguiBootstrap;
    private AcDream.UI.ImGui.ImGuiPanelHost? _panelHost;
    private AcDream.UI.Abstractions.Panels.Vitals.VitalsVM? _vitalsVm;
    // Phase I.2: ImGui debug panel ViewModel. Lives for as long as
    // _panelHost does. Self-subscribes to CombatState in its ctor, so
    // disposing isn't required (panel host holds the only ref).
    private AcDream.UI.Abstractions.Panels.Debug.DebugVM? _debugVm;
    private static readonly bool DevToolsEnabled =
        Environment.GetEnvironmentVariable("ACDREAM_DEVTOOLS") == "1";

    // Phase I.3 — real ICommandBus for live sessions. Constructed when
    // the live session spins up (so SendChatCmd handlers can close over
    // _liveSession + Chat). Null when offline; PanelContext then falls
    // back to NullCommandBus.Instance.
    private AcDream.UI.Abstractions.LiveCommandBus? _commandBus;

    // Phase I.7 — bridges CombatState's typed events into ChatLog as
    // retail-faithful "You hit ..." / "... evaded your attack." lines.
    // Disposable; lives for the duration of the live session.
    private AcDream.Core.Chat.CombatChatTranslator? _combatChatTranslator;

    // Phase G.1-G.2 world lighting/time state.
    public readonly AcDream.Core.World.WorldTimeService WorldTime =
        new AcDream.Core.World.WorldTimeService(
            AcDream.Core.World.SkyStateProvider.Default());
    public readonly AcDream.Core.Lighting.LightManager Lighting = new();
    public readonly AcDream.Core.World.WeatherSystem Weather = new();
    // Wired into the hook router in OnLoad so SetLightHook fires
    // from the animation pipeline flip the matching LightSource.IsLit.
    private AcDream.Core.Lighting.LightingHookSink? _lightingSink;

    // Phase G.1 sky renderer + shared UBO. Created once the GL context
    // exists in OnLoad; shared across every other renderer via
    // binding = 1 so terrain/mesh/instanced/sky all read the same
    // sun / ambient / fog / flash data per frame.
    private AcDream.App.Rendering.SceneLightingUboBinding? _sceneLightingUbo;
    private AcDream.App.Rendering.Sky.SkyRenderer? _skyRenderer;
    private AcDream.Core.World.LoadedSkyDesc? _loadedSkyDesc;

    // Phase 3a — retail-faithful per-Dereth-day weather roll. The active
    // DayGroup is re-picked deterministically whenever the server clock
    // crosses a DayTicks boundary. <c>long.MinValue</c> sentinel means
    // "no day rolled yet" so the first RefreshSkyForCurrentDay call
    // unconditionally installs a provider. See r12 §11 for the roller
    // semantics.
    private long _loadedSkyDayIndex = long.MinValue;
    private AcDream.Core.World.DayGroupData? _activeDayGroup;

    private double _weatherAccum;

    // F7 / F10 debug-cycle steps for time + weather. Initialized out of
    // range of the real values so the first press hits index 0 of the
    // cycle table cleanly.
    private int _timeDebugStep = 0;
    private int _weatherDebugStep = 0;

    // Phase B.2: player movement mode.
    private AcDream.App.Input.PlayerMovementController? _playerController;
    private AcDream.App.Rendering.ChaseCamera? _chaseCamera;
    private bool _playerMode;
    private uint _playerServerGuid;
    private uint? _playerCurrentAnimCommand;
    private float _playerCurrentAnimSpeed = 1f;
    private uint? _playerMotionTableId;  // server-sent MotionTable override for the player's character

    // K-fix7 (2026-04-26): server-authoritative Run + Jump skill values
    // received from PlayerDescription. -1 = "not yet received, fall back
    // to the controller's default (env-var or hardcoded 200/300)".
    // Captured by the GameEventWiring.WireAll callback the moment PD
    // arrives; pushed into _playerController via SetCharacterSkills both
    // immediately (if the controller already exists from auto-entry) and
    // again at every EnterPlayerModeNow so a player who Tab-toggles in
    // and out keeps the right skills.
    private int _lastSeenRunSkill = -1;
    private int _lastSeenJumpSkill = -1;
    // K.1b: this field is RESERVED — written when entering / leaving player
    // mode and previously fed mouse-X into MovementInput.MouseDeltaX. Now
    // never consumed by MovementInput (mouse never drives character yaw —
    // K.1b regression-prevention). Kept around as plumbing for the future
    // K.2 MMB-mouse-look path which will re-enable mouse → character-yaw
    // when MMB is held. The pragma silences the dead-write warning until K.2
    // wires the read-side back in.
#pragma warning disable CS0414 // assigned but never used — see comment above
    private float _playerMouseDeltaX;
#pragma warning restore CS0414

    // Mouse sensitivity multipliers — one per camera mode because the visual
    // feel is very different. Adjust via F8 / F9 for whichever mode is
    // currently active. Chase default is low because the character + camera
    // rotating together is overwhelming at fly speeds.
    private float _sensChase = 0.15f;
    private float _sensFly = 1.0f;
    private float _sensOrbit = 1.0f;

    // Right-mouse-button held → free-orbit the chase camera around the
    // player without turning the character. Release leaves the camera at
    // the orbited position (no snap back).
    private bool _rmbHeld;

    // K-fix1 (2026-04-26): autorun is a TOGGLE — Press Q to start
    // forward-running, press Q again (or any movement-cancel key like
    // X / S / Backward / Forward) to stop. Mirrors retail's
    // AutoRun action. While true, MovementInput.Forward is forced
    // true regardless of W's state.
    private bool _autoRunActive;

    // Phase K.2 — auto-enter player mode after a successful login. Armed
    // by the EnterWorld branch in BeginLiveSessionAsync; ticked from
    // OnUpdate; disarmed if the user manually enters fly mode (or any
    // other path that pre-empts the chase camera). Skipped entirely
    // offline (orbit camera stays the foreground). The class internally
    // tracks IsArmed; we read it via the guard rather than mirroring
    // the bool here.
    private AcDream.App.Input.PlayerModeAutoEntry? _playerModeAutoEntry;

    // Phase K.2 — MMB-hold instant mouse-look state. Live throughout
    // the session; flips Active on Press/Release. Defense-in-depth on
    // ImGui's WantCaptureMouse — the dispatcher already filters, but
    // OnWantCaptureMouseChanged also suspends the state if a panel
    // claims focus mid-hold.
    private AcDream.UI.Abstractions.Input.MouseLookState? _mouseLook;
    // Tracks the previous WantCaptureMouse value so we can fire the
    // changed-edge callback once per transition (vs every frame).
    private bool _lastWantCaptureMouse;
    // Cursor mode prior to entering MMB mouse-look. Restored on
    // release so the user lands back in the same camera mode as
    // before (raw for chase/fly, normal for orbit). Set non-null while
    // mouse-look is active.
    private Silk.NET.Input.CursorMode? _mouseLookSavedCursorMode;

    // Phase K.1b — single input path. Every keyboard/mouse-button reaction
    // flows through InputDispatcher.Fired (see OnInputAction below) or
    // IsActionHeld (per-frame polling for movement). The legacy direct
    // kb.KeyDown switch + mouse.MouseDown/MouseUp handlers are GONE; only
    // mouse.MouseMove survives as a direct handler because mouse-delta is
    // axis input, not chord input.
    private AcDream.App.Input.SilkKeyboardSource? _kbSource;
    private AcDream.App.Input.SilkMouseSource? _mouseSource;
    private AcDream.UI.Abstractions.Input.InputDispatcher? _inputDispatcher;
    // K.1c: load user-customized bindings from %LOCALAPPDATA%\acdream\keybinds.json,
    // falling back to the retail-faithful defaults if the file is missing
    // or corrupt. This is THE single source of truth for the keymap at
    // startup — no other call to RetailDefaults() / AcdreamCurrentDefaults()
    // should land in the GameWindow construction path.
    private readonly AcDream.UI.Abstractions.Input.KeyBindings _keyBindings = LoadStartupKeyBindings();

    private static AcDream.UI.Abstractions.Input.KeyBindings LoadStartupKeyBindings()
    {
        var path = AcDream.UI.Abstractions.Input.KeyBindings.DefaultPath();
        var bindings = AcDream.UI.Abstractions.Input.KeyBindings.LoadOrDefault(path);
        Console.WriteLine($"keybinds: loaded {bindings.All.Count} bindings from {path}");
        return bindings;
    }

    // Phase 4.7: optional live connection to an ACE server. Enabled only when
    // ACDREAM_LIVE=1 is in the environment — fully backward compatible with
    // the offline rendering pipeline.
    private AcDream.Core.Net.WorldSession? _liveSession;
    private int _liveCenterX;
    private int _liveCenterY;
    private uint _liveEntityIdCounter = 1_000_000u;  // well above any dat-hydrated id

    // K-fix1 (2026-04-26): cached at startup so per-frame branches are
    // single-flag reads instead of env-var lookups. True iff
    // ACDREAM_LIVE=1 was set when the window came up.
    private static readonly bool LiveModeEnabled =
        Environment.GetEnvironmentVariable("ACDREAM_LIVE") == "1";

    /// <summary>
    /// K-fix1 (2026-04-26): true iff live mode is configured AND we have
    /// NOT yet handed control to the chase camera. Gates initial
    /// streaming + scene rendering so the user never sees Holtburg flash
    /// before login completes — the screen stays at the sky/fog clear
    /// color until the player entity has spawned + the auto-entry guard
    /// has triggered <see cref="EnterPlayerModeFromAutoEntry"/>.
    /// Offline (LiveModeEnabled false) returns false → unchanged
    /// orbit-camera Holtburg view stays the foreground. Once chase mode
    /// is active the property latches false for the rest of the
    /// session, even if the user later toggles into fly mode (we don't
    /// want to re-blank the world after they've seen it).
    /// </summary>
    private bool IsLiveModeWaitingForLogin =>
        LiveModeEnabled
        && !_chaseModeEverEntered;

    // Latches true the first time chase mode becomes active. Used by
    // IsLiveModeWaitingForLogin to suppress the pre-login render gate
    // for subsequent fly-mode toggles.
    private bool _chaseModeEverEntered;

    /// <summary>
    /// Phase 6.6/6.7: server-guid → local WorldEntity lookup so
    /// UpdateMotion and UpdatePosition handlers can find the entity the
    /// server is talking about. The sequential <see cref="_liveEntityIdCounter"/>
    /// keys the render list; this parallel dictionary keys by server guid.
    /// </summary>
    private readonly Dictionary<uint, AcDream.Core.World.WorldEntity> _entitiesByServerGuid = new();
    private int _liveSpawnReceived;  // diagnostics
    private int _liveSpawnHydrated;
    private int _liveDropReasonNoPos;
    private int _liveDropReasonNoSetup;
    private int _liveDropReasonSetupDatMissing;
    private int _liveDropReasonNoMeshRefs;
    // Phase 6.4 animation-registration diagnostics
    private int _liveAnimRejectNoCycle;
    private int _liveAnimRejectFramerate;
    private int _liveAnimRejectSingleFrame;
    private int _liveAnimRejectPartFrames;

    public GameWindow(string datDir, WorldGameState worldGameState, WorldEvents worldEvents)
    {
        _datDir = datDir;
        _worldGameState = worldGameState;
        _worldEvents = worldEvents;
        SpellBook = new AcDream.Core.Spells.Spellbook(SpellTable);
        LocalPlayer = new AcDream.Core.Player.LocalPlayerState(SpellBook);
    }

    /// <summary>
    /// Issue #11 — load <c>data/spells.csv</c> from the bin output (copied
    /// there by the csproj). Returns <c>SpellTable.Empty</c> + logs a
    /// warning if the file is missing (e.g. when GameWindow is instantiated
    /// from tooling contexts that don't include the data folder).
    /// </summary>
    private static AcDream.Core.Spells.SpellTable LoadSpellTable()
    {
        string path = System.IO.Path.Combine(
            System.AppContext.BaseDirectory, "data", "spells.csv");
        try
        {
            if (System.IO.File.Exists(path))
            {
                var t = AcDream.Core.Spells.SpellTable.LoadFromCsv(path);
                Console.WriteLine($"spells: loaded {t.Count} entries from spells.csv");
                return t;
            }
            Console.WriteLine($"spells: data/spells.csv not found at {path}; using empty table");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"spells: load failed ({ex.Message}); using empty table");
        }
        return AcDream.Core.Spells.SpellTable.Empty;
    }

    public void Run()
    {
        var options = WindowOptions.Default with
        {
            Size = new Vector2D<int>(1280, 720),
            Title = "acdream — phase 1",
            API = new GraphicsAPI(
                ContextAPI.OpenGL,
                ContextProfile.Core,
                ContextFlags.ForwardCompatible,
                new APIVersion(4, 3)),
            VSync = false,  // off during development so the perf overlay shows true framerate
        };

        _window = Window.Create(options);
        _window.Load += OnLoad;
        _window.Update += OnUpdate;
        _window.Render += OnRender;
        _window.Closing += OnClosing;
        // L.0 Display tab: keep the GL viewport + camera aspect in sync
        // with the window framebuffer. Without this handler, resizing
        // the window (or applying a Display-tab Resolution change at
        // startup) leaves the viewport pinned to the original size —
        // user sees a small render in the corner of a big window.
        _window.FramebufferResize += OnFramebufferResize;

        _window.Run();
    }

    private void OnLoad()
    {
        // Task 7: wire the physics data cache into the engine so Transition can
        // run narrow-phase BSP tests during FindObjCollisions.
        _physicsEngine.DataCache = _physicsDataCache;

        _gl = GL.GetApi(_window!);
        _input = _window!.CreateInput();

        // Phase K.1b — every keyboard/mouse handler routes through the
        // InputDispatcher. The legacy direct kb.KeyDown / mouse.MouseDown
        // switches are gone; subscribers below own all game-side reactions.
        // We KEEP a direct mouse.MouseMove handler because mouse-delta is
        // axis input, not chord input — but with explicit WantCaptureMouse
        // gating and the previous "_playerMouseDeltaX +=" line dropped so
        // mouse delta NEVER drives character yaw (regression-prevention
        // per K.1b plan §D).
        var firstKb = _input.Keyboards.FirstOrDefault();
        var firstMouse = _input.Mice.FirstOrDefault();
        if (firstKb is not null && firstMouse is not null)
        {
            _kbSource = new AcDream.App.Input.SilkKeyboardSource(firstKb);
            _mouseSource = new AcDream.App.Input.SilkMouseSource(
                firstMouse,
                wantCaptureMouse:    () => DevToolsEnabled && ImGuiNET.ImGui.GetIO().WantCaptureMouse,
                wantCaptureKeyboard: () => DevToolsEnabled && ImGuiNET.ImGui.GetIO().WantCaptureKeyboard);
            _mouseSource.ModifierProbe = () => _kbSource.CurrentModifiers;
            _inputDispatcher = new AcDream.UI.Abstractions.Input.InputDispatcher(
                _kbSource, _mouseSource, _keyBindings);
            _inputDispatcher.Fired += OnInputAction;

            // Phase K.2 — MMB-hold instant mouse-look. The yaw mutator
            // drives _playerController.Yaw (the chase camera reads this
            // automatically via ChaseCamera.Update). Active only while
            // _playerController and _chaseCamera are live; the lambda
            // safely no-ops outside player mode.
            _mouseLook = new AcDream.UI.Abstractions.Input.MouseLookState(
                applyYawDelta: dYaw =>
                {
                    if (_playerController is not null) _playerController.Yaw += dYaw;
                });

            // Phase K.2 — auto-enter player mode after EnterWorld
            // succeeds. Predicates close over GameWindow state; the
            // entry callback flips into player mode via the same code
            // path TogglePlayerMode uses, just without the early-return
            // when the entity isn't ready (the third predicate
            // guarantees readiness before this fires).
            _playerModeAutoEntry = new AcDream.App.Input.PlayerModeAutoEntry(
                isLiveInWorld:           () => _liveSession is not null
                                              && _liveSession.CurrentState ==
                                                 AcDream.Core.Net.WorldSession.State.InWorld,
                isPlayerEntityPresent:   () => _entitiesByServerGuid.ContainsKey(_playerServerGuid),
                isPlayerControllerReady: () => true,
                enterPlayerMode:         EnterPlayerModeFromAutoEntry);
        }

        // Mouse delta handler — kept direct because Silk.NET delivers mouse
        // moves as continuous (x, y) positions, not chord events. We gate
        // on WantCaptureMouse so panel hover never drives camera. The
        // previous "_playerMouseDeltaX += dx * sens" branch is GONE — mouse
        // never drives character yaw in K.1b. RMB-held orbit is wired via
        // the dispatcher's AcdreamRmbOrbitHold action (subscriber sets
        // _rmbHeld below).
        foreach (var mouse in _input.Mice)
        {
            mouse.MouseMove += (m, pos) =>
            {
                // K.1b §E: explicit WantCaptureMouse defense-in-depth on the
                // surviving direct-mouse handler. Suppresses RMB orbit /
                // FlyCamera look while ImGui has the mouse focus.
                if (DevToolsEnabled && ImGuiNET.ImGui.GetIO().WantCaptureMouse)
                {
                    _lastMouseX = pos.X;
                    _lastMouseY = pos.Y;
                    return;
                }
                if (_cameraController is null) return;

                float dx = pos.X - _lastMouseX;
                float dy = pos.Y - _lastMouseY;

                if (_playerMode && _cameraController.IsChaseMode && _chaseCamera is not null)
                {
                    float sens = _sensChase;
                    if (_mouseLook is not null && _mouseLook.Active)
                    {
                        // Phase K.2 — MMB instant mouse-look. dx drives
                        // character yaw via the MouseLookState callback
                        // (which mutates _playerController.Yaw); the chase
                        // camera tracks the character automatically because
                        // ChaseCamera.Update reads the player yaw. So mouse-X
                        // here goes ONLY through ApplyDelta — no separate
                        // YawOffset write. dy still pitches the camera only.
                        _mouseLook.ApplyDelta(dx, sens);
                        _chaseCamera.AdjustPitch(dy * 0.003f * sens);
                    }
                    else if (_rmbHeld)
                    {
                        // Hold-RMB orbit: player stays the central point, camera
                        // free-orbits around. X rotates around, Y pitches. On release
                        // the camera STAYS at the new angle (no snap back).
                        // K.1b: this is the ONLY mouse-delta path that affects
                        // ANYTHING when in player mode — character yaw is
                        // dispatcher-only (A/D keys). K.2: MMB mouse-look path
                        // above takes precedence when active.
                        _chaseCamera.YawOffset -= dx * 0.004f * sens;
                        _chaseCamera.AdjustPitch(dy * 0.003f * sens);
                    }
                    // K-fix1 (2026-04-26): no default-pitch path. With
                    // neither MMB nor RMB held, mouse moves the cursor
                    // freely so the user can interact with panels +
                    // (eventually) click selectables in the world. Pitch
                    // is gated on a deliberate hold input.
                }
                else if (_cameraController.IsFlyMode)
                {
                    float sens = _sensFly;
                    _cameraController.Fly.Look(dx * sens, dy * sens);
                }
                else
                {
                    // Orbit-camera mode (offline / pre-login): hold LMB to
                    // drag-rotate. K.1b reads the mouse-button state via
                    // IMouseSource so all "is button held" queries go
                    // through the same abstraction the dispatcher uses.
                    float sens = _sensOrbit;
                    if (_mouseSource is not null && _mouseSource.IsHeld(MouseButton.Left))
                    {
                        _cameraController.Orbit.Yaw -= dx * 0.005f * sens;
                        _cameraController.Orbit.Pitch = Math.Clamp(
                            _cameraController.Orbit.Pitch + dy * 0.005f * sens,
                            0.1f, 1.5f);
                    }
                }
                _lastMouseX = pos.X;
                _lastMouseY = pos.Y;
            };
        }

        _gl.ClearColor(0.05f, 0.10f, 0.18f, 1.0f);
        _gl.Enable(EnableCap.DepthTest);

        string shadersDir = Path.Combine(AppContext.BaseDirectory, "Rendering", "Shaders");
        _shader = new Shader(_gl,
            Path.Combine(shadersDir, "terrain.vert"),
            Path.Combine(shadersDir, "terrain.frag"));

        _meshShader = new Shader(_gl,
            Path.Combine(shadersDir, "mesh_instanced.vert"),
            Path.Combine(shadersDir, "mesh_instanced.frag"));

        // Phase G.1/G.2: shared scene-lighting UBO. Stays bound at
        // binding=1 for the lifetime of the process — every shader that
        // declares `layout(std140, binding = 1) uniform SceneLighting`
        // reads from this without further intervention.
        _sceneLightingUbo = new SceneLightingUboBinding(_gl);

        _debugLines = new DebugLineRenderer(_gl, shadersDir);

        // Phase I.2: load a system monospace font + TextRenderer for the
        // future world-space HUD (D.6). The custom DebugOverlay is gone;
        // the ImGui DebugPanel handles all dev surfaces now. These fields
        // are reserved for future work — currently unused at the renderer
        // level. Skips silently if no font is available.
        var fontBytes = BitmapFont.TryLoadSystemMonospaceFont();
        if (fontBytes is not null)
        {
            _debugFont = new BitmapFont(_gl, fontBytes, pixelHeight: 15f, atlasSize: 512);
            _textRenderer = new TextRenderer(_gl, shadersDir);
            Console.WriteLine($"world-hud font: loaded {fontBytes.Length / 1024}KB, " +
                              $"atlas {_debugFont.AtlasWidth}x{_debugFont.AtlasHeight}, " +
                              $"lineHeight={_debugFont.LineHeight:F1}px (reserved for D.6 HUD)");
        }
        else
        {
            Console.WriteLine("world-hud font: no system monospace font found");
        }

        var orbit = new OrbitCamera { Aspect = _window!.Size.X / (float)_window.Size.Y };
        var fly = new FlyCamera { Aspect = _window.Size.X / (float)_window.Size.Y };
        _cameraController = new CameraController(orbit, fly);
        _cameraController.ModeChanged += OnCameraModeChanged;

        _dats = new DatCollection(_datDir, DatAccessType.Read);
        _animLoader = new AcDream.Core.Physics.DatCollectionLoader(_dats);

        // Phase E.3 particles: always-on, no driver dependency. Registered
        // with the hook router so CreateParticle / DestroyParticle /
        // StopParticle hooks fired from motion tables produce visible
        // spawns. The Tick call is driven from OnRender.
        _particleSystem = new AcDream.Core.Vfx.ParticleSystem(_emitterRegistry);
        _particleSink = new AcDream.Core.Vfx.ParticleHookSink(_particleSystem);
        _hookRouter.Register(_particleSink);

        // Phase 6c — PhysicsScript runner. Uses the DatCollection to
        // resolve PlayScript ids, and the same ParticleHookSink the
        // animation system uses, so CreateParticleHook fired from a
        // script spawns through the normal particle pipeline.
        _scriptRunner = new AcDream.Core.Vfx.PhysicsScriptRunner(_dats, _particleSink);

        // Phase G.2 lighting hooks: SetLightHook flips IsLit on
        // owner-tagged lights so ignite-torch animations light up,
        // extinguish-torch animations go dark.
        _lightingSink = new AcDream.Core.Lighting.LightingHookSink(Lighting);
        _hookRouter.Register(_lightingSink);

        // Phase E.2 audio: init OpenAL + hook sink. Suppressible via
        // ACDREAM_NO_AUDIO=1 for headless tests / broken audio drivers.
        if (Environment.GetEnvironmentVariable("ACDREAM_NO_AUDIO") != "1")
        {
            try
            {
                _soundCache = new AcDream.Core.Audio.DatSoundCache(_dats);
                _audioEngine = new AcDream.App.Audio.OpenAlAudioEngine();
                _entitySoundTables = new AcDream.App.Audio.DictionaryEntitySoundTable();
                if (_audioEngine.IsAvailable)
                {
                    _audioSink = new AcDream.App.Audio.AudioHookSink(
                        _audioEngine, _soundCache, _entitySoundTables);
                    _hookRouter.Register(_audioSink);
                    Console.WriteLine("audio: OpenAL engine ready (16 voices, 3D positional)");
                }
                else
                {
                    Console.WriteLine("audio: OpenAL unavailable (driver missing / headless) — audio disabled");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"audio: init failed: {ex.Message} — audio disabled");
            }
        }

        // L.0 follow-up — load + apply persisted Display / Audio settings
        // BEFORE the DevToolsEnabled block. The settings.json values
        // (resolution, vsync, FOV, master volume, etc) are runtime
        // settings, not devtools settings — a user running without
        // ACDREAM_DEVTOOLS=1 still expects their saved values to take
        // effect. The Settings PANEL (editing UI) is gated on devtools;
        // the persisted state is not. Caches values into fields so the
        // SettingsVM construction in the devtools block reads them
        // without re-loading.
        LoadAndApplyPersistedSettings();

        // Phase D.2a — ImGui devtools overlay. Zero cost when the env var
        // isn't set: no context creation, no per-frame branches hit.
        // See docs/plans/2026-04-24-ui-framework.md + memory/project_ui_architecture.md.
        if (DevToolsEnabled)
        {
            try
            {
                _imguiBootstrap = new AcDream.UI.ImGui.ImGuiBootstrapper(_gl!, _window!, _input!);
                _panelHost      = new AcDream.UI.ImGui.ImGuiPanelHost();

                // VitalsVM: GUID=0 at construction; set later at EnterWorld
                // (see the _playerServerGuid assignment path). Pre-login the
                // HP bar just reads 1.0 (safe default) — harmless. Stam/Mana
                // bars surface only after the first PlayerDescription has
                // populated LocalPlayer (Issue #5).
                _vitalsVm = new AcDream.UI.Abstractions.Panels.Vitals.VitalsVM(Combat, LocalPlayer);
                _vitalsPanel = new AcDream.UI.Abstractions.Panels.Vitals.VitalsPanel(_vitalsVm);
                _panelHost.Register(_vitalsPanel);

                // ChatPanel: reads the tail of the shared ChatLog. No GUID
                // dependency — works pre-login (empty) and post-login (live
                // tail of received speech/tells/channels/system msgs).
                // FpsProvider + PositionProvider plumb the runtime state
                // the client-side /framerate and /loc commands need; the
                // panel asks the VM, the VM asks GameWindow via these
                // delegates, no panel-vs-renderer-vs-state coupling.
                var chatVm = new AcDream.UI.Abstractions.Panels.Chat.ChatVM(Chat)
                {
                    FpsProvider      = () => (float)_lastFps,
                    PositionProvider = () => GetDebugPlayerPosition(),
                };
                _chatPanel = new AcDream.UI.Abstractions.Panels.Chat.ChatPanel(chatVm);
                _panelHost.Register(_chatPanel);

                // Phase I.2: DebugPanel — replaces the deleted custom
                // DebugOverlay (six floating panels + hint bar + toast).
                // The VM closes over every data source the old snapshot
                // record exposed; reads are live (no per-frame snapshot
                // build). Action hooks tie the panel's cycle/toggle
                // buttons back to the same routines the F2/F7/F10
                // keybinds use.
                _debugVm = new AcDream.UI.Abstractions.Panels.Debug.DebugVM(
                    getPlayerPosition:    () => GetDebugPlayerPosition(),
                    getPlayerHeadingDeg:  () => GetDebugPlayerHeadingDeg(),
                    getPlayerCellId:      () => GetDebugPlayerCellId(),
                    getPlayerOnGround:    () => GetDebugPlayerOnGround(),
                    getInPlayerMode:      () => _playerMode,
                    getInFlyMode:         () => _cameraController?.IsFlyMode ?? false,
                    getVerticalVelocity:  () => _playerController?.VerticalVelocity ?? 0f,
                    getEntityCount:       () => _worldState.Entities.Count,
                    getAnimatedCount:     () => _animatedEntities.Count,
                    getLandblocksVisible: () => _lastVisibleLandblocks,
                    getLandblocksTotal:   () => _lastTotalLandblocks,
                    getShadowObjectCount: () => _physicsEngine.ShadowObjects.TotalRegistered,
                    getNearestObjDist:    () => _lastNearestObjDist,
                    getNearestObjLabel:   () => _lastNearestObjLabel,
                    getColliding:         () => _lastColliding,
                    getDebugWireframes:   () => _debugCollisionVisible,
                    getStreamingRadius:   () => _streamingRadius,
                    getMouseSensitivity:  () => GetActiveSensitivity(),
                    getChaseDistance:     () => _chaseCamera?.Distance ?? 0f,
                    getRmbOrbit:          () => _rmbHeld,
                    getHourName:          () => WorldTime.CurrentCalendar.Hour.ToString(),
                    getDayFraction:       () => (float)WorldTime.DayFraction,
                    getWeather:           () => Weather.Kind.ToString(),
                    getActiveLights:      () => Lighting.ActiveCount,
                    getRegisteredLights:  () => Lighting.RegisteredCount,
                    getParticleCount:     () => _particleSystem?.ActiveParticleCount ?? 0,
                    getFps:               () => (float)_lastFps,
                    getFrameMs:           () => (float)_lastFrameMs,
                    combat:               Combat);
                _debugVm.CycleTimeOfDay       = CycleTimeOfDay;
                _debugVm.CycleWeather         = CycleWeather;
                _debugVm.ToggleCollisionWires = ToggleCollisionWires;
                // Phase K.2: free-fly toggle button — same routine the
                // legacy F-key alias hits. Cancels the one-shot
                // auto-entry if the user opts out of player mode before
                // it fires, so the chase camera doesn't snap on top of
                // the fly camera mid-inspection.
                _debugVm.ToggleFlyMode        = ToggleFlyOrChase;
                _debugPanel = new AcDream.UI.Abstractions.Panels.Debug.DebugPanel(_debugVm);
                _panelHost.Register(_debugPanel);

                // Phase K.3 — Settings panel. SettingsVM owns a draft
                // copy of the active KeyBindings. Save replaces the
                // dispatcher's live table + writes JSON; Cancel reverts
                // the draft. Construction is null-safe vs. the
                // dispatcher because the dispatcher is built earlier in
                // the same OnLoad path (see _inputDispatcher field).
                if (_inputDispatcher is not null && _settingsStore is not null)
                {
                    // L.0 — SettingsStore + persisted-settings load + apply
                    // happened earlier in OnLoad via
                    // LoadAndApplyPersistedSettings (settings are runtime
                    // state, not devtools state — they take effect even
                    // when ACDREAM_DEVTOOLS=0). Here we just construct the
                    // Settings PANEL on top of the already-loaded values.
                    var settingsStore = _settingsStore;
                    _settingsVm = new AcDream.UI.Abstractions.Panels.Settings.SettingsVM(
                        persisted: _keyBindings,
                        dispatcher: _inputDispatcher,
                        onSave: bindings =>
                        {
                            _inputDispatcher.SetBindings(bindings);
                            try
                            {
                                bindings.SaveToFile(
                                    AcDream.UI.Abstractions.Input.KeyBindings.DefaultPath());
                                Console.WriteLine(
                                    "keybinds: saved to "
                                    + AcDream.UI.Abstractions.Input.KeyBindings.DefaultPath());
                            }
                            catch (Exception ex)
                            {
                                Console.WriteLine($"keybinds: save failed: {ex.Message}");
                            }
                        },
                        persistedDisplay: _persistedDisplay,
                        onSaveDisplay: display =>
                        {
                            try
                            {
                                settingsStore.SaveDisplay(display);
                                Console.WriteLine(
                                    "settings: display saved to "
                                    + AcDream.UI.Abstractions.Panels.Settings.SettingsStore.DefaultPath());
                                // Apply window-level changes that are too
                                // jarring to live-preview (resolution +
                                // fullscreen). VSync / FOV / ShowFps
                                // already track DisplayDraft via the
                                // per-frame push.
                                ApplyDisplayWindowState(display);
                            }
                            catch (Exception ex)
                            {
                                Console.WriteLine($"settings: display save failed: {ex.Message}");
                            }
                        },
                        persistedAudio: _persistedAudio,
                        onSaveAudio: audio =>
                        {
                            try
                            {
                                settingsStore.SaveAudio(audio);
                                Console.WriteLine(
                                    "settings: audio saved to "
                                    + AcDream.UI.Abstractions.Panels.Settings.SettingsStore.DefaultPath());
                            }
                            catch (Exception ex)
                            {
                                Console.WriteLine($"settings: audio save failed: {ex.Message}");
                            }
                        },
                        persistedGameplay: _persistedGameplay,
                        onSaveGameplay: gameplay =>
                        {
                            try
                            {
                                settingsStore.SaveGameplay(gameplay);
                                Console.WriteLine(
                                    "settings: gameplay saved to "
                                    + AcDream.UI.Abstractions.Panels.Settings.SettingsStore.DefaultPath());
                                // Local-only this phase. Server-sync packet
                                // (CharacterOption bitmask) goes in here when
                                // the protocol round-trip is in place.
                            }
                            catch (Exception ex)
                            {
                                Console.WriteLine($"settings: gameplay save failed: {ex.Message}");
                            }
                        },
                        persistedChat: _persistedChat,
                        onSaveChat: chat =>
                        {
                            try
                            {
                                settingsStore.SaveChat(chat);
                                Console.WriteLine(
                                    "settings: chat saved to "
                                    + AcDream.UI.Abstractions.Panels.Settings.SettingsStore.DefaultPath());
                                // Channel filters affect client-side display
                                // only this phase. ChatPanel will read them
                                // off SettingsVM.ChatDraft when filtering is
                                // wired into the chat-line render path.
                            }
                            catch (Exception ex)
                            {
                                Console.WriteLine($"settings: chat save failed: {ex.Message}");
                            }
                        },
                        persistedCharacter: _persistedCharacter,
                        onSaveCharacter: character =>
                        {
                            try
                            {
                                // _activeToonKey is updated by
                                // BeginLiveSessionAsync after EnterWorld
                                // so saving character settings always
                                // writes under the chosen character's
                                // name (or "default" pre-login).
                                settingsStore.SaveCharacter(_activeToonKey, character);
                                Console.WriteLine(
                                    $"settings: character[{_activeToonKey}] saved to "
                                    + AcDream.UI.Abstractions.Panels.Settings.SettingsStore.DefaultPath());
                            }
                            catch (Exception ex)
                            {
                                Console.WriteLine($"settings: character save failed: {ex.Message}");
                            }
                        });
                    _settingsPanel = new AcDream.UI.Abstractions.Panels.Settings.SettingsPanel(_settingsVm);
                    _panelHost.Register(_settingsPanel);
                }

                Console.WriteLine("devtools: ImGui panel host ready (VitalsPanel + ChatPanel + DebugPanel + SettingsPanel registered)");

                // L.0 Display tab: seed sensible default positions for
                // every registered panel. cond=FirstUseEver means imgui.ini
                // takes precedence on subsequent launches — the user's
                // dragged positions persist. Without this, the first-run
                // experience stacks every panel at (0,0) which looks
                // broken.
                ResetPanelLayout(ImGuiNET.ImGuiCond.FirstUseEver);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"devtools: ImGui init failed: {ex.Message} — devtools disabled");
                _imguiBootstrap?.Dispose();
                _imguiBootstrap = null;
                _panelHost = null;
                _vitalsVm = null;
                _vitalsPanel = null;
                _debugVm = null;
                _debugPanel = null;
                _chatPanel = null;
                _settingsVm = null;
                _settingsPanel = null;
            }
        }

        uint centerLandblockId = 0xA9B4FFFFu;
        Console.WriteLine($"loading world view centered on 0x{centerLandblockId:X8}");

        var region = _dats.Get<DatReaderWriter.DBObjs.Region>(0x13000000u);
        var heightTable = region?.LandDefs.LandHeightTable;
        if (heightTable is null || heightTable.Length < 256)
            throw new InvalidOperationException("Region.LandDefs.LandHeightTable missing or truncated");

        // Phase G.1: parse the full sky descriptor (day groups, keyframes,
        // celestial mesh layers) and swap WorldTime's provider over to the
        // dat-backed keyframes. The stub default provider is only used if
        // the Region lacks HasSkyInfo.
        if (region is not null)
        {
            _loadedSkyDesc = AcDream.Core.World.SkyDescLoader.LoadFromRegion(region);
            if (_loadedSkyDesc is not null)
            {
                // Phase 3d: do NOT assign WorldTime.TickSize from
                // SkyDesc.TickSize. Agent C's decompile (chunk_00500000.c:6241
                // FUN_005062e0) shows SkyDesc.TickSize is the "next sky-tick
                // deadline" period — a throttle — NOT a game-time
                // advancement rate. ACE's server advances PortalYearTicks at
                // 1.0 ticks per real-second (Timers.cs: `PortalYearTicks +=
                // worldTickTimer.Elapsed.TotalSeconds`). Our client
                // extrapolation between TimeSyncs must match: 1.0.
                //
                // Previous behavior: WorldTime.TickSize = 0.8 (from the live
                // SkyDesc.TickSize). Between ~20s TimeSync gaps we fell 4
                // ticks behind the server, producing a visible "acdream sky
                // is behind retail" time-of-day mismatch (user-verified
                // 2026-04-23).
                WorldTime.TickSize = 1.0;

                // Phase 3f: adopt the dat's GameTime.ZeroTimeOfYear as the
                // calendar-extraction offset. Dereth's dat value is 3600
                // (verified 2026-04-23 live dump); ACE's DerethDateTime.cs
                // comment that "tick 0 = Morntide-and-Half" (3333.75
                // offset = +7/16) is WRONG by 266.25 ticks against the
                // authoritative dat. The mismatch cascaded into both the
                // wrong hour label AND the wrong DayOfYear at boundary
                // times (different LCG seed → different DayGroup roll),
                // which explained the user's observation of "acdream
                // clear night, retail stormy pre-dawn" at the same
                // server PortalYearTicks.
                if (region.GameTime is not null)
                {
                    AcDream.Core.World.DerethDateTime.SetOriginOffsetFromDat(
                        region.GameTime.ZeroTimeOfYear);
                    Console.WriteLine(
                        $"sky: GameTime ZeroTimeOfYear={region.GameTime.ZeroTimeOfYear} " +
                        $"(was default {AcDream.Core.World.DerethDateTime.DayFractionOriginOffsetTicks})");
                }

                Console.WriteLine(
                    $"sky: loaded Region 0x13000000 — {_loadedSkyDesc.DayGroups.Count} day groups, " +
                    $"SkyDesc.TickSize={_loadedSkyDesc.TickSize} (throttle, not rate), " +
                    $"LightTickSize={_loadedSkyDesc.LightTickSize}");

                // Initial DayGroup roll using whatever WorldTime currently
                // has (either the hardcoded boot seed or a pre-arrived
                // server sync). RefreshSkyForCurrentDay will re-roll when
                // ServerTimeUpdated delivers the real ConnectRequest tick.
                RefreshSkyForCurrentDay();
            }
        }

        // Seed WorldTime to noon so outdoor scenes aren't pitch-black before
        // the server sends its first TimeSync packet (offline rendering in
        // particular never receives one).
        //
        // "Noon" here means sun at zenith — dayFraction = 0.5. Because
        // DerethDateTime applies a +7/16 offset (tick 0 = Morntide-and-Half,
        // hour 8 of 16), we need raw ticks = 476.25 (one hour past tick 0 =
        // Midsong / Hour 9, which is what retail considers noon).
        //
        // Using `DayTicks * 0.5 = 3810` WOULD be correct if the offset were
        // zero, but with our 3333.75-tick shift it lands on dayFraction
        // 0.9375 — that's Gloaming-and-Half (sunset, nearly midnight),
        // producing a dim orange sky with the sun below the horizon until
        // TimeSync arrives.
        WorldTime.SyncFromServer(AcDream.Core.World.DerethDateTime.DayTicks / 16.0); // = 476.25 = Midsong (noon)

        // Build the terrain atlas once from the Region dat.
        var terrainAtlas = AcDream.App.Rendering.TerrainAtlas.Build(_gl, _dats);

        _terrain = new TerrainChunkRenderer(_gl, _shader, terrainAtlas);

        int centerX = (int)((centerLandblockId >> 24) & 0xFFu);
        int centerY = (int)((centerLandblockId >> 16) & 0xFFu);

        // Build blending context from the terrain atlas. Stored as fields so
        // ApplyLoadedTerrain (render-thread callback invoked per streamed lb)
        // can call LandblockMesh.Build without re-deriving these every time.
        var terrainTypeToLayerBytes = new Dictionary<uint, byte>(terrainAtlas.TerrainTypeToLayer.Count);
        foreach (var kvp in terrainAtlas.TerrainTypeToLayer)
            terrainTypeToLayerBytes[kvp.Key] = (byte)kvp.Value;

        const uint RoadTypeEnumValue = 0x20;  // TerrainTextureType.RoadType
        byte roadLayer = terrainTypeToLayerBytes.TryGetValue(RoadTypeEnumValue, out var rl)
            ? rl
            : AcDream.Core.Terrain.SurfaceInfo.None;

        _blendCtx = new AcDream.Core.Terrain.TerrainBlendingContext(
            TerrainTypeToLayer: terrainTypeToLayerBytes,
            RoadLayer: roadLayer,
            CornerAlphaLayers: terrainAtlas.CornerAlphaLayers,
            SideAlphaLayers:   terrainAtlas.SideAlphaLayers,
            RoadAlphaLayers:   terrainAtlas.RoadAlphaLayers,
            CornerAlphaTCodes: terrainAtlas.CornerAlphaTCodes,
            SideAlphaTCodes:   terrainAtlas.SideAlphaTCodes,
            RoadAlphaRCodes:   terrainAtlas.RoadAlphaRCodes);

        _heightTable = heightTable;
        _surfaceCache = new Dictionary<uint, AcDream.Core.Terrain.SurfaceInfo>();

        _textureCache = new TextureCache(_gl, _dats);
        _staticMesh = new InstancedMeshRenderer(_gl, _meshShader, _textureCache);

        // Phase G.1 sky renderer — its own shader (sky.vert / sky.frag)
        // with depth writes off + far plane 1e6 so celestial meshes
        // never clip. Shares the TextureCache with the static pipeline.
        var skyShader = new Shader(_gl,
            Path.Combine(shadersDir, "sky.vert"),
            Path.Combine(shadersDir, "sky.frag"));
        _skyRenderer = new AcDream.App.Rendering.Sky.SkyRenderer(
            _gl, _dats, skyShader, _textureCache);

        // Phase G.1 particle renderer — renders rain / snow / spell auras
        // spawned into the shared ParticleSystem as billboard quads.
        // Weather uses AttachLocal emitters so the rain volume follows
        // the player.
        _particleRenderer = new ParticleRenderer(_gl, shadersDir);

        // Phase A.1: replace the one-shot 3×3 preload with a streaming controller.
        // Parse runtime radius from environment (default 2 → 5×5 window).
        // Values outside [0, 8] fall back to the field default of 2.
        var radiusEnv = Environment.GetEnvironmentVariable("ACDREAM_STREAM_RADIUS");
        if (int.TryParse(radiusEnv, out var r) && r >= 0 && r <= 8)
            _streamingRadius = r;
        Console.WriteLine($"streaming: radius={_streamingRadius} (window={2*_streamingRadius+1}×{2*_streamingRadius+1})");

        // The streamer's load delegate wraps LandblockLoader.Load + stab
        // hydration. Scenery + interior will land in Task 8.
        _streamer = new AcDream.App.Streaming.LandblockStreamer(
            loadLandblock: id => BuildLandblockForStreaming(id));
        _streamer.Start();

        _streamingController = new AcDream.App.Streaming.StreamingController(
            enqueueLoad:      _streamer.EnqueueLoad,
            enqueueUnload:    _streamer.EnqueueUnload,
            drainCompletions: _streamer.DrainCompletions,
            applyTerrain:     ApplyLoadedTerrain,
            state:            _worldState,
            radius:           _streamingRadius,
            removeTerrain:    id =>
            {
                // Phase G.2: release any LightSources attached to entities
                // in this landblock before their records disappear from
                // _worldState — otherwise the LightManager accumulates
                // stale entries for every walk across a landblock boundary.
                if (_lightingSink is not null &&
                    _worldState.TryGetLandblock(id, out var lb))
                {
                    foreach (var ent in lb!.Entities)
                        _lightingSink.UnregisterOwner(ent.Id);
                }
                _terrain?.RemoveLandblock(id);
                _physicsEngine.RemoveLandblock(id);
                _cellVisibility.RemoveLandblock((id >> 16) & 0xFFFFu);
            });

        // Phase 4.7: optional live-mode startup. Connect to the ACE server,
        // enter the world as the first character on the account, and stream
        // CreateObject messages into _worldGameState as they arrive. Entirely
        // gated behind ACDREAM_LIVE=1 so the default run path is unchanged.
        _liveCenterX = centerX;
        _liveCenterY = centerY;
        TryStartLiveSession();
    }

    private void TryStartLiveSession()
    {
        if (Environment.GetEnvironmentVariable("ACDREAM_LIVE") != "1") return;

        var host = Environment.GetEnvironmentVariable("ACDREAM_TEST_HOST") ?? "127.0.0.1";
        var portStr = Environment.GetEnvironmentVariable("ACDREAM_TEST_PORT") ?? "9000";
        var user = Environment.GetEnvironmentVariable("ACDREAM_TEST_USER");
        var pass = Environment.GetEnvironmentVariable("ACDREAM_TEST_PASS");
        if (string.IsNullOrEmpty(user) || string.IsNullOrEmpty(pass))
        {
            Console.WriteLine("live: ACDREAM_LIVE set but TEST_USER/TEST_PASS missing; skipping");
            return;
        }

        try
        {
            // Resolve DNS names (e.g. play.coldeve.ac) as well as literal
            // IP addresses. `IPAddress.Parse` throws on hostnames; fall
            // back to `Dns.GetHostAddresses` and prefer IPv4 (ACE + retail
            // use IPv4 UDP exclusively).
            System.Net.IPAddress ip;
            if (!System.Net.IPAddress.TryParse(host, out ip!))
            {
                var addrs = System.Net.Dns.GetHostAddresses(host);
                ip = System.Array.Find(addrs,
                        a => a.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork)
                    ?? (addrs.Length > 0 ? addrs[0] : throw new System.Exception(
                        $"DNS resolved no addresses for '{host}'"));
                Console.WriteLine($"live: resolved {host} → {ip}");
            }
            var endpoint = new System.Net.IPEndPoint(ip, int.Parse(portStr));
            Console.WriteLine($"live: connecting to {endpoint} as {user}");
            _liveSession = new AcDream.Core.Net.WorldSession(endpoint);
            _liveSession.EntitySpawned += OnLiveEntitySpawned;
            _liveSession.MotionUpdated += OnLiveMotionUpdated;
            _liveSession.PositionUpdated += OnLivePositionUpdated;
            _liveSession.VectorUpdated += OnLiveVectorUpdated;
            _liveSession.TeleportStarted += OnTeleportStarted;

            // Phase 6c — PlayScript (0xF754) arrives from the server as
            // a (guid, scriptId) pair. Resolve the guid's current world
            // position and feed the PhysicsScript runner; it schedules
            // the script's hooks (particle spawns, sound cues, light
            // toggles) at their StartTime offsets. This is the channel
            // retail uses for spell casts, combat flinches, emote
            // gestures, AND — per Agent #5 research — lightning
            // flashes during stormy weather.
            _liveSession.PlayScriptReceived += OnPlayScriptReceived;

            // Phase 5d — AdminEnvirons (0xEA60): fog presets + sound
            // cues. Fog types (0x00..0x06) set WeatherSystem.Override;
            // sound types (0x65..0x7B) play a one-shot audio cue.
            // Lightning flashes arrive as a PAIRED PlayScript (the
            // visual) + AdminEnvirons ThunderXSound (the audio) — both
            // are handled here and in OnPlayScriptReceived respectively.
            _liveSession.EnvironChanged += OnEnvironChanged;

            // Phase G.1: keep the client's day/night clock in sync with
            // server time. Fires once from ConnectRequest (initial seed)
            // and repeatedly on TimeSync-flagged packets.
            // Phase 3a: also re-roll the active DayGroup if the Dereth-day
            // index changed — retail rolls one weather preset per server
            // day (r12 §11), deterministic from the day index so retail
            // and acdream converge without a wire message.
            _liveSession.ServerTimeUpdated += ticks =>
            {
                WorldTime.SyncFromServer(ticks);
                RefreshSkyForCurrentDay();
            };

            // Phase F.1-H.1: wire every parsed GameEvent into the right
            // Core state class (chat, combat, spellbook, items). After
            // this one call, server-sent ChannelBroadcast / damage
            // notifications / spell learns / wield events all update
            // the corresponding client-side state without further glue.
            // K-fix13 (2026-04-26): cache portal.dat's SkillTable so the
            // skill-formula resolver can apply the AttributeFormula
            // contribution. Without this, our wire-derived "skill"
            // value was missing the dominant attribute-derived term
            // and jumps undershot retail by ~30 % at typical
            // attribute levels.
            var skillTable = _dats?.Get<DatReaderWriter.DBObjs.SkillTable>(0x0E000004u);

            AcDream.Core.Net.GameEventWiring.WireAll(
                _liveSession.GameEvents, Items, Combat, SpellBook, Chat, LocalPlayer,
                TurbineChat,
                resolveSkillFormulaBonus: (skillId, attrCurrents) =>
                {
                    // ACE GetFormula (AttributeFormula.cs:55-): when
                    // formula.X (Attribute1Multiplier) is 0, the formula
                    // is "no attribute contribution" and the function
                    // returns 0. Otherwise:
                    //   bonus = (attr1 * Mult1 + attr2 * Mult2) / Divisor + Additive
                    if (skillTable?.Skills is null) return 0u;
                    if (!skillTable.Skills.TryGetValue(
                            (DatReaderWriter.Enums.SkillId)skillId, out var skillBase))
                        return 0u;
                    var f = skillBase.Formula;
                    if (f.Attribute1Multiplier == 0 || f.Divisor == 0) return 0u;
                    attrCurrents.TryGetValue((uint)f.Attribute1, out uint a1);
                    attrCurrents.TryGetValue((uint)f.Attribute2, out uint a2);
                    long num = (long)a1 * f.Attribute1Multiplier
                             + (long)a2 * f.Attribute2Multiplier;
                    long bonus = num / f.Divisor + f.AdditiveBonus;
                    return bonus < 0 ? 0u : (uint)bonus;
                },
                onSkillsUpdated: (runSkill, jumpSkill) =>
                {
                    // K-fix7 (2026-04-26): cache the latest server-sent
                    // Run / Jump skill values so the next
                    // EnterPlayerModeNow can hand them to the new
                    // PlayerMovementController. Push immediately too,
                    // so a PD that arrives WHILE player mode is active
                    // (re-equip / log-in mid-session) updates the live
                    // controller. -1 from the wiring means "skill not
                    // present in this PD" — keep the previous cached
                    // value rather than overwriting with -1.
                    if (runSkill  >= 0) _lastSeenRunSkill  = runSkill;
                    if (jumpSkill >= 0) _lastSeenJumpSkill = jumpSkill;
                    if (_playerController is not null
                        && _lastSeenRunSkill >= 0 && _lastSeenJumpSkill >= 0)
                    {
                        _playerController.SetCharacterSkills(
                            _lastSeenRunSkill, _lastSeenJumpSkill);
                        Console.WriteLine($"player: applied server skills run={_lastSeenRunSkill} jump={_lastSeenJumpSkill}");
                    }
                });

            // Phase I.7: subscribe to CombatState events and emit
            // retail-faithful "You hit X for Y damage" chat lines into
            // the unified ChatLog. The translator owns the wording
            // (templates ported from holtburger chat.rs:221-308); the
            // panel renders combat entries via TextColored.
            _combatChatTranslator = new AcDream.Core.Chat.CombatChatTranslator(Combat, Chat);

            // Phase H.1: feed inbound HearSpeech into the chat log.
            _liveSession.SpeechHeard += speech =>
                Chat.OnLocalSpeech(
                    sender: speech.SenderName,
                    text: speech.Text,
                    senderGuid: speech.SenderGuid,
                    isRanged: speech.IsRanged);

            // Phase I.6: feed inbound TurbineChat events into the chat log.
            // The Response variant is fire-and-forget (server-side ack);
            // EventSendToRoom is a real chat message broadcast to a room.
            // Phase J: ACE's GameMessageSystemChat (used for the login
            // banner "Welcome to Asheron's Call ... type @acehelp" and
            // for SystemChat broadcasts) rides opcode 0xF7E0 ServerMessage,
            // parsed in I.5 but never wired. Surface it as a System
            // chat line so the welcome banner appears + future server
            // pushes (announcements, command responses) show.
            _liveSession.ServerMessageReceived += sm =>
                Chat.OnSystemMessage(sm.Message, sm.ChatType);

            // Phase I.5 + J: emotes already had ChatLog adapters; wire
            // their session events here so they actually reach chat.
            _liveSession.EmoteHeard += emote =>
                Chat.OnEmote(emote.SenderName, emote.Text, emote.SenderGuid);
            _liveSession.SoulEmoteHeard += emote =>
                Chat.OnSoulEmote(emote.SenderName, emote.Text, emote.SenderGuid);
            _liveSession.PlayerKilledReceived += pk =>
                Chat.OnPlayerKilled(pk.DeathMessage, pk.VictimGuid, pk.KillerGuid);

            _liveSession.TurbineChatReceived += parsed =>
            {
                if (parsed.Body is AcDream.Core.Net.Messages.TurbineChat.Payload.EventSendToRoom ev)
                {
                    // Pass the friendly channel name out-of-band via
                    // ChatLog.OnChannelBroadcast's channelName param so
                    // ChatVM.FormatEntry can render the retail-style
                    // "[Trade] +Acdream says, \"hello\"" without us
                    // mangling the payload text.
                    string label = TurbineRoomDisplayName(ev.RoomId, ev.ChatType);
                    Chat.OnChannelBroadcast(
                        channelId:   ev.RoomId,
                        sender:      ev.SenderName,
                        text:        ev.Message,
                        channelName: label);
                }
                // Response (server ack of an outbound RequestSendToRoomById)
                // and Unknown payloads are intentionally not surfaced —
                // the inbound EventSendToRoom for our own message acts as
                // the canonical echo.
            };

            // Phase I.3: real ICommandBus. Panels publish SendChatCmd here
            // and we route it to the right wire opcode (Talk / Tell / ChatChannel)
            // plus a local echo into ChatLog so the player sees their own
            // message immediately. Closes over _liveSession + Chat so this
            // wiring only exists for the lifetime of the live session.
            var liveSession = _liveSession;
            var chat = Chat;
            _commandBus = new AcDream.UI.Abstractions.LiveCommandBus();
            var turbineChat = TurbineChat;
            uint playerGuid = _playerServerGuid;
            _commandBus.Register<AcDream.UI.Abstractions.SendChatCmd>(cmd =>
            {
                if (string.IsNullOrEmpty(cmd.Text)) return;
                switch (cmd.Channel)
                {
                    case AcDream.UI.Abstractions.ChatChannelKind.Say:
                        // Phase J: drop optimistic /say echo. ACE's
                        // HandleActionTalk broadcasts a HearSpeech back
                        // to the sender too, and ChatLog.OnLocalSpeech
                        // detects own-guid match to render it as
                        // "You say, ...". Optimistic-echoing here
                        // doubled the line. ALSO: don't echo "@xxx"
                        // server-side admin commands — ACE consumes
                        // them silently and replies via SystemChat.
                        liveSession.SendTalk(cmd.Text);
                        break;
                    case AcDream.UI.Abstractions.ChatChannelKind.Tell:
                        if (string.IsNullOrEmpty(cmd.TargetName)) return;
                        liveSession.SendTell(cmd.TargetName, cmd.Text);
                        chat.OnSelfSent(
                            AcDream.Core.Chat.ChatKind.Tell, cmd.Text,
                            targetOrChannel: cmd.TargetName);
                        break;
                    default:
                        // Phase I.6: try TurbineChat first for the global
                        // community channels (General/Trade/LFG/Roleplay/
                        // Society/Olthoi) — they ride 0xF7DE TurbineChat.
                        // Allegiance is double-routed: try TurbineChat first
                        // (when the player has a Turbine allegiance room) and
                        // fall back to the legacy 0x0147 ChatChannel.
                        //
                        // We do NOT optimistic-echo channels: ACE's
                        // TurbineChatHandler broadcasts EventSendToRoom back
                        // to the sender too, so we always get the canonical
                        // echo from the server. Optimistic-echoing here
                        // double-prints the message (one as "[Trade] hello"
                        // from us, one as "[Trade] +Acdream says, \"hello\""
                        // from the server). Trust the server.
                        var turbine = ResolveTurbineForKind(cmd.Channel, turbineChat);
                        if (turbine is not null)
                        {
                            uint cookie = turbineChat.NextContextId();
                            // Use the live player guid if it's been captured;
                            // otherwise 0 (server treats unknown sender_id
                            // gracefully — the cookie is what we care about).
                            uint senderGuid = _playerServerGuid != 0u
                                ? _playerServerGuid
                                : playerGuid;
                            Console.WriteLine(
                                $"chat: outbound TurbineChat {turbine.Value.DisplayName} " +
                                $"room=0x{turbine.Value.RoomId:X8} chatType={turbine.Value.ChatType} " +
                                $"cookie=0x{cookie:X} sender=0x{senderGuid:X8} len={cmd.Text.Length}");
                            liveSession.SendTurbineChatTo(
                                roomId:       turbine.Value.RoomId,
                                chatType:     turbine.Value.ChatType,
                                dispatchType: (uint)AcDream.Core.Net.Messages.TurbineChat.DispatchType.SendToRoomById,
                                senderGuid:   senderGuid,
                                text:         cmd.Text,
                                cookie:       cookie);
                            // No optimistic echo: server EventSendToRoom
                            // broadcast comes back with sender="+Acdream"
                            // and is rendered by ChatVM as
                            // "[Trade] +Acdream says, \"hello\"".
                            break;
                        }

                        var resolved = AcDream.UI.Abstractions.ChannelResolver.Resolve(cmd.Channel);
                        if (resolved is null)
                        {
                            // Diagnostic: the user picked a channel kind that
                            // (a) isn't a Turbine channel TurbineChatState
                            // knows about and (b) has no legacy ChatChannel
                            // mapping. Most common cause: TurbineChat hasn't
                            // been enabled yet (server didn't send 0x0295)
                            // and the kind is General/Trade/LFG/etc.
                            Console.WriteLine(
                                $"chat: SendChatCmd kind={cmd.Channel} dropped " +
                                $"(turbine.Enabled={turbineChat.Enabled} no legacy id)");
                            return;
                        }
                        Console.WriteLine(
                            $"chat: outbound legacy ChatChannel {resolved.Value.DisplayName} " +
                            $"id=0x{resolved.Value.ChannelId:X8} len={cmd.Text.Length}");
                        liveSession.SendChannel(resolved.Value.ChannelId, cmd.Text);
                        // Legacy channels (Fellowship / Allegiance / Patron /
                        // Monarch / Vassals / CoVassals) — keep the optimistic
                        // echo because legacy ChatChannel does NOT always
                        // broadcast back to the sender. ChannelName is the
                        // friendly display name so ChatVM renders it as
                        // "[Fellowship] +Acdream says, \"hello\"".
                        chat.OnSelfSent(
                            AcDream.Core.Chat.ChatKind.Channel, cmd.Text,
                            targetOrChannel: resolved.Value.DisplayName);
                        break;
                }
            });

            // Issue #5: feed PrivateUpdateVital + PrivateUpdateVitalCurrent
            // into LocalPlayer so VitalsPanel can draw Stam / Mana bars.
            _liveSession.VitalUpdated += v =>
                LocalPlayer.OnVitalUpdate(v.VitalId, v.Ranks, v.Start, v.Xp, v.Current);
            _liveSession.VitalCurrentUpdated += v =>
                LocalPlayer.OnVitalCurrent(v.VitalId, v.Current);

            Chat.OnSystemMessage($"connecting to {host}:{portStr} as {user}", chatType: 1);
            _liveSession.Connect(user, pass);
            Chat.OnSystemMessage("connected — character list received", chatType: 1);

            if (_liveSession.Characters is null || _liveSession.Characters.Characters.Count == 0)
            {
                Console.WriteLine("live: no characters on account; disconnecting");
                _liveSession.Dispose();
                _liveSession = null;
                return;
            }

            var chosen = _liveSession.Characters.Characters[0];
            _playerServerGuid = chosen.Id;  // Phase B.2: store for Tab-key player-mode entry
            _vitalsVm?.SetLocalPlayerGuid(chosen.Id);  // Phase D.2a — devtools HP bar tracks this guid
            Chat.SetLocalPlayerGuid(chosen.Id);  // Phase J — recognize own /say echo from ACE's HearSpeech broadcast
            _worldState.MarkPersistent(chosen.Id);  // player entity survives landblock unloads
            Console.WriteLine($"live: entering world as 0x{chosen.Id:X8} {chosen.Name}");
            _liveSession.EnterWorld(user, characterIndex: 0);

            // L.0 Character tab: swap the SettingsVM's character bag
            // from the "default" pre-login bag to the actual chosen
            // toon's bag. Every Save from now on writes under the
            // chosen toon's name. LoadCharacterContext rebinds BOTH
            // persisted + draft so HasUnsavedChanges doesn't flag the
            // swap as a pending edit.
            _activeToonKey = chosen.Name;
            if (_settingsStore is not null && _settingsVm is not null)
            {
                var toonBag = _settingsStore.LoadCharacter(_activeToonKey);
                _settingsVm.LoadCharacterContext(toonBag);
                Console.WriteLine($"settings: loaded character[{_activeToonKey}] preferences");
            }
            // Phase K.2: arm auto-entry. The guard's predicates won't
            // pass yet — the entity stream hasn't started — but the
            // OnUpdate tick re-checks every frame and fires once
            // everything converges (typically 100-300 ms after EnterWorld
            // returns). User can pre-empt via DebugPanel "Toggle
            // Free-Fly Mode" or Tab; both call Cancel() first.
            _playerModeAutoEntry?.Arm();
            Console.WriteLine($"live: in world — CreateObject stream active " +
                              $"(so far: {_liveSpawnReceived} received, {_liveSpawnHydrated} hydrated)");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"live: session failed: {ex.Message}");
            _combatChatTranslator?.Dispose();
            _combatChatTranslator = null;
            _liveSession?.Dispose();
            _liveSession = null;
        }
    }

    /// <summary>
    /// Convert a Phase 4.7 CreateObject spawn into a WorldEntity with hydrated
    /// mesh refs and register it in IGameState. Called from WorldSession events
    /// on the main thread (Tick runs in the Silk.NET Update callback).
    /// </summary>
    private void OnLiveEntitySpawned(AcDream.Core.Net.WorldSession.EntitySpawn spawn)
    {
        // Phase A.1 hotfix: live CreateObject handler reads dats extensively
        // (Setup, GfxObj, Surface, SurfaceTexture) to hydrate the spawned
        // entity. All of it must run under the dat lock so it doesn't race
        // with BuildLandblockForStreaming on the worker thread.
        lock (_datLock)
        {
            OnLiveEntitySpawnedLocked(spawn);
        }
    }

    private void OnLiveEntitySpawnedLocked(AcDream.Core.Net.WorldSession.EntitySpawn spawn)
    {
        _liveSpawnReceived++;

        // De-dup: the server re-sends CreateObject for the same guid in
        // several situations (visibility refresh, landblock crossing,
        // appearance update). Without cleanup the OLD copy remains in
        // GpuWorldState + WorldGameState + _animatedEntities, so the
        // renderer draws both copies overlapped — producing the
        // "NPC clothing changes when I turn the camera" bug because the
        // depth test arbitrates between overlapping duplicates each frame.
        //
        // For a respawn, drop the previous rendering state here before we
        // build the new one. `_entitiesByServerGuid` is the canonical map,
        // its value is the live WorldEntity we need to dispose.
        if (_entitiesByServerGuid.TryGetValue(spawn.Guid, out var existingEntity))
        {
            _worldState.RemoveEntityByServerGuid(spawn.Guid);
            _worldGameState.RemoveById(existingEntity.Id);
            _animatedEntities.Remove(existingEntity.Id);
            // Physics collision registry entry is keyed by local id too.
            _physicsEngine.ShadowObjects.Deregister(existingEntity.Id);
            // Dead-reckon state is keyed by SERVER guid (not local id) so we
            // clear using the same guid the new spawn will use. Leaving old
            // SnapResidual / DeadReckonedPos in would make the next first
            // UpdatePosition look like a 2m-residual soft-snap.
            _remoteDeadReckon.Remove(spawn.Guid);
            _remoteLastMove.Remove(spawn.Guid);
        }

        // Log every spawn that arrives so we can inventory what the server
        // sends (including the ones we can't render yet). The Name field
        // is the critical one — we can grep the log for "Nullified Statue
        // of a Drudge" or similar to find a specific weenie by its
        // in-game name.
        string posStr = spawn.Position is { } sp
            ? $"({sp.PositionX:F1},{sp.PositionY:F1},{sp.PositionZ:F1})@0x{sp.LandblockId:X8}"
            : "no-pos";
        string setupStr = spawn.SetupTableId is { } su ? $"0x{su:X8}" : "no-setup";
        string nameStr = spawn.Name is { Length: > 0 } n ? $"\"{n}\"" : "no-name";
        int animPartCount = spawn.AnimPartChanges?.Count ?? 0;
        int texChangeCount = spawn.TextureChanges?.Count ?? 0;
        int subPalCount = spawn.SubPalettes?.Count ?? 0;
        Console.WriteLine(
            $"live: spawn guid=0x{spawn.Guid:X8} name={nameStr} setup={setupStr} pos={posStr} " +
            $"animParts={animPartCount} texChanges={texChangeCount} subPalettes={subPalCount}");

        // Target the statue specifically for full diagnostic dump: Name match
        // is cheap and gives us exactly one entity's worth of log regardless
        // of arrival order.
        bool isStatue = spawn.Name is not null && spawn.Name.Contains("Statue", StringComparison.OrdinalIgnoreCase);
        if (isStatue)
        {
            Console.WriteLine($"live:   [STATUE] objScale={spawn.ObjScale?.ToString("F3") ?? "null"}");
            Console.WriteLine($"live:   [STATUE] mtable=0x{(spawn.MotionTableId ?? 0):X8} stance=0x{(spawn.MotionState?.Stance ?? 0):X4} cmd=0x{(spawn.MotionState?.ForwardCommand ?? 0):X4}");
            if (spawn.TextureChanges is { } tcs)
            {
                foreach (var tc in tcs)
                    Console.WriteLine($"live:   [STATUE] texChange part={tc.PartIndex} old=0x{tc.OldTexture:X8} new=0x{tc.NewTexture:X8}");
            }
            if (spawn.SubPalettes is { } sps)
            {
                Console.WriteLine($"live:   [STATUE] basePalette=0x{(spawn.BasePaletteId ?? 0):X8}");
                foreach (var subPal in sps)
                    Console.WriteLine($"live:   [STATUE] subPalette id=0x{subPal.SubPaletteId:X8} offset={subPal.Offset} length={subPal.Length}");
            }
            if (spawn.AnimPartChanges is { } apcs)
            {
                foreach (var apc in apcs)
                    Console.WriteLine($"live:   [STATUE] animPart index={apc.PartIndex} newModel=0x{apc.NewModelId:X8}");
            }

            // Dump the BASE setup's part list before AnimPartChanges, so we can
            // see how many parts the statue's Setup actually has + what their
            // default GfxObjs are. The retail statue may have additional parts
            // (e.g. a pedestal sub-mesh) that our setup loader is dropping or
            // we're rendering with wrong default GfxObjs.
            if (spawn.SetupTableId is { } sid && _dats is not null)
            {
                var baseSetup = _dats.Get<DatReaderWriter.DBObjs.Setup>(sid);
                if (baseSetup is not null)
                {
                    Console.WriteLine($"live:   [STATUE] base Setup 0x{sid:X8} has {baseSetup.Parts.Count} parts:");
                    for (int pi = 0; pi < baseSetup.Parts.Count; pi++)
                    {
                        uint partGfxId = (uint)baseSetup.Parts[pi];
                        var pgfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(partGfxId);
                        int subCount = pgfx?.Surfaces.Count ?? -1;
                        Console.WriteLine($"live:   [STATUE]   part[{pi}] gfxObj=0x{partGfxId:X8} surfaces={subCount}");
                    }
                    Console.WriteLine($"live:   [STATUE]   placementFrames count={baseSetup.PlacementFrames.Count}");
                }
            }
        }

        if (_dats is null || _staticMesh is null) return;
        if (spawn.Position is null || spawn.SetupTableId is null)
        {
            // Can't place a mesh without both. Most of these are inventory
            // items anyway (no position because they're held), which have no
            // visible world presence.
            if (spawn.Position is null) _liveDropReasonNoPos++;
            else _liveDropReasonNoSetup++;
            return;
        }

        var p = spawn.Position.Value;

        // Translate server position into acdream world space. The server sends
        // (landblockId, local x/y/z). acdream's world origin is the center
        // landblock; each neighbor landblock is offset by 192 units per step.
        int lbX = (int)((p.LandblockId >> 24) & 0xFFu);
        int lbY = (int)((p.LandblockId >> 16) & 0xFFu);
        var origin = new System.Numerics.Vector3(
            (lbX - _liveCenterX) * 192f,
            (lbY - _liveCenterY) * 192f,
            0f);
        var worldPos = new System.Numerics.Vector3(p.PositionX, p.PositionY, p.PositionZ) + origin;

        // AC quaternion wire order is (W, X, Y, Z); System.Numerics.Quaternion is (X, Y, Z, W).
        var rot = new System.Numerics.Quaternion(p.RotationX, p.RotationY, p.RotationZ, p.RotationW);

        // Hydrate mesh refs from the Setup dat. This is the same code path
        // used by the static scenery pipeline (see the Setup hydration above).
        var setup = _dats.Get<DatReaderWriter.DBObjs.Setup>(spawn.SetupTableId.Value);
        if (setup is not null)
            _physicsDataCache.CacheSetup(spawn.SetupTableId.Value, setup);
        if (setup is null)
        {
            _liveDropReasonSetupDatMissing++;
            Console.WriteLine($"live: DROP setup dat 0x{spawn.SetupTableId.Value:X8} missing " +
                              $"(guid=0x{spawn.Guid:X8})");
            return;
        }

        // Phase 6: resolve the entity's idle motion frame from its
        // MotionTable chain. For creatures and characters this gives us
        // the upright "Resting" pose instead of the Setup's Default
        // (T-pose / aggressive crouch). Static items with no motion table
        // get null and fall back to PlacementFrames in Flatten.
        // Honor the server's CurrentMotionState (CreateObject MovementData)
        // when present. The Foundry's drudge statue is the canonical case:
        // its MotionTable's default style is upright "Ready" but the weenie
        // is sent with a combat stance + Crouch ForwardCommand override, so
        // resolving the cycle key from those gives the aggressive crouch.
        ushort? stanceOverride = spawn.MotionState?.Stance;
        ushort? commandOverride = spawn.MotionState?.ForwardCommand;
        // Critical for entities like the Foundry's drudge statue: their
        // base Setup has DefaultMotionTable=0, but the server tells us
        // which motion table to use via PhysicsDescriptionFlag.MTable.
        // Without this override the resolver returns null and we fall
        // back to PlacementFrames[Default] which renders the wrong pose.
        // Phase 6.4: prefer the full cycle so we can play it forward over
        // time. Falls back to GetIdleFrame's static-frame behavior when
        // the cycle resolves but only the first frame is rendered (no
        // animated entry registered) — this happens for entities the
        // resolver short-circuits on.
        var idleCycle = AcDream.Core.Meshing.MotionResolver.GetIdleCycle(
            setup, _dats,
            motionTableIdOverride: spawn.MotionTableId,
            stanceOverride: stanceOverride,
            commandOverride: commandOverride);
        DatReaderWriter.Types.AnimationFrame? idleFrame = null;
        if (idleCycle is not null)
        {
            int startIdx = idleCycle.LowFrame;
            if (startIdx < 0 || startIdx >= idleCycle.Animation.PartFrames.Count) startIdx = 0;
            idleFrame = idleCycle.Animation.PartFrames[startIdx];
        }
        var flat = AcDream.Core.Meshing.SetupMesh.Flatten(setup, idleFrame);

        // Apply the server's AnimPartChanges: "replace part at index N
        // with GfxObj M". This is how characters become clothed (head →
        // helmet, torso → chestplate, ...) and how server-weenie statues
        // and props pick up their unique visual meshes on top of a generic
        // base Setup. Start with a mutable copy, patch in the replacements,
        // then proceed with the normal upload loop.
        var parts = new List<AcDream.Core.World.MeshRef>(flat);
        var animPartChanges = spawn.AnimPartChanges ?? Array.Empty<AcDream.Core.Net.Messages.CreateObject.AnimPartChange>();
        foreach (var change in animPartChanges)
        {
            if (change.PartIndex < parts.Count)
            {
                parts[change.PartIndex] = new AcDream.Core.World.MeshRef(
                    change.NewModelId, parts[change.PartIndex].PartTransform);
            }
        }

        // Build per-part texture overrides. The server sends TextureChanges as
        // (partIdx, oldSurfaceTextureId, newSurfaceTextureId) where both ids
        // are in the SurfaceTexture (0x05) range. Our sub-meshes are keyed
        // by Surface (0x08) ids whose `OrigTextureId` field points to a
        // SurfaceTexture. So we have to resolve each Surface → OrigTextureId,
        // match that against the part's oldSurfaceTextureId set, and build
        // a new dict keyed by Surface id → replacement OrigTextureId. The
        // renderer then calls TextureCache.GetOrUploadWithOrigTextureOverride
        // to get a texture decoded with the replacement SurfaceTexture
        // substituted inside the Surface's decode chain.
        var textureChanges = spawn.TextureChanges ?? Array.Empty<AcDream.Core.Net.Messages.CreateObject.TextureChange>();
        Dictionary<int, Dictionary<uint, uint>>? resolvedOverridesByPart = null;
        if (textureChanges.Count > 0)
        {
            // First pass: group (oldOrigTex → newOrigTex) per part.
            var perPartOldToNew = new Dictionary<int, Dictionary<uint, uint>>();
            foreach (var tc in textureChanges)
            {
                if (!perPartOldToNew.TryGetValue(tc.PartIndex, out var dict))
                {
                    dict = new Dictionary<uint, uint>();
                    perPartOldToNew[tc.PartIndex] = dict;
                }
                // Last write wins — matches observed duplicate semantics.
                dict[tc.OldTexture] = tc.NewTexture;
            }

            // Second pass: resolve each affected part's Surface chain and
            // build the Surface-id-keyed override map the renderer consumes.
            bool isStatueDiag = spawn.Name is not null && spawn.Name.Contains("Statue", StringComparison.OrdinalIgnoreCase);
            resolvedOverridesByPart = new Dictionary<int, Dictionary<uint, uint>>();
            for (int pi = 0; pi < parts.Count; pi++)
            {
                if (!perPartOldToNew.TryGetValue(pi, out var oldToNew)) continue;
                var partGfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(parts[pi].GfxObjId);
                if (partGfx is null)
                {
                    if (isStatueDiag)
                        Console.WriteLine($"live:   [STATUE] resolve part={pi} GfxObj 0x{parts[pi].GfxObjId:X8} missing");
                    continue;
                }
                _physicsDataCache.CacheGfxObj(parts[pi].GfxObjId, partGfx);

                if (isStatueDiag)
                    Console.WriteLine($"live:   [STATUE] resolve part={pi} gfx=0x{parts[pi].GfxObjId:X8} surfaces={partGfx.Surfaces.Count}");

                Dictionary<uint, uint>? resolved = null;
                foreach (var surfQid in partGfx.Surfaces)
                {
                    uint surfId = (uint)surfQid;
                    var surfDat = _dats.Get<DatReaderWriter.DBObjs.Surface>(surfId);
                    if (surfDat is null) continue;
                    uint origTexId = (uint)surfDat.OrigTextureId;
                    bool hit = origTexId != 0 && oldToNew.TryGetValue(origTexId, out uint newOrigTex) && (newOrigTex != 0 || true);
                    if (isStatueDiag)
                        Console.WriteLine($"live:   [STATUE]   surface=0x{surfId:X8} origTex=0x{origTexId:X8} " + (hit ? "[MATCH]" : "[miss]"));
                    if (origTexId == 0) continue;
                    if (oldToNew.TryGetValue(origTexId, out uint newId))
                    {
                        resolved ??= new Dictionary<uint, uint>();
                        resolved[surfId] = newId;
                    }
                }

                if (resolved is not null)
                    resolvedOverridesByPart[pi] = resolved;
            }
        }

        // Apply ObjScale by baking a scale matrix into each MeshRef's
        // PartTransform. Scenery hydration already does this pattern
        // (scaleMat baked into PartTransform at Setup flatten time).
        // Fallback to 1.0 if the server didn't send ObjScale (common for
        // creatures/characters whose size is intrinsic to the mesh).
        float scale = spawn.ObjScale ?? 1.0f;
        var scaleMat = System.Numerics.Matrix4x4.CreateScale(scale);

        var meshRefs = new List<AcDream.Core.World.MeshRef>();
        for (int partIdx = 0; partIdx < parts.Count; partIdx++)
        {
            var mr = parts[partIdx];
            var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(mr.GfxObjId);
            if (gfx is null) continue;
            _physicsDataCache.CacheGfxObj(mr.GfxObjId, gfx);
            var subMeshes = AcDream.Core.Meshing.GfxObjMesh.Build(gfx, _dats);
            _staticMesh.EnsureUploaded(mr.GfxObjId, subMeshes);

            IReadOnlyDictionary<uint, uint>? surfaceOverrides = null;
            if (resolvedOverridesByPart is not null && resolvedOverridesByPart.TryGetValue(partIdx, out var partOverrides))
                surfaceOverrides = partOverrides;

            // Multiplication order matches offline scenery hydration:
            // `PartTransform * scaleMat`. In row-vector semantics this means
            // "apply PartTransform first (which includes the part-attachment
            // translation), then scale in the resulting space." Using the
            // opposite order (`scaleMat * PartTransform`) scales in mesh-local
            // space first, which leaves the part-attachment offset unscaled —
            // for multi-part entities like the Nullified Statue that causes
            // the parts to drift relative to each other ("distorted") and the
            // base anchor to end up below the ground ("sinks into foundry").
            var transform = scale == 1.0f ? mr.PartTransform : mr.PartTransform * scaleMat;

            meshRefs.Add(new AcDream.Core.World.MeshRef(mr.GfxObjId, transform)
            {
                SurfaceOverrides = surfaceOverrides,
            });
        }
        if (meshRefs.Count == 0)
        {
            _liveDropReasonNoMeshRefs++;
            Console.WriteLine($"live: DROP no mesh refs from setup 0x{spawn.SetupTableId.Value:X8} " +
                              $"(guid=0x{spawn.Guid:X8})");
            return;
        }

        // Build optional per-entity palette override from the server's base
        // palette + subpalette overlays. The renderer applies these to
        // palette-indexed textures (PFID_P8 / PFID_INDEX16) to get per-entity
        // skin/hair/body colors and statue stone recoloring. Non-palette
        // textures ignore the override.
        AcDream.Core.World.PaletteOverride? paletteOverride = null;
        if (spawn.SubPalettes is { Count: > 0 } spList)
        {
            var ranges = new AcDream.Core.World.PaletteOverride.SubPaletteRange[spList.Count];
            for (int i = 0; i < spList.Count; i++)
                ranges[i] = new AcDream.Core.World.PaletteOverride.SubPaletteRange(
                    spList[i].SubPaletteId, spList[i].Offset, spList[i].Length);
            paletteOverride = new AcDream.Core.World.PaletteOverride(
                BasePaletteId: spawn.BasePaletteId ?? 0,
                SubPalettes: ranges);
        }

        var entity = new AcDream.Core.World.WorldEntity
        {
            Id = _liveEntityIdCounter++,
            ServerGuid = spawn.Guid,
            SourceGfxObjOrSetupId = spawn.SetupTableId.Value,
            Position = worldPos,
            Rotation = rot,
            MeshRefs = meshRefs,
            PaletteOverride = paletteOverride,
        };

        var snapshot = new AcDream.Plugin.Abstractions.WorldEntitySnapshot(
            Id: entity.Id,
            SourceId: entity.SourceGfxObjOrSetupId,
            Position: entity.Position,
            Rotation: entity.Rotation);
        _worldGameState.Add(snapshot);
        _worldEvents.FireEntitySpawned(snapshot);

        // Phase A.1: register entity into GpuWorldState so the next frame picks
        // it up. AppendLiveEntity is a no-op if the landblock isn't loaded yet
        // (can happen if the server sends CreateObjects before we finish loading).
        _worldState.AppendLiveEntity(spawn.Position!.Value.LandblockId, entity);
        _liveSpawnHydrated++;

        // Phase 6.6/6.7: remember the server-guid → WorldEntity mapping so
        // UpdateMotion / UpdatePosition events can reseat this entity by guid.
        _entitiesByServerGuid[spawn.Guid] = entity;

        // Phase B.2: capture the server-sent MotionTableId for our own
        // character so UpdatePlayerAnimation can pass it to GetIdleCycle.
        // The Setup's DefaultMotionTable is often 0 for human characters;
        // the real table comes from PhysicsDescriptionFlag.MTable.
        if (spawn.Guid == _playerServerGuid && spawn.MotionTableId is not null)
            _playerMotionTableId = spawn.MotionTableId;

        // Phase 6.4: register for per-frame playback if we resolved a real
        // cycle with a non-zero framerate and at least two frames in the
        // cycle (single-frame poses are static and don't need ticking).
        // Diagnostic: log why we did / didn't register so we can tell
        // which entities fall through the filter.
        if (idleCycle is null)
            _liveAnimRejectNoCycle++;
        else if (idleCycle.Framerate == 0f)
            _liveAnimRejectFramerate++;
        else if (idleCycle.HighFrame <= idleCycle.LowFrame)
            _liveAnimRejectSingleFrame++;
        else if (idleCycle.Animation.PartFrames.Count <= 1)
            _liveAnimRejectPartFrames++;



        if (idleCycle is not null && idleCycle.Framerate != 0f
            && idleCycle.HighFrame > idleCycle.LowFrame
            && idleCycle.Animation.PartFrames.Count > 1)
        {
            // Snapshot per-part identity from the hydrated meshRefs so the
            // tick can rebuild MeshRefs without redoing AnimPartChanges or
            // texture-override resolution every frame.
            var template = new (uint, IReadOnlyDictionary<uint, uint>?)[meshRefs.Count];
            for (int i = 0; i < meshRefs.Count; i++)
                template[i] = (meshRefs[i].GfxObjId, meshRefs[i].SurfaceOverrides);

            // Create an AnimationSequencer if we can load the MotionTable.
            AcDream.Core.Physics.AnimationSequencer? sequencer = null;
            if (_animLoader is not null)
            {
                uint mtableId = spawn.MotionTableId ?? (uint)setup.DefaultMotionTable;
                if (mtableId != 0)
                {
                    var mtable = _dats.Get<DatReaderWriter.DBObjs.MotionTable>(mtableId);
                    if (mtable is not null)
                    {
                        sequencer = new AcDream.Core.Physics.AnimationSequencer(setup, mtable, _animLoader);
                        uint seqStyle = stanceOverride is > 0 ? (uint)stanceOverride.Value : (uint)mtable.DefaultStyle;
                        uint seqMotion = commandOverride is > 0 ? (uint)commandOverride.Value : 0x41000003u;
                        sequencer.SetCycle(seqStyle, seqMotion);
                    }
                }
            }

            _animatedEntities[entity.Id] = new AnimatedEntity
            {
                Entity = entity,
                Setup = setup,
                Animation = idleCycle.Animation,
                LowFrame = Math.Max(0, idleCycle.LowFrame),
                HighFrame = Math.Min(idleCycle.HighFrame, idleCycle.Animation.PartFrames.Count - 1),
                Framerate = idleCycle.Framerate,
                Scale = scale,
                PartTemplate = template,
                CurrFrame = idleCycle.LowFrame,
                Sequencer = sequencer,
            };

            // Phase E.2: register entity's SoundTable so SoundTableHook can
            // resolve creature-specific sounds (footsteps, attack vocalizations,
            // damage grunts, etc). Server-sent SoundTable override would take
            // precedence here when the wire layer delivers it.
            if (_entitySoundTables is not null)
            {
                uint soundTableId = (uint)setup.DefaultSoundTable;
                if (soundTableId != 0)
                    _entitySoundTables.Set(entity.Id, soundTableId);
            }
        }

        // Dump a summary periodically so we can see drop breakdowns without
        // waiting for a graceful shutdown.
        if (_liveSpawnReceived % 20 == 0)
        {
            Console.WriteLine(
                $"live: animated={_animatedEntities.Count} " +
                $"animReject: noCycle={_liveAnimRejectNoCycle} fr0={_liveAnimRejectFramerate} " +
                $"1frame={_liveAnimRejectSingleFrame} partFrames={_liveAnimRejectPartFrames}");
            Console.WriteLine(
                $"live: summary recv={_liveSpawnReceived} hydrated={_liveSpawnHydrated} " +
                $"drops: noPos={_liveDropReasonNoPos} noSetup={_liveDropReasonNoSetup} " +
                $"setupMissing={_liveDropReasonSetupDatMissing} noMesh={_liveDropReasonNoMeshRefs}");
        }
    }

    /// <summary>
    /// Bilinear sample of the landblock heightmap at (x, y) in landblock-local
    /// world units. Matches the x-major indexing convention of LandblockMesh.
    /// </summary>
    private float SampleTerrainZ(DatReaderWriter.DBObjs.LandBlock block, float[] heightTable, float worldX, float worldY)
    {
        // Exact port of WorldBuilder TerrainUtils.GetHeight (line 59-108).
        // Barycentric interpolation over the cell's triangle pair, respecting
        // the cell's split direction (SWtoNE vs SEtoNW).
        const float CellSize = 24f;

        uint cellX = (uint)(worldX / CellSize);
        uint cellY = (uint)(worldY / CellSize);
        if (cellX >= 8) cellX = 7;
        if (cellY >= 8) cellY = 7;

        uint landblockX = (block.Id >> 24) & 0xFFu;
        uint landblockY = (block.Id >> 16) & 0xFFu;
        var splitDirection = AcDream.Core.Terrain.TerrainBlending.CalculateSplitDirection(
            landblockX, cellX, landblockY, cellY);

        // 4 cell corners (heightmap x-major: Height[x*9 + y])
        float h0 = heightTable[block.Height[cellX * 9 + cellY]];           // BL
        float h1 = heightTable[block.Height[(cellX + 1) * 9 + cellY]];     // BR
        float h2 = heightTable[block.Height[(cellX + 1) * 9 + (cellY + 1)]]; // TR
        float h3 = heightTable[block.Height[cellX * 9 + (cellY + 1)]];     // TL

        float lx = worldX - cellX * CellSize;
        float ly = worldY - cellY * CellSize;
        float s = lx / CellSize;
        float t = ly / CellSize;

        if (splitDirection == AcDream.Core.Terrain.CellSplitDirection.SWtoNE)
        {
            if (s + t <= 1f)
            {
                return h0 * (1f - s - t) + h1 * s + h3 * t;
            }
            else
            {
                float u = s + t - 1f;
                float v = 1f - s;
                float w = 1f - u - v;
                return h1 * w + h2 * u + h3 * v;
            }
        }
        else // SEtoNW
        {
            if (s >= t)
            {
                return h0 * (1f - s) + h1 * (s - t) + h2 * t;
            }
            else
            {
                return h0 * (1f - t) + h2 * s + h3 * (t - s);
            }
        }
    }

    /// <summary>
    /// Phase 6.6: the server says an entity's motion has changed. Look up
    /// the AnimatedEntity for that guid, re-resolve the idle cycle with the
    /// new (stance, forward-command) override, and if the cycle is still
    /// animated, swap in the new animation/frame range. Entities not in
    /// the animated map (static props, entities rejected at spawn time)
    /// are simply ignored — there's nothing to tick for them.
    /// </summary>
    private void OnLiveMotionUpdated(AcDream.Core.Net.WorldSession.EntityMotionUpdate update)
    {
        if (_dats is null) return;
        if (!_entitiesByServerGuid.TryGetValue(update.Guid, out var entity)) return;
        if (!_animatedEntities.TryGetValue(entity.Id, out var ae)) return;

        // Re-resolve using the new stance/command. Keep the setup and
        // motion-table we already know about — the server's motion
        // updates override state within the same table, not swap tables.
        //
        // IMPORTANT: stance and command are BOTH optional. Remote-player
        // autonomous broadcasts frequently set only one flag (e.g. just
        // ForwardCommand) with currentStyle=0x0000 meaning "no stance
        // change — keep current." Treating stance=0 as "default stance"
        // drops the real state; instead we preserve the sequencer's
        // current style.
        ushort stance = update.MotionState.Stance;
        ushort? command = update.MotionState.ForwardCommand;

        // Diagnostic: dump every inbound UpdateMotion so we can trace why
        // remote chars don't transition off RunForward when they stop.
        // Enable with ACDREAM_DUMP_MOTION=1.
        if (Environment.GetEnvironmentVariable("ACDREAM_DUMP_MOTION") == "1"
            && update.Guid != _playerServerGuid)
        {
            string cmdStr = command.HasValue ? $"0x{command.Value:X4}" : "null";
            float spd = update.MotionState.ForwardSpeed ?? 0f;
            uint seqStyle = ae.Sequencer?.CurrentStyle ?? 0;
            uint seqMotion = ae.Sequencer?.CurrentMotion ?? 0;
            Console.WriteLine(
                $"UM guid=0x{update.Guid:X8} stance=0x{stance:X4} cmd={cmdStr} spd={spd:F2} " +
                $"| seq now style=0x{seqStyle:X8} motion=0x{seqMotion:X8}");
        }

        // Wire server-echoed RunRate first — used for the player's own
        // locomotion tuning regardless of whether a cycle resolves.
        if (_playerController is not null
            && update.Guid == _playerServerGuid
            && update.MotionState.ForwardSpeed.HasValue
            && update.MotionState.ForwardSpeed.Value > 0f)
        {
            _playerController.ApplyServerRunRate(update.MotionState.ForwardSpeed.Value);
        }

        // ── Sequencer path (preferred) ──────────────────────────────────
        // Call SetCycle directly. The sequencer already handles:
        //   - left→right / backward→forward remapping via adjust_motion
        //   - style and motion as u32 MotionCommand values
        //   - fast-path for identical state
        //
        // When the server omits a field (stance flag not set, or command
        // flag not set), "no change" means we must preserve the sequencer's
        // current state, NOT fall back to a table default.
        if (ae.Sequencer is not null)
        {
            uint fullStyle = stance != 0
                ? (0x80000000u | (uint)stance)
                : ae.Sequencer.CurrentStyle;

            // ACE's stop signal: ForwardCommand flag CLEARED on the wire.
            // Per ACE InterpretedMotionState(MovementData) ctor + BuildMovementFlags,
            // when the player releases keys the InterpretedMotionState has
            // ForwardCommand = Invalid (default) and BuildMovementFlags doesn't
            // set bit 0x02 — so the field is absent. Retail's decompiled
            // handler (FUN_005295D0 → FUN_0051F260 @ chunk_00510000.c:13957)
            // bulk-copies Invalid/0 into the physics obj, which StopCompletely
            // treats as "return to style default (Ready)."
            //
            //   command == null      → retail stop signal → Ready
            //   command.Value == 0   → explicit 0 (rare)   → Ready
            //   otherwise            → resolve class byte and use full cmd
            uint fullMotion;
            if (!command.HasValue || command.Value == 0)
            {
                // Stop — return to the style's default substate (Ready).
                fullMotion = 0x41000003u;
            }
            else
            {
                // Use MotionCommandResolver to restore the proper class
                // byte from the wire's 16-bit ForwardCommand.
                uint resolved = AcDream.Core.Physics.MotionCommandResolver
                    .ReconstructFullCommand(command.Value);
                fullMotion = resolved != 0
                    ? resolved
                    : (ae.Sequencer.CurrentMotion & 0xFF000000u) | (uint)command.Value;
                if (fullMotion == (uint)command.Value) // no class bits yet
                    fullMotion = 0x40000000u | (uint)command.Value;
            }

            // ForwardSpeed from the InterpretedMotionState (flag 0x04).
            // ACE omits this field when speed == 1.0 (only sets the flag
            // when ForwardSpeed != 1.0 — InterpretedMotionState.cs:101).
            // So:
            //   - field absent       → default 1.0 (normal speed)
            //   - field present      → USE THE VALUE, including zero.
            //
            // Zero is a VALID stop signal: when the retail client releases
            // W, ACE broadcasts WalkForward with ForwardSpeed=0 (via
            // apply_run_to_command). Treating zero as "unspecified / 1.0"
            // produces "slow walk that never stops" — exactly what the
            // stop bug looked like.
            float speedMod = update.MotionState.ForwardSpeed ?? 1f;

            if (Environment.GetEnvironmentVariable("ACDREAM_DUMP_MOTION") == "1"
                && update.Guid != _playerServerGuid)
                Console.WriteLine(
                    $"UM    ↳ SetCycle(style=0x{fullStyle:X8}, motion=0x{fullMotion:X8}, speed={speedMod:F2})");

            // No-op if same; the sequencer's fast path guards against that.
            uint priorMotion = ae.Sequencer.CurrentMotion;

            // CRITICAL: for the local player, UpdatePlayerAnimation is the
            // authoritative driver of the sequencer. ACE's BroadcastMovement
            // echoes the player's own motion back, but:
            //   (a) ACE's own ForwardSpeed is `creature.GetRunRate()`, which
            //       may differ from our locally-computed runRate (ACDREAM_RUN_SKILL
            //       vs real server-side skills).
            //   (b) ACE omits the ForwardSpeed flag when speed == 1.0 (per
            //       InterpretedMotionState.BuildMovementFlags). When omitted,
            //       our wire parser returns null and we'd default to 1.0 —
            //       clobbering our locally-authoritative 2.375 × animScale
            //       and leaving the legs at 30 fps cadence regardless of
            //       actual run rate.
            // So: for the player's own guid, skip the wire-echo SetCycle.
            // UpdatePlayerAnimation has already set the correct cycle with
            // our locally-chosen speedMod, and that value should persist
            // until the next local motion change.
            if (update.Guid == _playerServerGuid)
            {
                // Still update the stance echo (_playerMotionTableId, etc) via
                // the paths above, but don't stomp the animation sequencer.
            }
            else
            {
                // Pick which cycle to play on the sequencer. Priority:
                //   1. Forward cmd if active (RunForward / WalkForward) — legs run/walk.
                //   2. Else sidestep cmd if active — legs strafe.
                //   3. Else turn cmd if active — legs pivot.
                //   4. Else Ready — idle.
                //
                // For forward+sidestep or forward+turn, the forward cycle
                // wins at the anim layer; the sidestep/turn contribute via
                // MotionInterpreter velocity/omega writes.
                uint animCycle = fullMotion;
                float animSpeed = speedMod;
                uint fwdLow = fullMotion & 0xFFu;
                bool fwdIsRunWalk = fwdLow == 0x05 /* Walk */ || fwdLow == 0x06 /* WalkBack */
                                 || fwdLow == 0x07 /* Run */;
                if (!fwdIsRunWalk)
                {
                    // Forward is Ready (or absent). Prefer sidestep cycle if present,
                    // else turn cycle, else Ready.
                    if (update.MotionState.SideStepCommand is { } sideForAnim && sideForAnim != 0)
                    {
                        uint sideFullForAnim = AcDream.Core.Physics.MotionCommandResolver
                            .ReconstructFullCommand(sideForAnim);
                        if (sideFullForAnim == 0) sideFullForAnim = 0x65000000u | sideForAnim;
                        animCycle = sideFullForAnim;
                        animSpeed = update.MotionState.SideStepSpeed ?? 1f;
                    }
                    else if (update.MotionState.TurnCommand is { } turnForAnim && turnForAnim != 0)
                    {
                        uint turnFullForAnim = AcDream.Core.Physics.MotionCommandResolver
                            .ReconstructFullCommand(turnForAnim);
                        if (turnFullForAnim == 0) turnFullForAnim = 0x65000000u | turnForAnim;
                        animCycle = turnFullForAnim;
                        animSpeed = MathF.Abs(update.MotionState.TurnSpeed ?? 1f);
                    }
                }
                // K-fix17 (2026-04-26): preserve the Falling cycle while
                // the remote is airborne. ACE broadcasts UpdateMotion
                // mid-arc when the player turns / runs — the previous
                // SetCycle here swapped Falling → RunForward, breaking
                // the visible jump animation. The arc still played out
                // physics-wise (body went up/down), but the legs ran
                // instead of folded. Skip the cycle swap when airborne;
                // the InterpretedState updates below still fire so the
                // body's velocity matches the new motion command, AND
                // the post-resolve landing path restores the cycle to
                // whatever the interpreted state says when the body
                // lands.
                bool remoteIsAirborne = _remoteDeadReckon.TryGetValue(update.Guid, out var rmCheck)
                                     && rmCheck.Airborne;
                if (!remoteIsAirborne)
                    ae.Sequencer.SetCycle(fullStyle, animCycle, animSpeed);

                // Retail runs the full MotionInterp state machine on every
                // remote. Route each wire command (forward, sidestep, turn)
                // through DoInterpretedMotion so apply_current_movement →
                // get_state_velocity → PhysicsBody.set_local_velocity fires
                // on a subsequent tick exactly as retail's FUN_00529210
                // (apply_current_movement) does.
                //
                // Decompile refs:
                //   FUN_00529930 DoMotion
                //   FUN_00528f70 DoInterpretedMotion
                //   FUN_00528960 get_state_velocity
                //   FUN_00529210 apply_current_movement
                if (_remoteDeadReckon.TryGetValue(update.Guid, out var remoteMot))
                {
                    // Forward axis (Ready / WalkForward / RunForward / WalkBackward).
                    remoteMot.Motion.DoInterpretedMotion(
                        fullMotion, speedMod, modifyInterpretedState: true);

                    // Sidestep axis.
                    if (update.MotionState.SideStepCommand is { } sideCmd16 && sideCmd16 != 0)
                    {
                        uint sideFull = AcDream.Core.Physics.MotionCommandResolver
                            .ReconstructFullCommand(sideCmd16);
                        if (sideFull == 0) sideFull = 0x65000000u | sideCmd16;
                        float sideSpd = update.MotionState.SideStepSpeed ?? 1f;
                        remoteMot.Motion.DoInterpretedMotion(
                            sideFull, sideSpd, modifyInterpretedState: true);
                    }
                    else
                    {
                        // No sidestep — clear any leftover strafing motion.
                        remoteMot.Motion.StopInterpretedMotion(
                            AcDream.Core.Physics.MotionCommand.SideStepRight, modifyInterpretedState: true);
                        remoteMot.Motion.StopInterpretedMotion(
                            AcDream.Core.Physics.MotionCommand.SideStepLeft, modifyInterpretedState: true);
                    }

                    // Turn axis — and use as the on/off switch for ObservedOmega.
                    // On turn start: seed ObservedOmega from the formula
                    // (π/2 × turnSpeed) so rotation begins THIS tick without
                    // waiting for the next UP to observe a delta.
                    // On turn end: zero ObservedOmega so rotation stops
                    // immediately instead of coasting at the last observed
                    // rate until the next UP shows zero delta.
                    // UpdatePosition still REFINES the rate from actual
                    // server deltas (more accurate than the formula), but
                    // this ensures instant on/off response.
                    if (update.MotionState.TurnCommand is { } turnCmd16 && turnCmd16 != 0)
                    {
                        uint turnFull = AcDream.Core.Physics.MotionCommandResolver
                            .ReconstructFullCommand(turnCmd16);
                        if (turnFull == 0) turnFull = 0x65000000u | turnCmd16;
                        float turnSpd = update.MotionState.TurnSpeed ?? 1f;
                        remoteMot.Motion.DoInterpretedMotion(
                            turnFull, turnSpd, modifyInterpretedState: true);
                        // Seed ObservedOmega with formula so rotation starts
                        // immediately; UP deltas will refine the rate.
                        uint turnLow = turnFull & 0xFFu;
                        if (turnLow == 0x0D /* TurnRight */)
                            remoteMot.ObservedOmega = new System.Numerics.Vector3(0, 0, -(MathF.PI / 2f) * turnSpd);
                        else if (turnLow == 0x0E /* TurnLeft */)
                            remoteMot.ObservedOmega = new System.Numerics.Vector3(0, 0, (MathF.PI / 2f) * turnSpd);
                    }
                    else
                    {
                        remoteMot.Motion.StopInterpretedMotion(
                            AcDream.Core.Physics.MotionCommand.TurnRight, modifyInterpretedState: true);
                        remoteMot.Motion.StopInterpretedMotion(
                            AcDream.Core.Physics.MotionCommand.TurnLeft, modifyInterpretedState: true);
                        // Zero ObservedOmega immediately — don't coast.
                        remoteMot.ObservedOmega = System.Numerics.Vector3.Zero;
                    }
                }
            }

            // CRITICAL: when we enter a locomotion cycle (Walk/Run/etc),
            // stamp the _remoteLastMove timestamp to "now". Without this,
            // the stop-detection loop in TickAnimations sees the previous
            // _remoteLastMove timestamp (set by the last UpdatePosition,
            // often >300ms ago during idle) and fires the stop signal
            // IMMEDIATELY — flipping the sequencer straight back to Ready.
            // The visible symptom was "remote char never animates; just
            // stands there, teleporting position every UpdatePosition."
            // Fresh timestamp gives the stop-timer a full 300ms window to
            // observe genuine position stagnation before reverting.
            uint newLo = fullMotion & 0xFFu;
            bool enteringLocomotion = newLo == 0x05 || newLo == 0x06
                                   || newLo == 0x07
                                   || newLo == 0x0F || newLo == 0x10;
            uint oldLo = priorMotion & 0xFFu;
            bool wasLocomotion = oldLo == 0x05 || oldLo == 0x06
                              || oldLo == 0x07
                              || oldLo == 0x0F || oldLo == 0x10;
            if (enteringLocomotion && !wasLocomotion && update.Guid != _playerServerGuid)
            {
                // Reset both stop signals so stop-detection starts a fresh
                // window from this transition. Without this, the entity
                // starts its run animation and is instantly interrupted.
                var refreshedTime = System.DateTime.UtcNow;
                if (_remoteLastMove.TryGetValue(update.Guid, out var prev))
                    _remoteLastMove[update.Guid] = (prev.Pos, refreshedTime);
                if (_remoteDeadReckon.TryGetValue(update.Guid, out var dr))
                    dr.LastServerPosTime = (refreshedTime - System.DateTime.UnixEpoch).TotalSeconds;
            }

            // Route the Commands list — one-shot Actions, Modifiers, and
            // ChatEmotes (mask classes 0x10, 0x20, 0x13 per r03 §3). These
            // live in the motion table's Links / Modifiers dicts, not
            // Cycles, and are played on top of the current cycle via
            // PlayAction which resolves the right dict and interleaves the
            // action frames before the cyclic tail.
            //
            // A typical NPC wave looks like:
            //   ForwardCommand=0 (Ready) + Commands=[{0x0087=Wave, speed=1.0}]
            //                                       [{0x0003=Ready, ...}]
            // Each item runs through PlayAction (for 0x10/0x20 mask) or the
            // standard SetCycle path (for 0x40 SubState). We leave SubState
            // commands to fall through to the next UpdateMotion; that's how
            // retail handles transition sequences (Wave → Ready).
            if (update.MotionState.Commands is { Count: > 0 } cmds)
            {
                foreach (var item in cmds)
                {
                    // Restore the 32-bit MotionCommand from the wire's 16-bit
                    // truncation by OR-ing class bits. The class is encoded
                    // in the low byte's high nibble via command ranges:
                    //   0x0003, 0x0005-0x0010 — SubState class (0x40xx xxxx)
                    //   0x0087 (Wave), 0x007D (BowDeep) etc — ChatEmote (0x13xx xxxx)
                    //   0x0051-0x00A1 — Action class (0x10xx xxxx)
                    //
                    // The retail MotionCommand enum carries the class byte in
                    // bits 24-31. DatReaderWriter's enum values match. For
                    // broadcasts, servers emit only low 16 bits (ACE
                    // InterpretedMotionState.cs:139). We reconstruct via a
                    // range-based lookup. See MotionCommand.generated.cs.
                    uint fullCmd = AcDream.Core.Physics.MotionCommandResolver.ReconstructFullCommand(item.Command);
                    if (fullCmd == 0) continue;

                    // Action class: play through the link dict then drop back
                    // to the current cycle. Modifier class: resolve from the
                    // Modifiers dict and combine on top. SubState: cycle
                    // change; route through SetCycle so the style-specific
                    // cycle fallback applies.
                    uint cls = fullCmd & 0xFF000000u;
                    if ((cls & 0x10000000u) != 0 || (cls & 0x20000000u) != 0
                        || cls == 0x12000000u || cls == 0x13000000u)
                    {
                        ae.Sequencer.PlayAction(fullCmd, item.Speed);
                    }
                    else if ((cls & 0x40000000u) != 0)
                    {
                        // Substate in the command list — typically the "and
                        // then return to Ready" item. Update the cycle.
                        ae.Sequencer.SetCycle(fullStyle, fullCmd, item.Speed);
                    }
                    // else: Style / UI / Toggle class — not animation-driving.
                }
            }
            return;
        }

        // ── Legacy path (entities without a sequencer) ──────────────────
        // Here we DO use GetIdleCycle because the legacy tick loop needs
        // a concrete Animation + frame range. Only swap when the resolver
        // returns a clearly-better cycle.
        var newCycle = AcDream.Core.Meshing.MotionResolver.GetIdleCycle(
            ae.Setup, _dats,
            motionTableIdOverride: null,
            stanceOverride: stance,
            commandOverride: command);
        bool newCycleIsGood = newCycle is not null
            && newCycle.Framerate != 0f
            && newCycle.HighFrame >= newCycle.LowFrame
            && newCycle.Animation.PartFrames.Count >= 1;
        if (!newCycleIsGood) return;

        ae.Animation = newCycle!.Animation;
        ae.LowFrame = Math.Max(0, newCycle.LowFrame);
        ae.HighFrame = Math.Min(newCycle.HighFrame, newCycle.Animation.PartFrames.Count - 1);
        ae.Framerate = newCycle.Framerate;
        ae.CurrFrame = ae.LowFrame;
    }

    /// <summary>
    /// Phase 6.7: the server says an entity moved. Translate its new
    /// landblock-local position into acdream world space (same math as
    /// CreateObject hydration) and update the entity's Position/Rotation
    /// in place so the next Draw picks up the new transform.
    ///
    /// Phase B.3 extension: if the player controller is in PortalSpace and
    /// this update is for our own character, detect a large position change
    /// (different landblock or > 100 units distance). If detected, recenter
    /// the streaming controller, resolve the new position through physics,
    /// snap the player entity + controller, and return to InWorld. Also sends
    /// LoginComplete so the server knows the client has loaded the destination.
    /// </summary>
    /// <summary>
    /// K-fix9 (2026-04-26): handle 0xF74E VectorUpdate — ACE broadcasts
    /// this on remote-player JUMPS (Player.cs:954). The payload carries
    /// the world-space launch velocity. Without handling it, remote
    /// jumps render as a tiny lift-and-back because we never see the
    /// +Z velocity that would integrate into a proper arc.
    /// </summary>
    private void OnLiveVectorUpdated(AcDream.Core.Net.Messages.VectorUpdate.Parsed update)
    {
        if (update.Guid == _playerServerGuid) return;          // local jump uses our own physics
        if (!_remoteDeadReckon.TryGetValue(update.Guid, out var rm)) return;

        // World-space velocity. Apply directly to the body — the per-tick
        // remote update will integrate Position += Velocity × dt + 0.5 × Accel × dt².
        rm.Body.Velocity = update.Velocity;

        // Mark airborne when the launch has meaningful +Z. Threshold
        // 0.5 m/s rejects noise / horizontal-only updates (server might
        // also use VectorUpdate for non-jump events). The per-tick
        // remote update reads .Airborne to skip the ground-clamp branch
        // and apply gravity instead.
        if (update.Velocity.Z > 0.5f)
        {
            rm.Airborne = true;
            // Clear ground-contact bits + enable gravity so calc_acceleration
            // returns (0, 0, -9.8) instead of zero. UpdatePhysicsInternal then
            // produces the parabolic arc.
            rm.Body.TransientState &= ~(AcDream.Core.Physics.TransientStateFlags.Contact
                                      | AcDream.Core.Physics.TransientStateFlags.OnWalkable);
            rm.Body.State |= AcDream.Core.Physics.PhysicsStateFlags.Gravity;

            // K-fix10 (2026-04-26): force the Falling animation cycle on
            // the remote so the legs match the arc. Mirrors the local
            // player's UpdatePlayerAnimation path which sets
            // animCommand = Falling whenever !IsOnGround.
            //
            // K-fix18 (2026-04-26): pass skipTransitionLink:true so the
            // RunForward→Falling transition frames don't play first.
            // Without that flag the remote stood still for ~100 ms at
            // the start of the jump while the link drained, then
            // folded into Falling. Skipping the link makes the pose
            // engage immediately on jump start.
            if (_entitiesByServerGuid.TryGetValue(update.Guid, out var ent)
                && _animatedEntities.TryGetValue(ent.Id, out var ae)
                && ae.Sequencer is not null)
            {
                uint style = ae.Sequencer.CurrentStyle != 0
                    ? ae.Sequencer.CurrentStyle
                    : 0x8000003Du;   // NonCombat default
                ae.Sequencer.SetCycle(style, AcDream.Core.Physics.MotionCommand.Falling, 1.0f,
                    skipTransitionLink: true);
            }
        }

        if (Environment.GetEnvironmentVariable("ACDREAM_DUMP_MOTION") == "1")
        {
            Console.WriteLine(
                $"VU    guid=0x{update.Guid:X8} vel=({update.Velocity.X:F2},{update.Velocity.Y:F2},{update.Velocity.Z:F2}) airborne={rm.Airborne}");
        }
    }

    private void OnLivePositionUpdated(AcDream.Core.Net.WorldSession.EntityPositionUpdate update)
    {
        // Phase A.1: track the most recently updated entity's landblock so the
        // streaming controller can follow the player. TODO: filter by our own
        // character guid once we reliably know it from CharacterList.
        _lastLivePlayerLandblockId = update.Position.LandblockId;

        if (!_entitiesByServerGuid.TryGetValue(update.Guid, out var entity)) return;

        var p = update.Position;
        int lbX = (int)((p.LandblockId >> 24) & 0xFFu);
        int lbY = (int)((p.LandblockId >> 16) & 0xFFu);
        var origin = new System.Numerics.Vector3(
            (lbX - _liveCenterX) * 192f,
            (lbY - _liveCenterY) * 192f,
            0f);
        var worldPos = new System.Numerics.Vector3(p.PositionX, p.PositionY, p.PositionZ) + origin;
        var rot = new System.Numerics.Quaternion(p.RotationX, p.RotationY, p.RotationZ, p.RotationW);

        // Capture the pre-update render position for the soft-snap residual
        // calculation below. Assign entity.Position to the server truth up
        // front; if we then compute a snap residual, we restore the rendered
        // position by adding the residual back (so the visual doesn't jerk
        // for one frame before the residual decay kicks in on the next tick).
        System.Numerics.Vector3 preSnapPos = entity.Position;
        entity.Position = worldPos;
        entity.Rotation = rot;

// Track remote-entity motion for stop detection. Only record the
        // timestamp when position moved MEANINGFULLY (> 0.05m). Updates
        // that report the same position keep the old Time, so the
        // TickAnimations check can see when motion last changed.
        //
        // Also populate the dead-reckon state so TickAnimations can
        // integrate velocity between server updates and avoid teleport jitter.
        // Observed-velocity is computed from the position delta across
        // consecutive updates — this is the fallback when the motion table's
        // MotionData.Velocity is zero (NPCs without HasVelocity).
        if (update.Guid != _playerServerGuid)
        {
            var now = System.DateTime.UtcNow;
            if (_remoteLastMove.TryGetValue(update.Guid, out var prev))
            {
                float moveDist = System.Numerics.Vector3.Distance(prev.Pos, worldPos);
                if (moveDist > 0.05f)
                    _remoteLastMove[update.Guid] = (worldPos, now);
                // else: leave old entry so "Time" = last real movement time
            }
            else
            {
                _remoteLastMove[update.Guid] = (worldPos, now);
            }

            // Retail-faithful hard-snap on UpdatePosition.
            // Decompile: FUN_00559030 @ chunk_00550000.c:8232 writes
            // pos/rot directly into PhysicsObj+0x80..0xBC with no blending.
            // Between UpdatePositions, per-tick velocity integration keeps
            // the rendered position close to server truth so each snap is
            // small. When HasVelocity is set, we also seed PhysicsBody
            // velocity (matches retail's set_velocity call in the same
            // dispatcher).
            if (!_remoteDeadReckon.TryGetValue(update.Guid, out var rmState))
            {
                rmState = new RemoteMotion();
                _remoteDeadReckon[update.Guid] = rmState;
                // Hard-snap orientation on first spawn so the per-tick
                // slerp doesn't visibly rotate from Identity to truth.
                rmState.Body.Orientation = rot;
            }
            rmState.Body.Position = worldPos;
            // K-fix15 (2026-04-26): DON'T auto-clear airborne on UP.
            // ACE broadcasts UPs during the arc (peak / mid-fall / land)
            // at ~5-10 Hz. The previous K-fix9 logic cleared Airborne on
            // the FIRST UP after the jump, which:
            //   * restored Contact + OnWalkable,
            //   * removed the Gravity flag,
            //   * caused the next per-tick to stomp Velocity via
            //     apply_current_movement (reading InterpretedState =
            //     Ready, so Velocity.Z went to 0),
            // …so the body got stuck at the server-broadcast apex Z,
            // visibly hovering. The fix: leave Airborne true; the
            // per-tick post-resolve logic detects an actual landing
            // (resolveResult.IsOnGround && Velocity.Z <= 0) and clears
            // it then. Mirrors how PlayerMovementController re-grounds
            // the local player at the bottom of its arc.
            //
            // The position-snap above is still authoritative — if ACE
            // says the body is at Z=68 mid-arc, we render Z=68. But we
            // continue integrating gravity from there, so the body
            // proceeds along the parabolic path between UPs.
            // Adopt the server's cell ID as the transition starting cell.
            // Retail authoritatively hard-snaps cell membership here too; our
            // per-tick ResolveWithTransition sweep then advances CheckCellId
            // as the sphere crosses cells and writes the new cell back into
            // rmState.CellId so the NEXT frame starts in the correct cell.
            rmState.CellId = p.LandblockId;

            // Retail hard-snaps orientation on UpdatePosition (set_frame,
            // FUN_00514b90 @ chunk_00510000.c:5637 — direct assignment).
            // Rotation rate between UPs comes from the formula-based
            // omega seed on UpdateMotion (π/2 × turnSpeed). We tried
            // deriving omega from UP deltas, but the first UP after a
            // turn starts incorporates the pre-turn interval and produces
            // a halved "observed" rate → visible slow-start. Formula-only
            // is stable and simple; hard-snap fixes any drift.
            rmState.Body.Orientation = rot;
            rmState.TargetOrientation = rot;
            rmState.LastServerPos = worldPos;
            rmState.LastServerPosTime = (now - System.DateTime.UnixEpoch).TotalSeconds;
            // Align the body's physics clock with our clock so update_object
            // doesn't sub-step a huge initial gap.
            rmState.Body.LastUpdateTime = rmState.LastServerPosTime;

            // ACE broadcasts UpdatePosition WITHOUT HasVelocity for player
            // remote motion — even while actively running. Per packet
            // captures: UPs always arrive with velocity null. So we can't
            // use UP-absent-velocity as a stop signal (was previously a
            // bug that fired StopCompletely every UP → intermittent run).
            //
            // Stop is signaled by UpdateMotion(ForwardCommand = Ready =
            // 0x41000003), handled in OnLiveMotionUpdated. UP's role here
            // is just to hard-snap position and adopt velocity IF the
            // packet happens to carry one (rare for players, common for
            // scripted-path NPCs / missiles).
            if (update.Velocity is { } svel)
            {
                rmState.Body.Velocity = svel;
                // Only use the < 0.2 m/s stop signal when velocity was
                // explicitly provided (i.e. server sent HasVelocity + tiny
                // value = "I'm definitely stopped"). Absent velocity field
                // carries no stop information for our ACE.
                if (svel.LengthSquared() < 0.04f)
                {
                    rmState.Motion.StopCompletely();
                    if (_animatedEntities.TryGetValue(entity.Id, out var aeForStop)
                        && aeForStop.Sequencer is not null)
                    {
                        uint curStyle = aeForStop.Sequencer.CurrentStyle;
                        uint readyCmd = (curStyle & 0xFF000000u) != 0
                            ? ((curStyle & 0xFF000000u) | 0x01000003u)
                            : 0x41000003u;
                        aeForStop.Sequencer.SetCycle(curStyle, readyCmd);
                    }
                }
            }

            entity.Position = rmState.Body.Position;
            entity.Rotation = rmState.Body.Orientation;
        }

        // Phase B.3: portal-space arrival detection.
        // Only runs for our own player character while in PortalSpace.
        if (_playerController is not null
            && _playerController.State == AcDream.App.Input.PlayerState.PortalSpace
            && update.Guid == _playerServerGuid)
        {
            // Compute old landblock coords from controller position (using the
            // current streaming origin as the reference center).
            var oldPos = _playerController.Position;
            int oldLbX = _liveCenterX + (int)System.Math.Floor(oldPos.X / 192f);
            int oldLbY = _liveCenterY + (int)System.Math.Floor(oldPos.Y / 192f);

            bool differentLandblock = (lbX != oldLbX || lbY != oldLbY);
            bool farAway = System.Numerics.Vector3.Distance(worldPos, oldPos) > 100f;

            if (differentLandblock || farAway)
            {
                Console.WriteLine(
                    $"live: teleport arrival — old lb=({oldLbX},{oldLbY}) " +
                    $"new lb=({lbX},{lbY}) dist={System.Numerics.Vector3.Distance(worldPos, oldPos):F1}");

                // 1. Recenter the streaming controller on the new landblock.
                _liveCenterX = lbX;
                _liveCenterY = lbY;

                // Recompute worldPos with new center (it becomes local-to-center).
                // After recentering, the new position is (p.PositionX, p.PositionY, p.PositionZ)
                // relative to the new origin — which maps to world-space (0,0,0) + local offset.
                // The streamingController.Tick will pick up _liveCenterX/_liveCenterY automatically.
                var newWorldPos = new System.Numerics.Vector3(p.PositionX, p.PositionY, p.PositionZ);
                // (after recentering, origin is (0,0,0) since lb == center)

                // 2. Resolve through physics for the correct ground Z.
                uint newCellId = p.LandblockId;
                var resolved = _physicsEngine.Resolve(
                    newWorldPos, newCellId,
                    System.Numerics.Vector3.Zero, _playerController.StepUpHeight);
                var snappedPos = new System.Numerics.Vector3(
                    resolved.Position.X, resolved.Position.Y, resolved.Position.Z);

                // 3. Snap player entity + controller.
                entity.Position = snappedPos;
                entity.Rotation = rot;
                _playerController.SetPosition(snappedPos, resolved.CellId);

                // 4. Recenter chase camera on the new position.
                _chaseCamera?.Update(snappedPos, _playerController.Yaw);

                // 5. Return to InWorld.
                _playerController.State = AcDream.App.Input.PlayerState.InWorld;
                Console.WriteLine($"live: teleport complete — snapped to {snappedPos} cell=0x{resolved.CellId:X8}");

                // 5. Send LoginComplete to tell the server the client finished loading.
                // Per holtburger's PlayerTeleport handler (client/messages.rs:434-440),
                // retail clients call send_login_complete() after each portal transition.
                // ResetLoginComplete() clears the latch so the 0xF746 PlayerCreate path
                // doesn't also send one. We send directly here instead.
                _liveSession?.SendGameAction(
                    AcDream.Core.Net.Messages.GameActionLoginComplete.Build());
            }
        }
    }

    /// <summary>
    /// Phase B.3: fires when the server sends a PlayerTeleport (0xF751).
    /// Freeze movement input by setting the player controller to PortalSpace.
    /// The controller's Update() will return a zero-movement result until the
    /// destination UpdatePosition arrives and OnLivePositionUpdated resets the
    /// state to InWorld.
    /// </summary>
    private void OnTeleportStarted(uint sequence)
    {
        if (_playerController is not null)
            _playerController.State = AcDream.App.Input.PlayerState.PortalSpace;
        Console.WriteLine($"live: teleport started (seq={sequence})");
    }

    /// <summary>
    /// Phase 6c — server-sent PlayScript (0xF754) handler. Routes the
    /// <c>(guid, scriptId)</c> pair into <see cref="_scriptRunner"/>
    /// with the CAMERA's current world position as the anchor. For
    /// scene-wide storm effects (lightning) the camera is the right
    /// reference frame since the flash is meant to be "around the
    /// player." For per-entity effects the runner's dedupe by
    /// <c>(scriptId, entityId)</c> keeps multiple simultaneous plays
    /// working on different guids.
    ///
    /// <para>
    /// Improvements for follow-up: look up the guid's actual last-
    /// known world position from <c>_worldState</c> so per-entity
    /// spell casts and emote gestures anchor correctly. For Phase 6
    /// scope (lightning, which is Dereth-wide) the camera anchor is
    /// sufficient.
    /// </para>
    /// </summary>
    private void OnPlayScriptReceived(uint guid, uint scriptId)
    {
        if (_scriptRunner is null) return;

        var camWorldPos = System.Numerics.Vector3.Zero;
        if (_cameraController is not null)
        {
            System.Numerics.Matrix4x4.Invert(_cameraController.Active.View, out var iv);
            camWorldPos = new System.Numerics.Vector3(iv.M41, iv.M42, iv.M43);
        }

        _scriptRunner.Play(scriptId, guid, camWorldPos);
    }

    /// <summary>
    /// Phase 5d — retail <c>AdminEnvirons</c> (0xEA60) dispatcher.
    /// Routes fog presets into the weather system's sticky override
    /// slot and logs the sound cues (Thunder1..6, Roar, Bell, etc)
    /// for now — actual sound playback needs a lookup table from
    /// <c>EnvironChangeType</c> → wave asset, which we don't yet
    /// have dat-indexed; follow-up will wire the thunder wave ids.
    /// </summary>
    private void OnEnvironChanged(uint environChangeType)
    {
        // Fog presets — values match AcDream.Core.World.EnvironOverride
        // byte-for-byte (we deliberately mirrored retail's enum).
        if (environChangeType <= 0x06u)
        {
            Weather.Override = (AcDream.Core.World.EnvironOverride)environChangeType;
            Console.WriteLine(
                $"live: AdminEnvirons fog override = " +
                $"{(AcDream.Core.World.EnvironOverride)environChangeType}");
            return;
        }

        // Sound cues 0x65..0x7B. Log by retail name for now; audio
        // binding is a separate follow-up (needs sound-table indexing
        // plus a PlaySound API on OpenAlAudioEngine that takes a
        // retail sound enum → wave-id mapping).
        string name = environChangeType switch
        {
            0x65u => "RoarSound",
            0x66u => "BellSound",
            0x67u => "Chant1Sound",
            0x68u => "Chant2Sound",
            0x69u => "DarkWhispers1Sound",
            0x6Au => "DarkWhispers2Sound",
            0x6Bu => "DarkLaughSound",
            0x6Cu => "DarkWindSound",
            0x6Du => "DarkSpeechSound",
            0x6Eu => "DrumsSound",
            0x6Fu => "GhostSpeakSound",
            0x70u => "BreathingSound",
            0x71u => "HowlSound",
            0x72u => "LostSoulsSound",
            0x75u => "SquealSound",
            0x76u => "Thunder1Sound",
            0x77u => "Thunder2Sound",
            0x78u => "Thunder3Sound",
            0x79u => "Thunder4Sound",
            0x7Au => "Thunder5Sound",
            0x7Bu => "Thunder6Sound",
            _     => $"Unknown(0x{environChangeType:X2})",
        };
        Console.WriteLine(
            $"live: AdminEnvirons sound cue = {name} " +
            $"(0x{environChangeType:X2}) — audio binding pending");
    }

    /// <summary>
    /// Phase A.1: streaming load delegate, runs on the worker thread.
    /// Reads the landblock from the dats, hydrates its stab entities (same
    /// path as the old preload), and returns a fully-populated LoadedLandblock.
    /// Thread-safe: uses only DatCollection reads (documented thread-safe by
    /// DatReaderWriter) and pure CPU work. No GL calls here.
    ///
    /// MVP scope: stabs only. Scenery + interior added in Task 8.
    /// </summary>
    private AcDream.Core.World.LoadedLandblock? BuildLandblockForStreaming(uint landblockId)
    {
        if (_dats is null) return null;

        // Phase A.1 hotfix: hold the dat lock for the entire load. The worker
        // thread mustn't read dats concurrently with the render thread's
        // ApplyLoadedTerrain / live-spawn handlers. Hold time is bounded by
        // the size of a single landblock's CPU-side build (tens of ms worst
        // case), which blocks the render thread for at most that duration.
        // This is the minimum correct behavior; a future pass can reduce
        // contention by pre-building render-thread work on the worker.
        lock (_datLock)
        {
            return BuildLandblockForStreamingLocked(landblockId);
        }
    }

    private AcDream.Core.World.LoadedLandblock? BuildLandblockForStreamingLocked(uint landblockId)
    {
        if (_dats is null) return null;

        var baseLoaded = AcDream.Core.World.LandblockLoader.Load(_dats, landblockId);
        if (baseLoaded is null) return null;

        int lbX = (int)((landblockId >> 24) & 0xFFu);
        int lbY = (int)((landblockId >> 16) & 0xFFu);
        var worldOffset = new System.Numerics.Vector3(
            (lbX - _liveCenterX) * 192f,
            (lbY - _liveCenterY) * 192f,
            0f);

        // Hydrate the stabs: same logic as the old OnLoad preload. Each stab
        // entity from LandblockLoader carries a SourceGfxObjOrSetupId that we
        // expand into per-part MeshRefs via SetupMesh.Flatten / GfxObjMesh.Build.
        // GPU upload (EnsureUploaded) happens on the render thread in
        // ApplyLoadedTerrain — NOT here.
        var hydrated = new List<AcDream.Core.World.WorldEntity>(baseLoaded.Entities.Count);
        foreach (var e in baseLoaded.Entities)
        {
            var meshRefs = new List<AcDream.Core.World.MeshRef>();

            if ((e.SourceGfxObjOrSetupId & 0xFF000000u) == 0x01000000u)
            {
                // Single GfxObj stab — identity part transform.
                var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(e.SourceGfxObjOrSetupId);
                if (gfx is not null)
                {
                    _physicsDataCache.CacheGfxObj(e.SourceGfxObjOrSetupId, gfx);
                    meshRefs.Add(new AcDream.Core.World.MeshRef(
                        e.SourceGfxObjOrSetupId, System.Numerics.Matrix4x4.Identity));
                }
            }
            else if ((e.SourceGfxObjOrSetupId & 0xFF000000u) == 0x02000000u)
            {
                // Multi-part Setup — flatten to per-part GfxObj refs.
                var setup = _dats.Get<DatReaderWriter.DBObjs.Setup>(e.SourceGfxObjOrSetupId);
                if (setup is not null)
                {
                    _physicsDataCache.CacheSetup(e.SourceGfxObjOrSetupId, setup);
                    var flat = AcDream.Core.Meshing.SetupMesh.Flatten(setup);
                    foreach (var mr in flat)
                    {
                        var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(mr.GfxObjId);
                        if (gfx is null) continue;
                        _physicsDataCache.CacheGfxObj(mr.GfxObjId, gfx);
                        meshRefs.Add(mr);
                    }
                }
            }

            if (meshRefs.Count == 0) continue;

            var entity = new AcDream.Core.World.WorldEntity
            {
                Id = e.Id,
                SourceGfxObjOrSetupId = e.SourceGfxObjOrSetupId,
                Position = e.Position + worldOffset,
                Rotation = e.Rotation,
                MeshRefs = meshRefs,
            };
            hydrated.Add(entity);
        }

        // Task 8: merge stabs + scenery + interior into one entity list.
        var merged = new List<AcDream.Core.World.WorldEntity>(hydrated);
        merged.AddRange(BuildSceneryEntitiesForStreaming(baseLoaded, lbX, lbY));
        merged.AddRange(BuildInteriorEntitiesForStreaming(landblockId, lbX, lbY));

        return new AcDream.Core.World.LoadedLandblock(
            baseLoaded.LandblockId,
            baseLoaded.Heightmap,
            merged);
    }

    /// <summary>
    /// Phase A.1 Task 8: generate scenery (trees, rocks, bushes) for a single
    /// landblock on the worker thread. Pure CPU — no GL calls.
    ///
    /// Ported from the pre-streaming preload loop in GameWindow.OnLoad
    /// (pre-Task-7 version, lines 329-405). Adapted to operate on a single
    /// LoadedLandblock instead of iterating worldView.Landblocks.
    /// </summary>
    private List<AcDream.Core.World.WorldEntity> BuildSceneryEntitiesForStreaming(
        AcDream.Core.World.LoadedLandblock lb, int lbX, int lbY)
    {
        var result = new List<AcDream.Core.World.WorldEntity>();
        if (_dats is null || _heightTable is null) return result;

        var region = _dats.Get<DatReaderWriter.DBObjs.Region>(0x13000000u);
        if (region is null) return result;

        // Build a set of terrain vertex indices that have buildings on them,
        // so the scenery generator can skip those cells (ACME conformance fix 4d).
        HashSet<int>? buildingCells = null;
        var lbInfo = _dats.Get<DatReaderWriter.DBObjs.LandBlockInfo>(
            (lb.LandblockId & 0xFFFF0000u) | 0xFFFEu);
        if (lbInfo is not null)
        {
            // Only Buildings suppress scenery. Stabs (LandBlockInfo.Objects) are
            // static scenery placeholders themselves (rocks, tree clusters) that
            // retail does NOT use to suppress scenery generation. Including them
            // here over-suppressed scenery in town landblocks.
            buildingCells = new HashSet<int>();
            foreach (var bldg in lbInfo.Buildings)
            {
                int cx = Math.Clamp((int)(bldg.Frame.Origin.X / 24f), 0, 8);
                int cy = Math.Clamp((int)(bldg.Frame.Origin.Y / 24f), 0, 8);
                buildingCells.Add(cx * 9 + cy);
            }
        }

        var spawns = AcDream.Core.World.SceneryGenerator.Generate(
            _dats, region, lb.Heightmap, lb.LandblockId, buildingCells, _heightTable);
        if (spawns.Count == 0) return result;

        var lbOffset = new System.Numerics.Vector3(
            (lbX - _liveCenterX) * 192f,
            (lbY - _liveCenterY) * 192f,
            0f);

        // Per-landblock id namespace. Landblock IDs are formatted 0xXXYYFFFF
        // where XX = landblock X coord (bits 24-31), YY = Y coord (bits 16-23).
        // Both must go into our ID so landblocks don't collide.
        // Format: 0x80 | XX | YY | local_index(8 bits) = 0x80XXYY_II.
        // 256 slots per landblock is enough (SceneryGenerator caps ~200).
        uint lbXByte = (lb.LandblockId >> 24) & 0xFFu;
        uint lbYByte = (lb.LandblockId >> 16) & 0xFFu;
        uint sceneryIdBase = 0x80000000u | (lbXByte << 16) | (lbYByte << 8);
        uint localIndex = 0;

        foreach (var spawn in spawns)
        {
            // Resolve the object to a mesh (same GfxObj/Setup logic as Stabs).
            // Scale is baked into the root transform by wrapping each part's
            // transform with a scale matrix.
            var meshRefs = new List<AcDream.Core.World.MeshRef>();
            var scaleMat = System.Numerics.Matrix4x4.CreateScale(spawn.Scale);

            if ((spawn.ObjectId & 0xFF000000u) == 0x01000000u)
            {
                var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(spawn.ObjectId);
                if (gfx is not null)
                {
                    _physicsDataCache.CacheGfxObj(spawn.ObjectId, gfx);
                    // Sub-meshes pre-built CPU-side; upload deferred to ApplyLoadedTerrain.
                    _ = AcDream.Core.Meshing.GfxObjMesh.Build(gfx, _dats);
                    meshRefs.Add(new AcDream.Core.World.MeshRef(spawn.ObjectId, scaleMat));
                }
            }
            else if ((spawn.ObjectId & 0xFF000000u) == 0x02000000u)
            {
                var setup = _dats.Get<DatReaderWriter.DBObjs.Setup>(spawn.ObjectId);
                if (setup is not null)
                {
                    _physicsDataCache.CacheSetup(spawn.ObjectId, setup);
                    var flat = AcDream.Core.Meshing.SetupMesh.Flatten(setup);
                    foreach (var mr in flat)
                    {
                        var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(mr.GfxObjId);
                        if (gfx is null) continue;
                        _physicsDataCache.CacheGfxObj(mr.GfxObjId, gfx);
                        _ = AcDream.Core.Meshing.GfxObjMesh.Build(gfx, _dats);
                        // Compose: part's own transform, then the spawn's scale.
                        meshRefs.Add(new AcDream.Core.World.MeshRef(mr.GfxObjId, mr.PartTransform * scaleMat));
                    }
                }
            }

            if (meshRefs.Count == 0) continue;

            // Sample terrain Z at (localX, localY) to lift scenery onto the
            // ground. Add BaseLoc.Z from the scenery ObjectDesc (passed in as
            // spawn.LocalPosition.Z) so meshes that specify a vertical offset
            // from the ground (e.g., flowers at -0.1m, roots below terrain)
            // settle properly.
            float localX = spawn.LocalPosition.X;
            float localY = spawn.LocalPosition.Y;
            // Prefer the physics engine's terrain sampler (TerrainSurface.SampleZ)
            // — it uses the same AC2D render split-direction formula the
            // TerrainChunkRenderer uses for the visible terrain mesh. This
            // guarantees trees are placed on the SAME Z height the player
            // walks on. If physics hasn't registered this landblock yet,
            // fall back to the local bilinear sample.
            var worldPx = localX + lbOffset.X;
            var worldPy = localY + lbOffset.Y;
            float groundZ = _physicsEngine.SampleTerrainZ(worldPx, worldPy)
                ?? SampleTerrainZ(lb.Heightmap, _heightTable, localX, localY);
            float finalZ = groundZ + spawn.LocalPosition.Z;

            var hydrated = new AcDream.Core.World.WorldEntity
            {
                Id = sceneryIdBase + localIndex++,
                SourceGfxObjOrSetupId = spawn.ObjectId,
                Position = new System.Numerics.Vector3(localX, localY, finalZ) + lbOffset,
                Rotation = spawn.Rotation,
                MeshRefs = meshRefs,
                Scale = spawn.Scale,
            };
            result.Add(hydrated);
        }

        return result;
    }

    /// <summary>
    /// Phase A.1 Task 8: walk a landblock's EnvCells and produce (a) the cell
    /// room-mesh entity (Phase 7.1) for each EnvCell with an EnvironmentId, and
    /// (b) a WorldEntity per StaticObject in each cell. Pure CPU — no GL calls.
    ///
    /// Cell sub-meshes are stored in _pendingCellMeshes (ConcurrentDictionary)
    /// so ApplyLoadedTerrain can drain + upload them on the render thread.
    ///
    /// Ported from pre-streaming preload lines 407-565.
    /// </summary>
    private List<AcDream.Core.World.WorldEntity> BuildInteriorEntitiesForStreaming(
        uint landblockId, int lbX, int lbY)
    {
        var result = new List<AcDream.Core.World.WorldEntity>();
        if (_dats is null) return result;

        var lbInfo = _dats.Get<DatReaderWriter.DBObjs.LandBlockInfo>((landblockId & 0xFFFF0000u) | 0xFFFEu);
        if (lbInfo is null || lbInfo.NumCells == 0) return result;

        var lbOffset = new System.Numerics.Vector3(
            (lbX - _liveCenterX) * 192f,
            (lbY - _liveCenterY) * 192f,
            0f);

        // Per-landblock id namespace: 0x40000000 | (lbId & 0x00FFFF00) | local_counter.
        // Distinct from scenery (0x80000000+) and stabs (ids from LandblockLoader).
        uint interiorIdBase = 0x40000000u | (landblockId & 0x00FFFF00u);
        uint localCounter = 0;

        uint firstCellId = (landblockId & 0xFFFF0000u) | 0x0100u;
        for (uint offset = 0; offset < lbInfo.NumCells; offset++)
        {
            uint envCellId = firstCellId + offset;
            var envCell = _dats.Get<DatReaderWriter.DBObjs.EnvCell>(envCellId);
            if (envCell is null) continue;

            // Phase 7.1: build and register room geometry for this EnvCell.
            DatReaderWriter.Types.CellStruct? cellStruct = null;
            if (envCell.EnvironmentId != 0)
            {
                var environment = _dats.Get<DatReaderWriter.DBObjs.Environment>(0x0D000000u | envCell.EnvironmentId);
                if (environment is not null
                    && environment.Cells.TryGetValue(envCell.CellStructure, out cellStruct))
                {
                    var cellSubMeshes = AcDream.Core.Meshing.CellMesh.Build(envCell, cellStruct, _dats);
                    if (cellSubMeshes.Count > 0)
                    {
                        _pendingCellMeshes[envCellId] = cellSubMeshes;

                        var cellOrigin = envCell.Position.Origin + lbOffset
                            + new System.Numerics.Vector3(0f, 0f, 0.02f);
                        var cellTransform =
                            System.Numerics.Matrix4x4.CreateFromQuaternion(envCell.Position.Orientation) *
                            System.Numerics.Matrix4x4.CreateTranslation(cellOrigin);

                        var cellMeshRef = new AcDream.Core.World.MeshRef(envCellId, cellTransform);

                        var cellEntity = new AcDream.Core.World.WorldEntity
                        {
                            Id = interiorIdBase + localCounter++,
                            SourceGfxObjOrSetupId = envCellId,
                            Position = System.Numerics.Vector3.Zero,
                            Rotation = System.Numerics.Quaternion.Identity,
                            MeshRefs = new[] { cellMeshRef },
                            ParentCellId = envCellId,
                        };
                        result.Add(cellEntity);

                        // Step 4: build LoadedCell for portal visibility.
                        BuildLoadedCell(envCellId, envCell, cellStruct, cellOrigin, cellTransform);

                        // Cache CellStruct physics BSP for indoor collision.
                        _physicsDataCache.CacheCellStruct(envCellId, cellStruct, cellTransform);
                    }
                }
            }

            // Phase 2d: static objects inside the EnvCell.
            foreach (var stab in envCell.StaticObjects)
            {
                var meshRefs = new List<AcDream.Core.World.MeshRef>();
                if ((stab.Id & 0xFF000000u) == 0x01000000u)
                {
                    var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(stab.Id);
                    if (gfx is not null)
                    {
                        _physicsDataCache.CacheGfxObj(stab.Id, gfx);
                        _ = AcDream.Core.Meshing.GfxObjMesh.Build(gfx, _dats);
                        meshRefs.Add(new AcDream.Core.World.MeshRef(stab.Id, System.Numerics.Matrix4x4.Identity));
                    }
                }
                else if ((stab.Id & 0xFF000000u) == 0x02000000u)
                {
                    var setup = _dats.Get<DatReaderWriter.DBObjs.Setup>(stab.Id);
                    if (setup is not null)
                    {
                        _physicsDataCache.CacheSetup(stab.Id, setup);
                        var flat = AcDream.Core.Meshing.SetupMesh.Flatten(setup);
                        foreach (var mr in flat)
                        {
                            var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(mr.GfxObjId);
                            if (gfx is null) continue;
                            _physicsDataCache.CacheGfxObj(mr.GfxObjId, gfx);
                            _ = AcDream.Core.Meshing.GfxObjMesh.Build(gfx, _dats);
                            meshRefs.Add(mr);
                        }
                    }
                }

                if (meshRefs.Count == 0) continue;

                // Stabs inside EnvCells are already in landblock-local coordinates
                // (same space as LandBlockInfo.Objects stabs). Adding cellOrigin would
                // be wrong — see Phase 2d comment in the pre-streaming preload.
                var worldPos = stab.Frame.Origin + lbOffset;
                var worldRot = stab.Frame.Orientation;

                var hydrated = new AcDream.Core.World.WorldEntity
                {
                    Id = interiorIdBase + localCounter++,
                    SourceGfxObjOrSetupId = stab.Id,
                    Position = worldPos,
                    Rotation = worldRot,
                    MeshRefs = meshRefs,
                    ParentCellId = envCellId,
                };
                result.Add(hydrated);
            }
        }

        return result;
    }

    /// <summary>
    /// Phase A.1: render-thread callback from StreamingController.Tick
    /// whenever a new landblock's terrain + entities are ready for GPU upload.
    /// Mirrors the terrain-build + entity-upload part of the old preload.
    /// Must only be called from the render thread.
    /// </summary>
    private void ApplyLoadedTerrain(AcDream.Core.World.LoadedLandblock lb)
    {
        if (_terrain is null || _dats is null || _blendCtx is null
            || _heightTable is null || _surfaceCache is null) return;

        // Phase A.1 hotfix: render-thread path also takes the dat lock so it
        // doesn't race with BuildLandblockForStreaming on the worker thread.
        // Hold the lock across the entire apply because we read dats below
        // (GfxObj sub-mesh builds) and mutate the shared _surfaceCache from
        // LandblockMesh.Build.
        lock (_datLock)
        {
            ApplyLoadedTerrainLocked(lb);
        }
    }

    /// <summary>
    /// Step 4: build a <see cref="LoadedCell"/> for portal visibility and queue it
    /// for render-thread registration. Called from the worker thread during
    /// <see cref="BuildInteriorEntitiesForStreaming"/>.
    /// </summary>
    private void BuildLoadedCell(
        uint envCellId,
        DatReaderWriter.DBObjs.EnvCell envCell,
        DatReaderWriter.Types.CellStruct cellStruct,
        System.Numerics.Vector3 cellOrigin,
        System.Numerics.Matrix4x4 cellTransform)
    {
        System.Numerics.Matrix4x4.Invert(cellTransform, out var inverse);

        // Compute local AABB from CellStruct vertices.
        var boundsMin = new System.Numerics.Vector3(float.MaxValue);
        var boundsMax = new System.Numerics.Vector3(float.MinValue);
        foreach (var kvp in cellStruct.VertexArray.Vertices)
        {
            var v = kvp.Value;
            var pos = new System.Numerics.Vector3(v.Origin.X, v.Origin.Y, v.Origin.Z);
            boundsMin = System.Numerics.Vector3.Min(boundsMin, pos);
            boundsMax = System.Numerics.Vector3.Max(boundsMax, pos);
        }
        if (boundsMin.X == float.MaxValue)
        {
            boundsMin = System.Numerics.Vector3.Zero;
            boundsMax = System.Numerics.Vector3.Zero;
        }

        // Build portal list and clip planes from CellPortals.
        var portals = new List<CellPortalInfo>();
        var clipPlanes = new List<PortalClipPlane>();

        // Compute cell centroid in local space for InsideSide determination.
        var centroid = (boundsMin + boundsMax) * 0.5f;

        foreach (var portal in envCell.CellPortals)
        {
            portals.Add(new CellPortalInfo(
                portal.OtherCellId,
                portal.PolygonId,
                (ushort)portal.Flags));

            // Build clip plane from the portal polygon.
            if (cellStruct.Polygons.TryGetValue(portal.PolygonId, out var poly)
                && poly.VertexIds.Count >= 3)
            {
                // Get first 3 vertices in local space for the plane.
                System.Numerics.Vector3 p0 = System.Numerics.Vector3.Zero,
                                        p1 = System.Numerics.Vector3.Zero,
                                        p2 = System.Numerics.Vector3.Zero;
                bool found = true;
                if (cellStruct.VertexArray.Vertices.TryGetValue((ushort)poly.VertexIds[0], out var v0))
                    p0 = new System.Numerics.Vector3(v0.Origin.X, v0.Origin.Y, v0.Origin.Z);
                else found = false;
                if (found && cellStruct.VertexArray.Vertices.TryGetValue((ushort)poly.VertexIds[1], out var v1))
                    p1 = new System.Numerics.Vector3(v1.Origin.X, v1.Origin.Y, v1.Origin.Z);
                else found = false;
                if (found && cellStruct.VertexArray.Vertices.TryGetValue((ushort)poly.VertexIds[2], out var v2))
                    p2 = new System.Numerics.Vector3(v2.Origin.X, v2.Origin.Y, v2.Origin.Z);
                else found = false;

                if (found)
                {
                    var normal = System.Numerics.Vector3.Normalize(
                        System.Numerics.Vector3.Cross(p1 - p0, p2 - p0));
                    float d = -System.Numerics.Vector3.Dot(normal, p0);

                    // Determine InsideSide: which side of the plane the cell centroid is on.
                    // If centroid dot > 0 → inside is positive half-space (InsideSide=0).
                    float centroidDot = System.Numerics.Vector3.Dot(normal, centroid) + d;
                    int insideSide = centroidDot >= 0 ? 0 : 1;

                    clipPlanes.Add(new PortalClipPlane
                    {
                        Normal = normal,
                        D = d,
                        InsideSide = insideSide,
                    });
                }
                else
                {
                    clipPlanes.Add(default);
                }
            }
            else
            {
                clipPlanes.Add(default);
            }
        }

        var loaded = new LoadedCell
        {
            CellId = envCellId,
            WorldPosition = cellOrigin,
            WorldTransform = cellTransform,
            InverseWorldTransform = inverse,
            LocalBoundsMin = boundsMin,
            LocalBoundsMax = boundsMax,
            Portals = portals,
            ClipPlanes = clipPlanes,
        };
        _pendingCells.Add(loaded);
    }

    private void ApplyLoadedTerrainLocked(AcDream.Core.World.LoadedLandblock lb)
    {
        if (_terrain is null || _dats is null || _blendCtx is null
            || _heightTable is null || _surfaceCache is null) return;

        uint lbXu = (lb.LandblockId >> 24) & 0xFFu;
        uint lbYu = (lb.LandblockId >> 16) & 0xFFu;
        int lbX = (int)lbXu;
        int lbY = (int)lbYu;
        var origin = new System.Numerics.Vector3(
            (lbX - _liveCenterX) * 192f,
            (lbY - _liveCenterY) * 192f,
            0f);

        // Build terrain mesh data on the render thread (pure CPU; acceptable
        // for the MVP; a future pass can move it to the worker thread).
        var meshData = AcDream.Core.Terrain.LandblockMesh.Build(
            lb.Heightmap, lbXu, lbYu, _heightTable, _blendCtx, _surfaceCache);
        _terrain.AddLandblock(lb.LandblockId, meshData, origin);

        // Step 4: drain pending LoadedCells from the worker thread.
        while (_pendingCells.TryTake(out var cell))
            _cellVisibility.AddCell(cell);

        // Compute the per-landblock AABB for frustum culling. XY from the
        // landblock's world origin + 192 footprint. Z from the terrain vertex
        // range padded +50 above (for trees/buildings) and -10 below (for
        // basements). TerrainRenderer already scans vertices internally; we
        // replicate here so GpuWorldState has the same bounds for the static
        // mesh renderer's culling pass.
        {
            float zMin = float.MaxValue, zMax = float.MinValue;
            foreach (var v in meshData.Vertices)
            {
                float z = v.Position.Z;
                if (z < zMin) zMin = z;
                if (z > zMax) zMax = z;
            }
            if (zMin == float.MaxValue) { zMin = 0f; zMax = 0f; }
            zMax += 50f;   // generous pad for trees and buildings
            zMin -= 10f;   // below-ground buffer for basements/cellars
            var aabbMin = new System.Numerics.Vector3(origin.X, origin.Y, zMin);
            var aabbMax = new System.Numerics.Vector3(origin.X + 192f, origin.Y + 192f, zMax);
            _worldState.SetLandblockAabb(lb.LandblockId, aabbMin, aabbMax);
        }

        // Phase B.3: populate the physics engine with terrain + indoor cell
        // surfaces for this landblock. Runs under _datLock (same lock as the
        // rest of ApplyLoadedTerrainLocked) so dat reads are safe.
        {
            uint lbPhysX = (lb.LandblockId >> 24) & 0xFFu;
            uint lbPhysY = (lb.LandblockId >> 16) & 0xFFu;
            // Extract per-vertex terrain-type bytes so TerrainSurface can
            // classify water cells for ValidateWalkable's water-depth
            // adjustment. Each TerrainInfo is a ushort with Type in bits
            // 2-6; taking the low byte preserves those bits (+ Road in 0-1,
            // which the classifier masks off).
            var terrainBytes = new byte[81];
            for (int i = 0; i < 81; i++)
                terrainBytes[i] = (byte)(ushort)lb.Heightmap.Terrain[i];

            var terrainSurface = new AcDream.Core.Physics.TerrainSurface(
                lb.Heightmap.Height, _heightTable, lbPhysX, lbPhysY, terrainBytes);

            var cellSurfaces = new List<AcDream.Core.Physics.CellSurface>();
            var portalPlanes = new List<AcDream.Core.Physics.PortalPlane>();
            var lbInfo = _dats.Get<DatReaderWriter.DBObjs.LandBlockInfo>(
                (lb.LandblockId & 0xFFFF0000u) | 0xFFFEu);
            if (lbInfo is not null && lbInfo.NumCells > 0)
            {
                uint firstCellId = (lb.LandblockId & 0xFFFF0000u) | 0x0100u;
                for (uint offset = 0; offset < lbInfo.NumCells; offset++)
                {
                    uint envCellId = firstCellId + offset;
                    var envCell = _dats.Get<DatReaderWriter.DBObjs.EnvCell>(envCellId);
                    if (envCell is null) continue;
                    if (envCell.EnvironmentId == 0) continue;

                    var environment = _dats.Get<DatReaderWriter.DBObjs.Environment>(
                        0x0D000000u | envCell.EnvironmentId);
                    if (environment is null) continue;
                    if (!environment.Cells.TryGetValue(envCell.CellStructure, out var cellStruct)) continue;

                    // Transform CellStruct vertices from cell-local to world space.
                    var rot = envCell.Position.Orientation;
                    var cellOriginWorld = envCell.Position.Origin + origin;
                    var worldVerts = new Dictionary<ushort, System.Numerics.Vector3>(
                        cellStruct.VertexArray.Vertices.Count);
                    foreach (var (vid, vtx) in cellStruct.VertexArray.Vertices)
                    {
                        var localPos = vtx.Origin;
                        var worldPos = System.Numerics.Vector3.Transform(localPos, rot) + cellOriginWorld;
                        worldVerts[(ushort)vid] = worldPos;
                    }

                    // Extract polygon vertex-id lists from PhysicsPolygons.
                    // PhysicsPolygons is Dictionary<ushort, Polygon>; iterate Values.
                    var polyVids = new List<List<short>>(cellStruct.PhysicsPolygons.Count);
                    foreach (var poly in cellStruct.PhysicsPolygons.Values)
                    {
                        var vids = new List<short>(poly.VertexIds.Count);
                        foreach (var vid in poly.VertexIds)
                            vids.Add(vid);
                        polyVids.Add(vids);
                    }

                    cellSurfaces.Add(new AcDream.Core.Physics.CellSurface(envCellId, worldVerts, polyVids));

                    // Extract portal planes from this EnvCell's CellPortals.
                    // CellPortal.PolygonId indexes cellStruct.Polygons (rendering polygons),
                    // NOT PhysicsPolygons — confirmed by ACViewer EnvCell.find_transit_cells.
                    foreach (var portal in envCell.CellPortals)
                    {
                        if (!cellStruct.Polygons.TryGetValue(portal.PolygonId, out var poly))
                            continue;
                        if (poly.VertexIds.Count < 3)
                            continue;

                        // Collect ALL polygon vertices for accurate centroid + radius.
                        var portalVerts = new System.Numerics.Vector3[poly.VertexIds.Count];
                        bool allFound = true;
                        for (int pv = 0; pv < poly.VertexIds.Count; pv++)
                        {
                            if (!worldVerts.TryGetValue((ushort)poly.VertexIds[pv], out portalVerts[pv]))
                            { allFound = false; break; }
                        }
                        if (!allFound) continue;

                        portalPlanes.Add(AcDream.Core.Physics.PortalPlane.FromVertices(
                            portalVerts.AsSpan(),
                            portal.OtherCellId,          // target cell (0xFFFF = outdoor)
                            envCellId & 0xFFFFu,         // owner cell (low 16 bits)
                            (ushort)portal.Flags));
                    }
                }
            }

            _physicsEngine.AddLandblock(lb.LandblockId, terrainSurface, cellSurfaces,
                portalPlanes, origin.X, origin.Y);
        }

        // Upload every GfxObj referenced by this landblock's entities.
        // EnsureUploaded is idempotent so duplicates across landblocks are free.
        if (_staticMesh is not null)
        {
            // Task 8: drain any pending EnvCell room-mesh sub-meshes first.
            // The worker thread pre-built these CPU-side and stored them in
            // _pendingCellMeshes. We must upload them here (render thread) before
            // the per-MeshRef loop below tries to look them up via GfxObjMesh.Build,
            // which would fail because EnvCell ids (0xAAAA01xx) aren't real GfxObj
            // dat ids. EnsureUploaded is idempotent so calling it here then seeing
            // the same id again in the loop below is safe.
            foreach (var entity in lb.Entities)
            {
                foreach (var meshRef in entity.MeshRefs)
                {
                    if (_pendingCellMeshes.TryRemove(meshRef.GfxObjId, out var cellSubMeshes))
                        _staticMesh.EnsureUploaded(meshRef.GfxObjId, cellSubMeshes);
                }
            }

            // Now upload regular GfxObj sub-meshes (stabs, scenery, interior stabs).
            // Skip any ids already uploaded (includes the cell meshes just drained).
            foreach (var entity in lb.Entities)
            {
                foreach (var meshRef in entity.MeshRefs)
                {
                    // Skip EnvCell synthetic ids — already handled above (or already
                    // uploaded on a prior tick). GfxObj ids are 0x01xxxxxx; Setup ids
                    // are 0x02xxxxxx; anything else is not a GfxObj dat record.
                    if ((meshRef.GfxObjId & 0xFF000000u) != 0x01000000u) continue;
                    var gfx = _dats.Get<DatReaderWriter.DBObjs.GfxObj>(meshRef.GfxObjId);
                    if (gfx is null) continue;
                    _physicsDataCache.CacheGfxObj(meshRef.GfxObjId, gfx);
                    var subMeshes = AcDream.Core.Meshing.GfxObjMesh.Build(gfx, _dats);
                    _staticMesh.EnsureUploaded(meshRef.GfxObjId, subMeshes);
                }
            }
        }

        // Task 7: register static entities into the ShadowObjectRegistry so the
        // Transition system can find and collide against them during movement.
        // Only entities backed by a GfxObj with a physics BSP are registered —
        // entities with no BSP (pure visual, no physics) are skipped.
        //
        // Radius source priority:
        //   1. GfxObj: use the BSP root bounding sphere radius if available.
        //   2. Setup: use Setup.Radius (the capsule radius) if available.
        //   3. Fallback: 1.0m (conservative default for trees / small objects).
        int lbBspCount = 0, lbCylCount = 0, lbNoneCount = 0;
        int scTried = 0, scHaveBounds = 0, scRegistered = 0, scTooThin = 0, scNoBounds = 0;
        foreach (var entity in lb.Entities)
        {
            // Phase G.2: if the entity's Setup has baked-in LightInfos,
            // register them with the LightManager so torches, braziers,
            // and lifestones cast real light on nearby geometry. Hooked
            // via the LightingHookSink so per-entity owner tracking +
            // SetLightHook IsLit toggles all go through one codepath.
            // Only applies to Setup-sourced entities (0x02xxxxxx) — raw
            // GfxObjs don't carry Lights dictionaries.
            if (_lightingSink is not null && _dats is not null)
            {
                uint src = entity.SourceGfxObjOrSetupId;
                if ((src & 0xFF000000u) == 0x02000000u)
                {
                    var datSetup = _dats.Get<DatReaderWriter.DBObjs.Setup>(src);
                    if (datSetup is not null && datSetup.Lights.Count > 0)
                    {
                        var loaded = AcDream.Core.Lighting.LightInfoLoader.Load(
                            datSetup,
                            ownerId: entity.Id,
                            entityPosition: entity.Position,
                            entityRotation: entity.Rotation);
                        foreach (var ls in loaded)
                            _lightingSink.RegisterOwnedLight(ls);
                    }
                }
            }

            int entityBsp = 0, entityCyl = 0;
            // Treat both procedural scenery (0x80000000+) AND LandBlockInfo
            // stabs (IDs < 0x40000000 with 0x01/0x02 source) as outdoor-entities
            // that should use visual-mesh-AABB collision. Stabs include landscape
            // trees placed by Turbine (not procedural scenery) that otherwise
            // have no collision shape registered.
            uint _srcPrefix = entity.SourceGfxObjOrSetupId & 0xFF000000u;
            bool _isOutdoorMesh = ((entity.Id & 0x80000000u) != 0)  // scenery
                || ((entity.Id < 0x40000000u)                        // stab
                    && (_srcPrefix == 0x01000000u || _srcPrefix == 0x02000000u));
            bool _isScenery = _isOutdoorMesh;
            if (_isScenery) scTried++;
            // Register EACH physics-enabled part so multi-part Setups
            // (buildings, trees) have all their collision geometry registered.
            // Each part gets its own ShadowEntry with its world-space transform.
            var entityRoot =
                System.Numerics.Matrix4x4.CreateFromQuaternion(entity.Rotation) *
                System.Numerics.Matrix4x4.CreateTranslation(entity.Position);

            uint partIndex = 0;
            foreach (var meshRef in entity.MeshRefs)
            {
                var partCached = _physicsDataCache.GetGfxObj(meshRef.GfxObjId);
                if (partCached?.BSP?.Root is null) { partIndex++; continue; }

                // Compute the part's world-space position from its transform.
                var partWorld = meshRef.PartTransform * entityRoot;

                // Decompose to extract scale (scenery objects have it baked
                // into PartTransform), rotation, and translation.
                System.Numerics.Vector3 partScale3;
                System.Numerics.Quaternion partRot;
                System.Numerics.Vector3 partPos;
                if (System.Numerics.Matrix4x4.Decompose(partWorld,
                    out partScale3, out partRot, out partPos))
                { /* decompose succeeded */ }
                else
                {
                    partScale3 = System.Numerics.Vector3.One;
                    partRot = entity.Rotation;
                    partPos = new System.Numerics.Vector3(partWorld.M41, partWorld.M42, partWorld.M43);
                }

                // Use uniform scale (X component) — AC objects are uniformly scaled.
                float partScale = partScale3.X;
                if (partScale <= 0f) partScale = 1f;

                // Local bounding sphere radius × world scale = world-space radius
                // for the broad phase. The BSPQuery will also use `partScale` to
                // transform player spheres into the unscaled BSP coordinate space.
                float localRadius = partCached.BoundingSphere?.Radius ?? 1f;
                float worldRadius = localRadius * partScale;

                // Use a unique sub-ID per part: entity.Id * 256 + partIndex.
                uint partId = entity.Id * 256u + partIndex;
                _physicsEngine.ShadowObjects.Register(
                    partId, meshRef.GfxObjId,
                    partPos, partRot, worldRadius,
                    origin.X, origin.Y, lb.LandblockId,
                    AcDream.Core.Physics.ShadowCollisionType.BSP, 0f,
                    partScale);

                entityBsp++;
                partIndex++;
            }

            // Register collision shapes from the Setup (if this entity has one).
            // Retail uses CylSpheres for trunks/pillars, Spheres for blob-shaped
            // collision volumes. We register both as "cylinder" shadow entries
            // because our collision system only has BSP and Cylinder types; a
            // Sphere is handled as a short cylinder.
            //
            // SCALE + ROTATION handling:
            // - Radius, Height, and the local Origin offset are ALL scaled by
            //   entity.Scale so they match the visually-scaled mesh.
            // - The Origin offset is ROTATED by entity.Rotation so rotated
            //   scenery has its collision cylinder in the correct world spot.
            //
            // Keying:
            //   entity.Id                  → the primary CylSphere (if any)
            //   entity.Id + K*0x10000000u  → additional CylSpheres/Spheres
            // This ensures uniqueness per shape so ShadowObjectRegistry doesn't
            // clobber entries via Deregister.
            {
                var setup = _physicsDataCache.GetSetup(entity.SourceGfxObjOrSetupId);
                if (setup is not null)
                {
                    float entScale = entity.Scale > 0f ? entity.Scale : 1f;
                    uint shapeIndex = 0;

                    // Register every CylSphere the Setup defines.
                    for (int ci = 0; ci < setup.CylSpheres.Count; ci++)
                    {
                        var cyl = setup.CylSpheres[ci];
                        float cylRadius = cyl.Radius * entScale;
                        float baseHeight = cyl.Height > 0 ? cyl.Height : cyl.Radius * 4f;
                        float cylHeight = baseHeight * entScale;
                        if (cylRadius <= 0f) continue;

                        // Rotate the local origin offset by entity rotation,
                        // then scale it before adding to entity.Position.
                        var localOffset = new System.Numerics.Vector3(
                            cyl.Origin.X, cyl.Origin.Y, cyl.Origin.Z) * entScale;
                        var worldOffset = System.Numerics.Vector3.Transform(localOffset, entity.Rotation);

                        uint shapeId = entity.Id + (shapeIndex++) * 0x10000000u;
                        _physicsEngine.ShadowObjects.Register(
                            shapeId, entity.SourceGfxObjOrSetupId,
                            entity.Position + worldOffset,
                            entity.Rotation, cylRadius,
                            origin.X, origin.Y, lb.LandblockId,
                            AcDream.Core.Physics.ShadowCollisionType.Cylinder, cylHeight);
                        entityCyl++;
                    }

                    // Register every Sphere as a short cylinder when no
                    // CylSphere claimed the object.
                    if (setup.CylSpheres.Count == 0)
                    {
                        for (int si = 0; si < setup.Spheres.Count; si++)
                        {
                            var sph = setup.Spheres[si];
                            if (sph.Radius <= 0f) continue;

                            float sphRadius = sph.Radius * entScale;
                            float sphHeight = sphRadius * 2f;

                            // Rotate + scale the local origin, then offset the
                            // cylinder base down by the scaled radius so the
                            // short cylinder is centered on the sphere.
                            var localOffset = new System.Numerics.Vector3(
                                sph.Origin.X, sph.Origin.Y, sph.Origin.Z) * entScale;
                            var worldOffset = System.Numerics.Vector3.Transform(localOffset, entity.Rotation);
                            worldOffset.Z -= sphRadius;

                            uint shapeId = entity.Id + (shapeIndex++) * 0x10000000u;
                            _physicsEngine.ShadowObjects.Register(
                                shapeId, entity.SourceGfxObjOrSetupId,
                                entity.Position + worldOffset,
                                entity.Rotation, sphRadius,
                                origin.X, origin.Y, lb.LandblockId,
                                AcDream.Core.Physics.ShadowCollisionType.Cylinder, sphHeight);
                            entityCyl++;
                        }
                    }

                    // Setup.Radius fallback: the Setup has NO CylSpheres and NO
                    // Spheres but has a positive Radius/Height. Use the overall
                    // bounding cylinder scaled by entity.Scale.
                    if (setup.CylSpheres.Count == 0 && setup.Spheres.Count == 0
                        && setup.Radius > 0f && entityBsp == 0)
                    {
                        float fr = setup.Radius * entScale;
                        float fh = (setup.Height > 0 ? setup.Height : setup.Radius * 2f) * entScale;
                        uint shapeId = entity.Id + (shapeIndex++) * 0x10000000u;
                        _physicsEngine.ShadowObjects.Register(
                            shapeId, entity.SourceGfxObjOrSetupId,
                            entity.Position, entity.Rotation, fr,
                            origin.X, origin.Y, lb.LandblockId,
                            AcDream.Core.Physics.ShadowCollisionType.Cylinder, fh);
                        entityCyl++;
                    }
                }
            }

            // VISUAL mesh-bounds collision: for SCENERY entities (IDs with
            // 0x80000000 bit set, indicating procedurally-placed scenery),
            // ALWAYS compute a cylinder from the world-space mesh AABB.
            // This catches trees whose BSP is only on the canopy (player
            // walks under) AND corrects CylSphere positioning issues caused
            // by mesh files having vertices offset from the mesh origin.
            //
            // For stabs (low IDs) and live entities, keep the existing Setup
            // CylSphere / BSP registrations — those are placed with precise
            // frame data and don't have the scenery offset issue.
            if ((_isOutdoorMesh || (entityBsp == 0 && entityCyl == 0)) && entity.MeshRefs.Count > 0)
            {
                float entScale = entity.Scale > 0f ? entity.Scale : 1f;
                bool haveBounds = false;
                var worldMin = new System.Numerics.Vector3(float.MaxValue);
                var worldMax = new System.Numerics.Vector3(float.MinValue);

                var entRoot =
                    System.Numerics.Matrix4x4.CreateFromQuaternion(entity.Rotation) *
                    System.Numerics.Matrix4x4.CreateTranslation(entity.Position);

                // First pass: compute overall vertical extent in world Z.
                float overallMinZ = float.MaxValue;
                float overallMaxZ = float.MinValue;
                foreach (var mr in entity.MeshRefs)
                {
                    var vb = _physicsDataCache.GetVisualBounds(mr.GfxObjId);
                    if (vb is null || vb.Radius <= 0f) continue;
                    var partWorld = mr.PartTransform * entRoot;
                    for (int bi = 0; bi < 8; bi++)
                    {
                        var corner = new System.Numerics.Vector3(
                            (bi & 1) != 0 ? vb.Max.X : vb.Min.X,
                            (bi & 2) != 0 ? vb.Max.Y : vb.Min.Y,
                            (bi & 4) != 0 ? vb.Max.Z : vb.Min.Z);
                        var w = System.Numerics.Vector3.Transform(corner, partWorld);
                        if (w.Z < overallMinZ) overallMinZ = w.Z;
                        if (w.Z > overallMaxZ) overallMaxZ = w.Z;
                    }
                }

                // Second pass: use TRUNK HEIGHT ONLY (bottom 25% of the mesh
                // or first 2.5m, whichever is smaller) for horizontal radius.
                // This gives us the trunk thickness — not the canopy spread.
                // The Z extent still uses the full mesh (so tall trees have
                // tall collision cylinders).
                float trunkHeight = MathF.Min(2.5f, (overallMaxZ - overallMinZ) * 0.25f);
                if (trunkHeight < 0.5f) trunkHeight = 0.5f;
                float trunkTopZ = overallMinZ + trunkHeight;

                foreach (var mr in entity.MeshRefs)
                {
                    var vb = _physicsDataCache.GetVisualBounds(mr.GfxObjId);
                    if (vb is null || vb.Radius <= 0f) continue;

                    var partWorld = mr.PartTransform * entRoot;
                    // Only accumulate horizontal extents from corners within the
                    // trunk height range. Pass the full vertical extent through.
                    for (int bi = 0; bi < 8; bi++)
                    {
                        var corner = new System.Numerics.Vector3(
                            (bi & 1) != 0 ? vb.Max.X : vb.Min.X,
                            (bi & 2) != 0 ? vb.Max.Y : vb.Min.Y,
                            (bi & 4) != 0 ? vb.Max.Z : vb.Min.Z);
                        var w = System.Numerics.Vector3.Transform(corner, partWorld);

                        // Always track vertical extent
                        if (w.Z < worldMin.Z) worldMin.Z = w.Z;
                        if (w.Z > worldMax.Z) worldMax.Z = w.Z;

                        // Only track horizontal extent for TRUNK-level vertices
                        if (w.Z <= trunkTopZ)
                        {
                            if (w.X < worldMin.X) worldMin.X = w.X;
                            if (w.Y < worldMin.Y) worldMin.Y = w.Y;
                            if (w.X > worldMax.X) worldMax.X = w.X;
                            if (w.Y > worldMax.Y) worldMax.Y = w.Y;
                            haveBounds = true;
                        }
                    }
                }

                if (haveBounds)
                {
                    if (_isScenery) scHaveBounds++;

                    // RADIUS: prefer the Setup's CylSphere radius (the retail
                    // trunk radius — thin, matches tree trunks). Fall back to
                    // Setup.Radius or mesh AABB if CylSphere is unavailable.
                    // Always scale by entity.Scale.
                    float entScaleLocal = entity.Scale > 0f ? entity.Scale : 1f;
                    float cylRadius = -1f;
                    float cylHeight;

                    var setupInfo = _physicsDataCache.GetSetup(entity.SourceGfxObjOrSetupId);
                    if (setupInfo is not null)
                    {
                        if (setupInfo.CylSpheres.Count > 0 && setupInfo.CylSpheres[0].Radius > 0f)
                        {
                            // Retail CylSphere — the definitive trunk collision.
                            cylRadius = setupInfo.CylSpheres[0].Radius * entScaleLocal;
                        }
                        else if (setupInfo.Radius > 0f)
                        {
                            // Setup.Radius — the overall bounding radius. For
                            // thin trunks this might be the full tree radius
                            // (canopy included) but often it's the trunk.
                            cylRadius = setupInfo.Radius * entScaleLocal;
                        }
                    }

                    // Fall back to mesh AABB trunk-level radius if no Setup data.
                    if (cylRadius < 0f)
                    {
                        float halfX = (worldMax.X - worldMin.X) * 0.5f;
                        float halfY = (worldMax.Y - worldMin.Y) * 0.5f;
                        cylRadius = MathF.Max(halfX, halfY);
                    }

                    // Clamp: retail AC trunks are 0.3-1.0m. Bigger radii (from
                    // the AABB fallback for canopy-heavy meshes) are clearly
                    // wrong; clamp to a reasonable tree-trunk maximum.
                    if (cylRadius < 0.3f) cylRadius = 0.3f;
                    if (cylRadius > 1.5f) cylRadius = 1.5f;

                    // HEIGHT: use Setup.Height scaled, or mesh AABB vertical extent.
                    if (setupInfo is not null && setupInfo.Height > 0f)
                        cylHeight = setupInfo.Height * entScaleLocal;
                    else
                        cylHeight = MathF.Max(worldMax.Z - entity.Position.Z, cylRadius);

                    // CENTER: entity.Position (the rendered root).
                    var baseCenter = new System.Numerics.Vector3(
                        entity.Position.X, entity.Position.Y, entity.Position.Z);

                    _physicsEngine.ShadowObjects.Register(
                        entity.Id,
                        entity.SourceGfxObjOrSetupId,
                        baseCenter, entity.Rotation, cylRadius,
                        origin.X, origin.Y, lb.LandblockId,
                        AcDream.Core.Physics.ShadowCollisionType.Cylinder, cylHeight);
                    entityCyl++;
                    if (_isScenery) scRegistered++;
                }
                else if (_isScenery) scNoBounds++;
            }

            // Tally per-entity collision presence (debug counter — optional).
            if (entityBsp > 0) lbBspCount++;
            if (entityCyl > 0) lbCylCount++;
            if (entityBsp == 0 && entityCyl == 0)
            {
                // Only count as "none" if it's an OUTDOOR entity (0x01/0x02 source).
                // EnvCell entities (src = cell ID like 0xAABBxxxx) use BSP collision
                // via CellPhysics and don't need cylinder registration.
                uint srcPrefix = entity.SourceGfxObjOrSetupId & 0xFF000000u;
                if (srcPrefix == 0x01000000u || srcPrefix == 0x02000000u)
                    lbNoneCount++;
            }
        }
        if (scTried > 0)
            Console.WriteLine(
                $"lb 0x{lb.LandblockId:X8}: scenery tried={scTried} registered={scRegistered} " +
                $"noBounds={scNoBounds} tooThin={scTooThin} (outdoorNone={lbNoneCount})");

        // Find scenery WITHOUT any cached visual bounds at all
        int sceneryNoCache = 0;
        var sampleMissing = new List<uint>();
        foreach (var entity in lb.Entities)
        {
            if ((entity.Id & 0x80000000u) == 0) continue;  // not scenery
            bool anyHaveBounds = false;
            foreach (var mr in entity.MeshRefs)
            {
                var vb = _physicsDataCache.GetVisualBounds(mr.GfxObjId);
                if (vb is not null && vb.Radius > 0f) { anyHaveBounds = true; break; }
            }
            if (!anyHaveBounds)
            {
                sceneryNoCache++;
                if (sampleMissing.Count < 3)
                    sampleMissing.Add(entity.SourceGfxObjOrSetupId);
            }
        }
        if (sceneryNoCache > 0)
        {
            string samples = string.Join(",", sampleMissing.Select(s => $"0x{s:X8}"));
            Console.WriteLine($"  → {sceneryNoCache} scenery entities had no visual bounds cached. Samples: {samples}");
        }


        // Register each stab as a plugin snapshot so the plugin host has
        // visibility into the streaming world state.
        foreach (var entity in lb.Entities)
        {
            var snapshot = new AcDream.Plugin.Abstractions.WorldEntitySnapshot(
                Id: entity.Id,
                SourceId: entity.SourceGfxObjOrSetupId,
                Position: entity.Position,
                Rotation: entity.Rotation);
            _worldGameState.Add(snapshot);
            _worldEvents.FireEntitySpawned(snapshot);
        }
    }

    private void OnUpdate(double dt)
    {
        // Phase A.1: advance the streaming controller FIRST so the initial
        // landblocks are loaded into GpuWorldState before live-session
        // CreateObject events drain. The earlier order (live tick first,
        // streaming tick second) caused the initial CreateObject flood from
        // login to land before any landblock was loaded; AppendLiveEntity
        // is a no-op for unloaded landblocks, so all 40+ NPCs/weenies were
        // silently dropped on the first frame and never rendered.
        //
        // K-fix1 (2026-04-26): skip streaming entirely while live mode is
        // configured but the chase camera hasn't engaged yet — otherwise
        // the orbit camera at startup centers on the hardcoded
        // 0xA9B4 (Holtburg) and Holtburg landblocks render briefly
        // until the player spawn arrives + auto-entry switches to chase.
        if (_streamingController is not null && _cameraController is not null
            && !IsLiveModeWaitingForLogin)
        {
            int observerCx = _liveCenterX;
            int observerCy = _liveCenterY;

            if (_playerMode && _playerController is not null)
            {
                // Player mode: follow the physics-resolved player position.
                // The player walks via the local physics engine; the server
                // doesn't echo back our autonomous moves, so _lastLivePlayer*
                // stays at the login position. Compute the landblock from the
                // controller's current world-space position instead.
                var pp = _playerController.Position;
                observerCx = _liveCenterX + (int)System.Math.Floor(pp.X / 192f);
                observerCy = _liveCenterY + (int)System.Math.Floor(pp.Y / 192f);
            }
            else if (_liveSession is not null
                && _liveSession.CurrentState == AcDream.Core.Net.WorldSession.State.InWorld
                && _lastLivePlayerLandblockId is { } lid)
            {
                // Live mode (fly camera): follow the server's last-known player position.
                observerCx = (int)((lid >> 24) & 0xFFu);
                observerCy = (int)((lid >> 16) & 0xFFu);
            }
            else
            {
                // Offline: project the fly camera's world-space position back into
                // landblock coordinates. OrbitCamera doesn't expose Position via
                // ICamera, but FlyCamera.Position is always updated (even when the
                // orbit camera is Active), so this is safe in both modes.
                // Each landblock is 192 world units wide.
                var camPos = _cameraController.Fly.Position;
                observerCx = _liveCenterX + (int)System.Math.Floor(camPos.X / 192f);
                observerCy = _liveCenterY + (int)System.Math.Floor(camPos.Y / 192f);
            }

            _streamingController.Tick(observerCx, observerCy);

            // Re-inject persistent entities rescued from unloaded landblocks
            // into the current center landblock (the one the observer is in).
            var rescued = _worldState.DrainRescued();
            if (rescued.Count > 0)
            {
                uint centerLb = (uint)((observerCx << 24) | (observerCy << 16) | 0xFFFF);
                foreach (var entity in rescued)
                    _worldState.AppendLiveEntity(centerLb, entity);
            }
        }

        // Drain pending live-session traffic AFTER streaming so any incoming
        // CreateObject events find their landblock already loaded in
        // GpuWorldState. Non-blocking — returns immediately if no datagrams
        // are in the kernel buffer. Fires EntitySpawned events synchronously.
        _liveSession?.Tick();

        // Phase K.1a — tick the input dispatcher so Hold-type bindings
        // re-fire while their chord is held. K.1b adds the subscribers
        // that actually consume the events.
        _inputDispatcher?.Tick();

        // Phase K.2 — re-evaluate WantCaptureMouse for the MMB
        // mouse-look state machine. Detect rising/falling edges so the
        // state suspends correctly when ImGui claims the cursor while
        // MMB is held (e.g. a tooltip pop-up over the cursor). When the
        // suspend deactivates an active session, restore the cursor so
        // it doesn't get stuck hidden under a panel.
        if (_mouseLook is not null)
        {
            bool wcm = DevToolsEnabled && ImGuiNET.ImGui.GetIO().WantCaptureMouse;
            if (wcm != _lastWantCaptureMouse)
            {
                bool wasActive = _mouseLook.Active;
                _mouseLook.OnWantCaptureMouseChanged(wcm);
                if (wasActive && !_mouseLook.Active) RestoreCursorAfterMouseLook();
                _lastWantCaptureMouse = wcm;
            }
        }

        // Phase K.2 — auto-enter player mode at login. The guard
        // returns true on the firing tick (one-shot); subsequent ticks
        // are no-ops. Skipped offline (no _liveSession → IsLiveInWorld
        // predicate stays false). Cancelled by manual fly-toggle in
        // OnInputAction (Ctrl+Tab → TogglePlayerMode) or DebugPanel.
        _playerModeAutoEntry?.TryEnter();

        if (_cameraController is null || _input is null) return;

        // Phase D.2a / K.1b — suppress game-side input polling when ImGui
        // has keyboard focus (e.g. a text field is active). The InputDispatcher
        // already gates KeyDown/MouseDown via WantCaptureKeyboard internally;
        // this guard adds defense-in-depth for the per-frame IsActionHeld
        // movement poll below (typing "walk" into a chat field shouldn't
        // walk).
        bool suppressGameInput =
            DevToolsEnabled && ImGuiNET.ImGui.GetIO().WantCaptureKeyboard;
        if (suppressGameInput) return;

        if (_cameraController.IsFlyMode)
        {
            // K.1b: fly-camera input flows through the dispatcher. Reuses
            // movement actions (Forward/Backup/TurnLeft/TurnRight/Jump/
            // RunLock) — in fly mode "TurnLeft" semantically maps to
            // strafe-left because A/D in fly is strafe, not turn (mouse
            // delta drives fly heading instead).
            if (_inputDispatcher is null) return;
            _cameraController.Fly.Update(
                dt,
                w:     _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementForward),
                a:     _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementTurnLeft),
                s:     _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementBackup),
                d:     _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementTurnRight),
                up:    _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementJump),
                down:  _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.AcdreamFlyDown),
                boost: _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementRunLock));
        }
        else if (_playerMode && _playerController is not null && _chaseCamera is not null)
        {
            // Phase B.2 / K.1b: player movement mode — every input flows
            // through the dispatcher. WASD walks/runs, A/D turns, Z/X
            // strafes, Shift runs, Space jumps. Mouse delta NEVER drives
            // character yaw (regression-prevention per K.1b plan §D);
            // MouseDeltaX is hardcoded 0f. RMB held still pans the chase
            // camera (handled in the mouse-move handler via _rmbHeld).
            // The _playerMouseDeltaX field is preserved as plumbing for the
            // future MMB-mouse-look behavior coming back in K.2.
            if (_inputDispatcher is null) return;
            _playerMouseDeltaX = 0f;  // defensive: ensure no leakage even if some path writes it

            // K-fix1 (2026-04-26): retail-faithful movement semantics.
            //   * Default speed = RUN. Forward / backward / strafe all run
            //     by default; holding Shift (MovementWalkMode) drops to
            //     walk speed.
            //   * Q = AUTORUN TOGGLE: pressing Q latches forward-running
            //     until Q is pressed again. Handled in OnInputAction; here
            //     we just OR _autoRunActive into the Forward flag.
            //   * Mouse never drives character yaw (K.1b regression-prevention).
            bool walking = _inputDispatcher.IsActionHeld(
                AcDream.UI.Abstractions.Input.InputAction.MovementWalkMode);
            bool wHeld = _inputDispatcher.IsActionHeld(
                AcDream.UI.Abstractions.Input.InputAction.MovementForward);
            var input = new AcDream.App.Input.MovementInput(
                Forward:     wHeld || _autoRunActive,
                Backward:    _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementBackup),
                StrafeLeft:  _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementStrafeLeft),
                StrafeRight: _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementStrafeRight),
                TurnLeft:    _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementTurnLeft),
                TurnRight:   _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementTurnRight),
                Run:         !walking,  // default = run; Shift held = walk
                MouseDeltaX: 0f,
                Jump:        _inputDispatcher.IsActionHeld(AcDream.UI.Abstractions.Input.InputAction.MovementJump));

            var result = _playerController.Update((float)dt, input);

            // Update the player entity's position + rotation so it renders at
            // the physics-resolved location each frame.
            if (_entitiesByServerGuid.TryGetValue(_playerServerGuid, out var pe))
            {
                pe.Position = result.Position;
                pe.Rotation = System.Numerics.Quaternion.CreateFromAxisAngle(
                    System.Numerics.Vector3.UnitZ, _playerController.Yaw - MathF.PI / 2f);

                // Move the player entity to its current landblock in GpuWorldState
                // so it doesn't get frustum-culled when the player walks away from
                // the spawn landblock. Without this, the entity stays in the spawn
                // landblock's entity list and disappears when that landblock is culled.
                var pp = _playerController.Position;
                int plx = _liveCenterX + (int)System.Math.Floor(pp.X / 192f);
                int ply = _liveCenterY + (int)System.Math.Floor(pp.Y / 192f);
                uint currentLb = (uint)((plx << 24) | (ply << 16) | 0xFFFF);
                _worldState.RelocateEntity(pe, currentLb);
            }

            // Update chase camera. K-fix12 (2026-04-26): pass isOnGround
            // so the camera pins its Z to last-grounded while the
            // player is airborne — without this the camera follows
            // player.Z 1:1 during a jump and the player's screen
            // position never changes. With the pin: player visibly
            // rises above the camera, matching retail "you can see
            // yourself jump" feedback.
            _chaseCamera.Update(result.Position, _playerController.Yaw,
                isOnGround: result.IsOnGround,
                dt: (float)dt);

            // Send outbound movement messages to the live server.
            if (_liveSession is not null)
            {
                // Convert world position back to AC wire coordinates.
                // World origin is _liveCenterX/_liveCenterY; each landblock is 192 units.
                int lbX = _liveCenterX + (int)MathF.Floor(result.Position.X / 192f);
                int lbY = _liveCenterY + (int)MathF.Floor(result.Position.Y / 192f);
                float localX = result.Position.X - (lbX - _liveCenterX) * 192f;
                float localY = result.Position.Y - (lbY - _liveCenterY) * 192f;
                uint wireCellId = ((uint)lbX << 24) | ((uint)lbY << 16) | (result.CellId & 0xFFFFu);
                var wirePos = new System.Numerics.Vector3(localX, localY, result.Position.Z);
                var wireRot = YawToAcQuaternion(_playerController.Yaw);

                if (result.MotionStateChanged)
                {
                    // HoldKey axis values — retail enum (holtburger types.rs HoldKey):
                    //   Invalid = 0, None = 1, Run = 2
                    // Retail always sends CURRENT_HOLD_KEY (and uses the same
                    // value for every active per-axis hold key — see
                    // holtburger's build_motion_state_raw_motion_state).
                    // When the player is running forward, 2=Run; otherwise 1=None.
                    const uint HoldKeyNone = 1u;
                    const uint HoldKeyRun  = 2u;
                    uint axisHoldKey = result.IsRunning ? HoldKeyRun : HoldKeyNone;

                    var seq = _liveSession.NextGameActionSequence();
                    var body = AcDream.Core.Net.Messages.MoveToState.Build(
                        gameActionSequence:     seq,
                        forwardCommand:         result.ForwardCommand,
                        forwardSpeed:           result.ForwardSpeed,
                        sidestepCommand:        result.SidestepCommand,
                        sidestepSpeed:          result.SidestepSpeed,
                        turnCommand:            result.TurnCommand,
                        turnSpeed:              result.TurnSpeed,
                        holdKey:                axisHoldKey,                                                  // always present
                        forwardHoldKey:         result.ForwardCommand.HasValue  ? axisHoldKey : (uint?)null,
                        sidestepHoldKey:        result.SidestepCommand.HasValue ? axisHoldKey : (uint?)null,
                        turnHoldKey:            result.TurnCommand.HasValue     ? axisHoldKey : (uint?)null,
                        cellId:                 wireCellId,
                        position:               wirePos,
                        rotation:               wireRot,
                        instanceSequence:       _liveSession.InstanceSequence,
                        serverControlSequence:  _liveSession.ServerControlSequence,
                        teleportSequence:       _liveSession.TeleportSequence,
                        forcePositionSequence:  _liveSession.ForcePositionSequence);
                    _liveSession.SendGameAction(body);
                }

                if (_playerController.HeartbeatDue)
                {
                    var seq = _liveSession.NextGameActionSequence();
                    var body = AcDream.Core.Net.Messages.AutonomousPosition.Build(
                        gameActionSequence:     seq,
                        cellId:                 wireCellId,
                        position:               wirePos,
                        rotation:               wireRot,
                        instanceSequence:       _liveSession.InstanceSequence,
                        serverControlSequence:  _liveSession.ServerControlSequence,
                        teleportSequence:       _liveSession.TeleportSequence,
                        forcePositionSequence:  _liveSession.ForcePositionSequence);
                    _liveSession.SendGameAction(body);
                }

                if (result.JumpExtent.HasValue && result.JumpVelocity.HasValue)
                {
                    var seq = _liveSession.NextGameActionSequence();
                    var jumpBody = AcDream.Core.Net.Messages.JumpAction.Build(
                        gameActionSequence:     seq,
                        extent:                 result.JumpExtent.Value,
                        velocity:               result.JumpVelocity.Value,
                        instanceSequence:       _liveSession.InstanceSequence,
                        serverControlSequence:  _liveSession.ServerControlSequence,
                        teleportSequence:       _liveSession.TeleportSequence,
                        forcePositionSequence:  _liveSession.ForcePositionSequence);
                    _liveSession.SendGameAction(jumpBody);
                }
            }

            // Update the player entity's animation cycle to match current motion.
            UpdatePlayerAnimation(result);
        }
    }

    /// <summary>
    /// Convert our internal yaw (math convention: 0=+X East, PI/2=+Y North)
    /// to AC's quaternion heading convention.
    /// AC heading: 0=West, 90=North, 180=East, 270=South.
    /// Formula from holtburger Quaternion::from_heading.
    /// </summary>
    private static System.Numerics.Quaternion YawToAcQuaternion(float yaw)
    {
        // Our yaw → AC heading in degrees:
        // yaw=0 → East → AC 180°, yaw=PI/2 → North → AC 90°
        // heading_deg = 180 - yaw_degrees
        float yawDeg = yaw * (180f / MathF.PI);
        float headingDeg = 180f - yawDeg;
        if (headingDeg < 0f) headingDeg += 360f;
        if (headingDeg >= 360f) headingDeg -= 360f;

        // holtburger from_heading: theta = (450 - heading_deg) in radians
        float theta = (450f - headingDeg) * (MathF.PI / 180f);
        float halfTheta = theta * 0.5f;
        float w = MathF.Cos(halfTheta);
        float z = MathF.Sin(halfTheta);

        // Canonicalize: w must be non-negative
        if (w < 0f) { w = -w; z = -z; }

        return new System.Numerics.Quaternion(0f, 0f, z, w);
    }

    private void OnCameraModeChanged(bool _modeBool)
    {
        if (_input is null) return;
        var mouse = _input.Mice.FirstOrDefault();
        if (mouse is null) return;

        // K-fix2 (2026-04-26): the bool passed to ModeChanged is NOT
        // reliably "isFlyMode" — CameraController.EnterChaseMode invokes
        // it with IsChaseMode (true), CameraController.ToggleFly invokes
        // it with IsFlyMode, and CameraController.ExitChaseMode invokes
        // it with IsFlyMode. Reading the controller state directly is
        // the only correct gate. Cursor visible by default in chase /
        // orbit modes; Raw cursor only in fly mode (continuous
        // look-and-fly affordance). Mouse-look (raw mode) when MMB is
        // held is handled separately by HideCursorForMouseLook /
        // RestoreCursorAfterMouseLook.
        bool needsRawCursor = _cameraController?.IsFlyMode == true;
        mouse.Cursor.CursorMode = needsRawCursor ? CursorMode.Raw : CursorMode.Normal;
        _capturedMouse = needsRawCursor ? mouse : null;
    }

    // Performance overlay state — updated every ~0.5s and written to the
    // window title so there's zero rendering cost (no font/overlay needed).
    private double _perfAccum;
    private int _perfFrameCount;

    private void OnRender(double deltaSeconds)
    {
        // Phase G.1: set the clear color from the current sky's fog
        // tint so the horizon band continues naturally past the
        // rendered geometry. Fog blends to this color at max distance
        // so there's no visible seam. Updated each frame from the
        // interpolated keyframe.
        var kf = WorldTime.CurrentSky;
        var atmo = Weather.Snapshot(in kf);
        var fogColor = atmo.FogColor;
        // Clear to fog color (horizon haze) so if sky meshes have alpha
        // gaps or don't cover the full view, the "missing" area reads as
        // distant haze, not as pitch-black. Fog color is clamped to 0..1
        // since keyframes may pre-multiply DirBright and produce over-1
        // values that some drivers interpret as "bright clamp" (pink/green
        // frames).
        _gl!.ClearColor(
            System.Math.Clamp(fogColor.X, 0f, 1f),
            System.Math.Clamp(fogColor.Y, 0f, 1f),
            System.Math.Clamp(fogColor.Z, 0f, 1f),
            1f);

        _gl!.Clear(ClearBufferMask.ColorBufferBit | ClearBufferMask.DepthBufferBit);

        // Phase D.2a — begin ImGui frame. Paired with the Render() call
        // after the scene draws (below). ImGuiController.Update()
        // consumes buffered Silk.NET input events and calls ImGui.NewFrame.
        if (DevToolsEnabled && _imguiBootstrap is not null)
            _imguiBootstrap.BeginFrame((float)deltaSeconds);

        // Phase 6.4: advance per-entity animation playback before drawing
        // so the renderer always sees the up-to-date per-part transforms.
        if (_animatedEntities.Count > 0)
            TickAnimations((float)deltaSeconds);

        // Phase G.1: weather state machine — deterministic per-day roll
        // + transitions + lightning flash.
        var cal = WorldTime.CurrentCalendar;
        int dayIndex = cal.Year * (AcDream.Core.World.DerethDateTime.DaysInAMonth *
                                    AcDream.Core.World.DerethDateTime.MonthsInAYear)
                     + (int)cal.Month * AcDream.Core.World.DerethDateTime.DaysInAMonth
                     + (cal.Day - 1);
        Weather.Tick(nowSeconds: _weatherAccum, dayIndex: dayIndex, dtSeconds: (float)deltaSeconds);
        _weatherAccum += deltaSeconds;

        // (Pre-Bug-A code spawned camera-attached rain/snow particle
        // emitters here as a workaround for missing weather-mesh
        // rendering. Deleted 2026-04-26 once the retail-faithful world-
        // space mesh path landed in SkyRenderer.RenderWeather. Retail
        // rain is GfxObj 0x01004C42/0x01004C44 — a hollow octagonal
        // cylinder anchored at player_pos + (0, 0, -120m) per
        // GameSky::UpdatePosition at 0x00506dd0 — drawn after the
        // landblock pass per LScape::draw at 0x00506330. There is no
        // server-driven weather event and no camera-attached emitter
        // in retail. Snow renders identically when a Snowy DayGroup is
        // active in some other Region; the partition by Properties&0x04
        // and the SkyRenderer.RenderWeather pass both pick up snow
        // weather meshes for free.)

        // Phase E.3: advance live particle emitters AFTER animation tick
        // so emitters spawned by hooks fired this frame get integrated.
        // Tick the PhysicsScript runner BEFORE the particle system so any
        // CreateParticleHook fired this frame has its emitter alive when
        // the particle system advances.
        _scriptRunner?.Tick((float)deltaSeconds);

        _particleSystem?.Tick((float)deltaSeconds);

        int visibleLandblocks = 0;
        int totalLandblocks = 0;

        if (_cameraController is not null)
        {
            var camera = _cameraController.Active;
            var frustum = AcDream.App.Rendering.FrustumPlanes.FromViewProjection(camera.View * camera.Projection);

            // Extract camera world position from the inverse of the view
            // matrix — needed by the scene-lighting UBO (for fog distance)
            // and by the sky renderer (for the camera-centered sky dome).
            System.Numerics.Matrix4x4.Invert(camera.View, out var invView);
            var camPos = new System.Numerics.Vector3(invView.M41, invView.M42, invView.M43);

            // L.0 Audio tab: push the SettingsVM's live AudioDraft into the
            // engine each frame, so volume sliders preview audibly while
            // the user drags. Cancel reverts the draft and the engine
            // catches up on the very next frame; Save persists to
            // settings.json without changing engine state (already
            // applied). Cheap enough to run unconditionally on every
            // tick — four float assignments.
            if (_audioEngine is not null && _audioEngine.IsAvailable && _settingsVm is not null)
            {
                var a = _settingsVm.AudioDraft;
                _audioEngine.MasterVolume  = a.Master;
                _audioEngine.MusicVolume   = a.Music;
                _audioEngine.SfxVolume     = a.Sfx;
                _audioEngine.AmbientVolume = a.Ambient;
            }

            // L.0 Display tab: push the live DisplayDraft into the
            // active rendering surfaces each frame. FOV is the live-
            // preview slider per the brainstorm — dragging it changes
            // camera FovY immediately. VSync change-detected to avoid
            // spamming the window. Resolution + Fullscreen apply on
            // Save (handled by ApplyDisplayWindowState — too jarring
            // to live-preview a resize).
            if (_settingsVm is not null && _cameraController is not null)
            {
                var d = _settingsVm.DisplayDraft;
                float fovYRad = d.FieldOfView * (MathF.PI / 180f);
                _cameraController.Orbit.FovY = fovYRad;
                _cameraController.Fly.FovY   = fovYRad;
                if (_cameraController.Chase is not null)
                    _cameraController.Chase.FovY = fovYRad;
                if (_window is not null && _window.VSync != d.VSync)
                    _window.VSync = d.VSync;
            }

            // Phase E.2 audio: update listener pose so 3D sounds pan/attenuate
            // correctly relative to where we're looking.
            if (_audioEngine is not null && _audioEngine.IsAvailable)
            {
                var fwd = new System.Numerics.Vector3(-invView.M31, -invView.M32, -invView.M33);
                var up  = new System.Numerics.Vector3( invView.M21,  invView.M22,  invView.M23);
                _audioEngine.SetListener(
                    camPos.X, camPos.Y, camPos.Z,
                    fwd.X, fwd.Y, fwd.Z,
                    up.X,  up.Y,  up.Z);
            }

            // Step 4: portal visibility — compute BEFORE the UBO upload so
            // the indoor flag drives the sun's intensity to zero for
            // dungeons (r13 §13.7).
            var visibility = _cellVisibility.ComputeVisibility(camPos);
            bool cameraInsideCell = visibility?.CameraCell is not null;

            // Phase G.1/G.2: feed the sun, tick LightManager, build + upload
            // the scene-lighting UBO once per frame. Every shader that
            // consumes binding=1 reads the same data for the rest of the
            // frame — terrain, static mesh, instanced mesh, sky.
            UpdateSunFromSky(kf, cameraInsideCell);
            Lighting.Tick(camPos);
            var ubo = AcDream.Core.Lighting.SceneLightingUbo.Build(
                Lighting, in atmo, camPos, (float)WorldTime.DayFraction);
            _sceneLightingUbo?.Upload(ubo);

            // Never cull the landblock the player is currently on.
            uint? playerLb = null;
            if (_playerMode && _playerController is not null)
            {
                var pp = _playerController.Position;
                int plx = _liveCenterX + (int)System.Math.Floor(pp.X / 192f);
                int ply = _liveCenterY + (int)System.Math.Floor(pp.Y / 192f);
                playerLb = (uint)((plx << 24) | (ply << 16) | 0xFFFF);
            }

            // Phase G.1: sky renderer — draws the far-plane-infinity
            // celestial meshes FIRST so the rest of the scene z-tests
            // on top of them (depth mask off, no depth writes). Skipped
            // when indoors; dungeons fully block sky visibility.
            //
            // Mirrors retail's LScape::draw at 0x00506330 which calls
            // GameSky::Draw(0) (sky pass) BEFORE the landblock DrawBlock
            // loop and GameSky::Draw(1) (weather pass) AFTER. The split
            // matters because weather meshes (the 815m-tall rain
            // cylinder 0x01004C42/0x01004C44) need to overlay terrain
            // and entities to look volumetric — see the post-scene
            // RenderWeather call further below.
            if (!cameraInsideCell)
            {
                _skyRenderer?.RenderSky(camera, camPos, (float)WorldTime.DayFraction,
                    _activeDayGroup, kf);
            }

            // K-fix1 (2026-04-26): suppress terrain + entity rendering
            // while live mode is configured but the chase camera hasn't
            // engaged yet — pairs with the streaming-Tick gate in
            // OnUpdate so absolutely nothing of the world (Holtburg or
            // otherwise) renders pre-login. The sky still draws above so
            // the user sees a live, time-of-day-correct sky during the
            // brief connection + character-list + EnterWorld handshake.
            if (IsLiveModeWaitingForLogin)
            {
                goto SkipWorldGeometry;
            }

            _terrain?.Draw(camera, frustum, neverCullLandblockId: playerLb);

            // Conditional depth clear: when camera is inside a building, clear
            // depth (not color) so interior geometry writes fresh Z values on top
            // of the terrain color buffer. Exit portals show outdoor terrain color
            // because we kept the color buffer. Matching ACME GameScene.cs pattern.
            if (cameraInsideCell)
                _gl!.Clear(ClearBufferMask.DepthBufferBit);

            _staticMesh?.Draw(camera, _worldState.LandblockEntries, frustum,
                neverCullLandblockId: playerLb,
                visibleCellIds: visibility?.VisibleCellIds);

            // Phase G.1 / E.3: draw all live particles after opaque
            // scene geometry so alpha blending composites correctly.
            // Runs with depth test on (particles occluded by walls)
            // but depth write off (no self-occlusion sorting needed).
            if (_particleSystem is not null && _particleRenderer is not null)
                _particleRenderer.Draw(_particleSystem, camera, camPos);

            // Bug A fix (post-#26 worktree, 2026-04-26): weather sky
            // meshes (Properties & 0x04, e.g. the 815m-tall rain
            // cylinder 0x01004C42/0x01004C44) render AFTER the scene so
            // the additive rain streaks overlay terrain and entities
            // instead of being painted over by them. This is the second
            // half of retail's LScape::draw split — GameSky::Draw(1)
            // fires after the DrawBlock loop. Same indoor gate as the
            // sky pass: weather is suppressed inside cells.
            if (!cameraInsideCell)
            {
                _skyRenderer?.RenderWeather(camera, camPos, (float)WorldTime.DayFraction,
                    _activeDayGroup, kf);
            }

            // Debug: draw collision shapes as wireframe cylinders around the
            // player so we can visually verify alignment with scenery meshes.
            if (_debugCollisionVisible && _debugLines is not null)
            {
                _debugLines.Begin();

                // Pick the center for the debug radius. Prefer player
                // position in player mode, otherwise use camPos.
                System.Numerics.Vector3 center;
                if (_playerMode && _playerController is not null)
                    center = _playerController.Position;
                else
                    center = camPos;

                // Draw ALL registered shadow objects regardless of distance —
                // if it has collision, it gets a wireframe. This lets the user
                // see exactly what's in the collision registry at any moment.
                int drawn = 0;
                foreach (var obj in _physicsEngine.ShadowObjects.AllEntriesForDebug())
                {
                    var dx = obj.Position.X - center.X;
                    var dy = obj.Position.Y - center.Y;

                    if (obj.CollisionType == AcDream.Core.Physics.ShadowCollisionType.Cylinder)
                    {
                        float h = obj.CylHeight > 0 ? obj.CylHeight : obj.Radius * 2f;
                        _debugLines.AddCylinder(
                            obj.Position, obj.Radius, h,
                            new System.Numerics.Vector3(0f, 1f, 0f)); // green cylinders
                    }
                    else
                    {
                        // BSP: show a bounding sphere as a cylinder for visibility
                        _debugLines.AddCylinder(
                            obj.Position - new System.Numerics.Vector3(0, 0, obj.Radius),
                            obj.Radius, obj.Radius * 2f,
                            new System.Numerics.Vector3(1f, 0.5f, 0f)); // orange BSP
                    }
                    drawn++;
                }

                // Draw the player's collision sphere as a red cylinder (0.48m radius, 1.8m tall)
                if (_playerMode && _playerController is not null)
                {
                    var pp = _playerController.Position;
                    _debugLines.AddCylinder(
                        new System.Numerics.Vector3(pp.X, pp.Y, pp.Z - 0.0f),
                        0.48f, 1.8f,
                        new System.Numerics.Vector3(1f, 0f, 0f)); // red player
                }

                if (_debugDrawLogOnce < 5 && _playerMode && _playerController is not null)
                {
                    var pp = _playerController.Position;
                    Console.WriteLine(
                        $"debug frame {_debugDrawLogOnce}: player=({pp.X:F1},{pp.Y:F1},{pp.Z:F1}) drew={drawn} " +
                        $"totalReg={_physicsEngine.ShadowObjects.TotalRegistered}");
                    // Sample 3 nearest shadow objects
                    int logged = 0;
                    foreach (var o in _physicsEngine.ShadowObjects.AllEntriesForDebug())
                    {
                        var dx = o.Position.X - pp.X;
                        var dy = o.Position.Y - pp.Y;
                        float dh = MathF.Sqrt(dx * dx + dy * dy);
                        if (dh < 10f)
                        {
                            Console.WriteLine($"  near id=0x{o.EntityId:X8} type={o.CollisionType} pos=({o.Position.X:F1},{o.Position.Y:F1},{o.Position.Z:F1}) r={o.Radius:F2} h={o.CylHeight:F2} dh={dh:F2}");
                            if (++logged >= 5) break;
                        }
                    }
                    _debugDrawLogOnce++;
                }
                _debugLines.Flush(camera.View, camera.Projection);
            }

            // Count visible vs total for the perf overlay.
            foreach (var entry in _worldState.LandblockEntries)
            {
                totalLandblocks++;
                if (AcDream.App.Rendering.FrustumCuller.IsAabbVisible(frustum, entry.AabbMin, entry.AabbMax))
                    visibleLandblocks++;
            }

            // Phase I.2: refresh per-frame fields that DebugVM closures
            // can't compute lazily (frustum-derived counters + nearest-
            // object scan). Every other DebugVM field reads through to
            // the live source via its closure. Skipped entirely when
            // devtools are off — avoids the nearest-object O(N) scan in
            // the hot path of an offline render.
            if (_debugVm is not null)
            {
                _lastVisibleLandblocks = visibleLandblocks;
                _lastTotalLandblocks = totalLandblocks;

                // Compute fly/orbit-mode camera position for the nearest-
                // object scan when not in player mode.
                System.Numerics.Vector3 nearOrigin;
                if (_playerMode && _playerController is not null)
                    nearOrigin = _playerController.Position;
                else
                    nearOrigin = camPos;

                const float playerRadius = 0.48f;
                float bestDist = float.PositiveInfinity;
                string bestLabel = "-";
                foreach (var obj in _physicsEngine.ShadowObjects.AllEntriesForDebug())
                {
                    float dx = obj.Position.X - nearOrigin.X;
                    float dy = obj.Position.Y - nearOrigin.Y;
                    float d = MathF.Sqrt(dx * dx + dy * dy) - obj.Radius - playerRadius;
                    if (d < bestDist)
                    {
                        bestDist = d;
                        bestLabel = $"0x{obj.EntityId:X8} {obj.CollisionType}";
                    }
                }
                _lastColliding = bestDist < 0.05f;
                _lastNearestObjDist = bestDist < 0f ? 0f : bestDist;
                _lastNearestObjLabel = bestLabel;
            }

            // K-fix1 (2026-04-26): jump target for IsLiveModeWaitingForLogin —
            // skips the world geometry pass before login. ImGui (chat,
            // debug, settings panels) and the menu bar still render
            // below. Sky has already drawn before this label so the
            // pre-login screen shows a live, correctly-tinted sky and
            // nothing else.
            SkipWorldGeometry: ;
        }

        // Phase D.2a — end ImGui frame. Runs AFTER all scene + debug draws
        // so ImGui composites on top. ImGuiController save/restores the
        // GL state it touches (blend, scissor, VAO, shader, texture); any
        // state not in its save-list (e.g. GL_FRAMEBUFFER_SRGB, unused
        // today) would need manual protection.
        if (DevToolsEnabled && _imguiBootstrap is not null && _panelHost is not null)
        {
            // Phase I.3 — prefer the live command bus when a live session
            // is up so panel-emitted SendChatCmd actually flows server-ward.
            // Fall back to NullCommandBus for offline / pre-connect renders.
            AcDream.UI.Abstractions.ICommandBus bus =
                _commandBus ?? (AcDream.UI.Abstractions.ICommandBus)
                    AcDream.UI.Abstractions.NullCommandBus.Instance;
            var ctx = new AcDream.UI.Abstractions.PanelContext(
                (float)deltaSeconds,
                bus);

            // Phase K.3 — top-of-screen menu bar. Provides discoverable
            // entries for users who don't memorize the F-keys (View →
            // Settings / Vitals / Chat / Debug). Uses ImGuiNET directly
            // here because the panel host doesn't own a menu-bar
            // surface; the abstraction (BeginMainMenuBar / BeginMenu /
            // MenuItem) exists for backend portability + tests but only
            // gets exercised here once per frame.
            if (ImGuiNET.ImGui.BeginMainMenuBar())
            {
                if (ImGuiNET.ImGui.BeginMenu("View"))
                {
                    if (_settingsPanel is not null
                        && ImGuiNET.ImGui.MenuItem("Settings", "F11"))
                        _settingsPanel.IsVisible = !_settingsPanel.IsVisible;
                    if (_vitalsPanel is not null
                        && ImGuiNET.ImGui.MenuItem("Vitals"))
                        _vitalsPanel.IsVisible = !_vitalsPanel.IsVisible;
                    if (_chatPanel is not null
                        && ImGuiNET.ImGui.MenuItem("Chat"))
                        _chatPanel.IsVisible = !_chatPanel.IsVisible;
                    if (_debugPanel is not null
                        && ImGuiNET.ImGui.MenuItem("Debug", "Ctrl+F1"))
                        _debugPanel.IsVisible = !_debugPanel.IsVisible;
                    ImGuiNET.ImGui.Separator();
                    // L.0 Display tab: a manual reset for users whose
                    // imgui.ini has saved a panel position that's now
                    // off-screen (after a window shrink, monitor swap,
                    // or a malformed save). Force-resets every panel
                    // to its default landing position. The same code
                    // path runs automatically on FramebufferResize.
                    if (ImGuiNET.ImGui.MenuItem("Reset window layout"))
                        ResetPanelLayout(ImGuiNET.ImGuiCond.Always);
                    ImGuiNET.ImGui.EndMenu();
                }
                // K-fix2 (2026-04-26): Camera submenu — discoverable
                // free-fly toggle for users who don't know the
                // Ctrl+Shift+F shortcut or the Debug-panel button.
                if (ImGuiNET.ImGui.BeginMenu("Camera"))
                {
                    if (_cameraController is not null)
                    {
                        string flyLabel = _cameraController.IsFlyMode
                            ? "Exit Free-Fly Mode" : "Enter Free-Fly Mode";
                        if (ImGuiNET.ImGui.MenuItem(flyLabel, "Ctrl+Shift+F"))
                            ToggleFlyOrChase();
                    }
                    ImGuiNET.ImGui.EndMenu();
                }
                ImGuiNET.ImGui.EndMainMenuBar();
            }

            _panelHost.RenderAll(ctx);
            _imguiBootstrap.Render();
        }

        // Update the window title with performance stats every ~0.5s.
        _perfAccum += deltaSeconds;
        _perfFrameCount++;
        if (_perfAccum >= 0.5)
        {
            double avgFrameTime = _perfAccum / _perfFrameCount * 1000.0;
            double fps = _perfFrameCount / _perfAccum;
            int entityCount = _worldState.Entities.Count;
            int animatedCount = _animatedEntities.Count;

            // L.0 Display tab: ShowFps gates the perf string in the
            // title bar. Default is true (matches pre-L.0 behaviour);
            // unchecking the toggle in Display tab collapses the title
            // to just "acdream" for a cleaner alt-tab experience.
            //
            // When perf is shown, also include the in-game calendar/time —
            // matches retail's @timestamp output ("Date: <Month> <Day>,
            // PY <Year>  Time: <HourName>"). Uses NowTicks (server-synced
            // + wall-clock interpolation) so the user can read the same
            // fields off both acdream and retail and confirm clock parity
            // directly. Drift > 1 hour = real bug.
            bool showFps = _settingsVm?.DisplayDraft.ShowFps ?? true;
            if (showFps)
            {
                double tNow = WorldTime.NowTicks;
                var titleCal = AcDream.Core.World.DerethDateTime.ToCalendar(tNow);
                double df = WorldTime.DayFraction;
                _window!.Title =
                    $"acdream | {fps:F0} fps | {avgFrameTime:F1} ms | "
                  + $"lb {visibleLandblocks}/{totalLandblocks} | ent {entityCount}/anim {animatedCount} | "
                  + $"PY{titleCal.Year} {titleCal.Month} {titleCal.Day} {titleCal.Hour} (df={df:F4})";
            }
            else
            {
                _window!.Title = "acdream";
            }
            _lastFps = fps;
            _lastFrameMs = avgFrameTime;
            _perfAccum = 0;
            _perfFrameCount = 0;
        }
    }

    /// <summary>
    /// Phase 6.4: advance every animated entity's frame counter by
    /// <paramref name="dt"/> * Framerate, wrapping around the cycle's
    /// [LowFrame..HighFrame] interval, then rebuild that entity's
    /// MeshRefs from the new frame's per-part transforms. Static
    /// entities (no AnimatedEntity record) are untouched. The static
    /// renderer reads the new MeshRefs on the next Draw call.
    /// </summary>
    private void TickAnimations(float dt)
    {
        // Retail has NO stop-detection heuristic — it relies on the
        // server sending explicit UpdateMotion(Ready). The server-side
        // stop signal flows the same way as any other motion change:
        //   alt releases W → MoveToState(Ready) → ACE broadcasts
        //   UpdateMotion(Ready) + UpdatePosition with zero velocity.
        // On our side, both are handled: UpdateMotion routes through
        // MotionInterpreter.DoInterpretedMotion which zeroes the
        // interpreter's state, and UpdatePosition's HasVelocity~0 hits
        // MotionInterpreter.StopCompletely. Anything else is server
        // buggery (packet loss, ACE bug) — don't guess client-side.
        var now = System.DateTime.UtcNow;

        foreach (var kv in _animatedEntities)
        {
            var ae = kv.Value;

            // Locate the server guid for this entity once per tick — needed
            // for dead-reckoning. O(N) reverse lookup; for player populations
            // < 100 the cost is negligible.
            uint serverGuid = 0;
            foreach (var esg in _entitiesByServerGuid)
            {
                if (ReferenceEquals(esg.Value, ae.Entity)) { serverGuid = esg.Key; break; }
            }

            // ── Dead-reckoning: smooth position between UpdatePosition bursts.
            // The server broadcasts UpdatePosition at ~5-10Hz for distant
            // entities; without integration, remote chars jitter-hop between
            // samples. Each tick we advance entity.Position by the
            // sequencer's current velocity (rotated into world space by the
            // entity's facing) — matching the retail client's
            // apply_current_movement (chunk_00520000.c L7132-L7189) and
            // holtburger's project_pose_by_velocity.
            //
            // The cap on predict-distance from the last server pos prevents
            // runaway when the sequencer's velocity and the server's reality
            // disagree (e.g. server is rubber-banding the entity). Retail
            // uses a similar clamp at PhysicsObj::IsInterpolationComplete.
            if (ae.Sequencer is not null
                && serverGuid != 0
                && serverGuid != _playerServerGuid
                && _remoteDeadReckon.TryGetValue(serverGuid, out var rm))
            {
                // Stop detection is handled explicitly on packet receipt:
                //   - UpdateMotion with ForwardCommand flag CLEARED → Ready.
                //   - UpdatePosition with HasVelocity flag CLEARED → StopCompletely.
                // Both map to retail's "flag-absent = Invalid = reset to
                // default" semantics (FUN_0051F260 bulk-copy). No timer-based
                // inference needed — the server sends the right signal every
                // time a remote stops.

                // Retail per-tick motion pipeline applied to every remote.
                // Mirrors retail FUN_00515020 update_object → FUN_00513730
                // UpdatePositionInternal → FUN_005111D0 UpdatePhysicsInternal:
                //
                //   1. apply_current_movement (FUN_00529210) — recomputes
                //      body.Velocity from InterpretedState via get_state_velocity.
                //   2. Pull omega from the sequencer (baked MotionData.Omega
                //      for TurnRight / TurnLeft cycles, scaled by speedMod).
                //   3. body.update_object(now) — Euler-integrates
                //      position += Velocity × dt + 0.5 × Accel × dt² AND
                //      orientation += omega × dt.
                //
                // On UpdatePosition receipt we hard-snap body.Position and
                // body.Orientation — if integration matched server physics,
                // each snap is small/invisible.
                double nowSec = (System.DateTime.UtcNow - System.DateTime.UnixEpoch).TotalSeconds;

                // Step 1: re-apply current motion commands → body.Velocity.
                // Forces OnWalkable + Contact so the gate in apply_current_movement
                // always succeeds (remotes are server-authoritative; we don't
                // simulate airborne physics for them).
                //
                // K-fix9 (2026-04-26): SKIP this when the remote is airborne.
                // Otherwise the force-OnWalkable + apply_current_movement
                // path stomps the +Z velocity we set in OnLiveVectorUpdated,
                // and gravity never gets to integrate the arc. The airborne
                // body keeps the launch velocity from the VectorUpdate;
                // UpdatePhysicsInternal below applies gravity each tick;
                // the next UpdatePosition snaps to the new ground location
                // and re-grounds.
                if (!rm.Airborne)
                {
                    rm.Body.TransientState |= AcDream.Core.Physics.TransientStateFlags.Contact
                                            | AcDream.Core.Physics.TransientStateFlags.OnWalkable
                                            | AcDream.Core.Physics.TransientStateFlags.Active;
                    rm.Motion.apply_current_movement(cancelMoveTo: false, allowJump: false);
                }
                else
                {
                    // Airborne — keep Active flag (so UpdatePhysicsInternal
                    // doesn't early-return) but DON'T set Contact / OnWalkable.
                    rm.Body.TransientState |= AcDream.Core.Physics.TransientStateFlags.Active;
                }

                // Step 2: integrate rotation manually per tick. We can't
                // rely on PhysicsBody.update_object here — its MinQuantum
                // gate (1/30 s) causes it to SKIP integration when our
                // 60fps render dt (~0.016s) is below the quantum, meaning
                // rotation never advances. Measured snap per UP was ~129°
                // = the full expected 1s × 2.24 rad/s, confirming zero
                // between-tick rotation.
                //
                // Manual integration matches retail's FUN_005256b0
                // apply_physics (Orientation *= quat(ω × dt)). Use
                // ObservedOmega derived from server UP rotation deltas so
                // the rate exactly matches server physics — hard-snap on
                // next UP becomes invisible by construction.
                rm.Body.Omega = System.Numerics.Vector3.Zero; // don't double-integrate in update_object
                if (rm.ObservedOmega.LengthSquared() > 1e-8f)
                {
                    float omegaMag = rm.ObservedOmega.Length();
                    var axis = rm.ObservedOmega / omegaMag;
                    float angle = omegaMag * dt;
                    var deltaRot = System.Numerics.Quaternion.CreateFromAxisAngle(axis, angle);
                    rm.Body.Orientation = System.Numerics.Quaternion.Normalize(
                        System.Numerics.Quaternion.Multiply(rm.Body.Orientation, deltaRot));
                }

                // Step 3: integrate physics — retail FUN_005111D0
                // UpdatePhysicsInternal. Pure Euler:
                //   position += velocity × dt + 0.5 × accel × dt²
                //
                // Call UpdatePhysicsInternal DIRECTLY rather than via
                // PhysicsBody.update_object (FUN_00515020). update_object gates
                // on MinQuantum = 1/30s: at our 60fps render tick (~16ms),
                // deltaTime < MinQuantum → early return AND LastUpdateTime is
                // NOT advanced. Net effect: position never integrates between
                // UpdatePositions and the only Body.Position changes come
                // from the UP hard-snap, producing a visible teleport-stride
                // on slopes (the "staircase" the user reported).
                //
                // PlayerMovementController.cs:358 calls UpdatePhysicsInternal
                // directly for the same reason. Remote motion mirrors that.
                // Omega is already integrated manually above, so we zero it
                // here to prevent UpdatePhysicsInternal's own omega pass from
                // double-integrating.
                var preIntegratePos = rm.Body.Position;
                rm.Body.calc_acceleration();
                rm.Body.UpdatePhysicsInternal(dt);
                var postIntegratePos = rm.Body.Position;

                // Step 4: collision sweep — retail FUN_00514B90 →
                // FUN_005148A0 → Transition::FindTransitionalPosition.
                // Projects the sphere from preIntegratePos to postIntegratePos
                // through the BSP + terrain, resolving:
                //   - terrain Z snap along the slope (fixes the "staircase" where
                //     horizontal Euler motion up a slope sinks into rising ground
                //     until the next UP pops it up)
                //   - indoor BSP walls (via the 6-path dispatcher in BSPQuery)
                //   - object collisions via ShadowObjectRegistry
                //   - step-up / step-down against walkable ledges
                // ResolveWithTransition is the same call PlayerMovementController
                // uses for the local player; remotes now get the full retail
                // treatment between UpdatePositions instead of pure kinematics.
                //
                // Skipped when rm.CellId == 0 (no UP landed yet — can't build
                // a SpherePath without a starting cell). One-frame grace until
                // the first UP arrives; harmless because the entity is
                // server-freshly-spawned at a valid Z anyway.
                if (rm.CellId != 0 && _physicsEngine.LandblockCount > 0)
                {
                    // Sphere dims match local-player defaults (human Setup
                    // bounds — ~0.48m radius, ~1.2m height). Good enough for
                    // grounded humanoid remotes; can be setup-derived later
                    // if creatures of wildly different sizes need different
                    // collision profiles.
                    var resolveResult = _physicsEngine.ResolveWithTransition(
                        preIntegratePos, postIntegratePos, rm.CellId,
                        sphereRadius: 0.48f,
                        sphereHeight: 1.2f,
                        stepUpHeight: 2.0f,     // retail default for unknown remotes
                        stepDownHeight: 0.04f,  // PhysicsGlobals.DefaultStepHeight
                        // K-fix9 (2026-04-26): mirror the K-fix7 gate —
                        // airborne remotes must NOT pre-seed the
                        // ContactPlane, otherwise AdjustOffset's snap-to-plane
                        // branch zeroes the +Z offset every step (same bug
                        // we hit on the local jump).
                        isOnGround: !rm.Airborne,
                        body: rm.Body);          // persist ContactPlane across frames for slope tracking

                    rm.Body.Position = resolveResult.Position;
                    if (resolveResult.CellId != 0)
                        rm.CellId = resolveResult.CellId;

                    // K-fix15 (2026-04-26): post-resolve landing
                    // detection for airborne remotes. Mirrors
                    // PlayerMovementController's local-player landing
                    // path: when the resolver says we're on ground AND
                    // velocity is no longer pointing up, transition
                    // back to grounded — clear Airborne, restore
                    // Contact + OnWalkable, remove Gravity, zero any
                    // residual downward velocity, and trigger
                    // HitGround so the sequencer can swap from
                    // Falling → idle/locomotion. Without this, an
                    // airborne remote falls through the floor (gravity
                    // keeps building Velocity.Z negative until the
                    // sphere-sweep clamps each frame, but Airborne
                    // stays true forever).
                    if (rm.Airborne
                        && resolveResult.IsOnGround
                        && rm.Body.Velocity.Z <= 0f)
                    {
                        rm.Airborne = false;
                        rm.Body.TransientState |= AcDream.Core.Physics.TransientStateFlags.Contact
                                                | AcDream.Core.Physics.TransientStateFlags.OnWalkable;
                        rm.Body.State &= ~AcDream.Core.Physics.PhysicsStateFlags.Gravity;
                        rm.Body.Velocity = new System.Numerics.Vector3(
                            rm.Body.Velocity.X, rm.Body.Velocity.Y, 0f);
                        rm.Motion.HitGround();

                        // K-fix17 (2026-04-26): reset the sequencer cycle
                        // from Falling back to whatever the interpreted
                        // motion state says they should be doing now.
                        // Without this, the remote stays in the Falling
                        // pose forever (legs folded) until the next
                        // server-sent UpdateMotion arrives. Use the
                        // sequencer's current style (preserved across
                        // jump) and pick the cycle from
                        // InterpretedState.ForwardCommand: Ready
                        // (idle), WalkForward, RunForward, WalkBackward.
                        // SideStep / Turn aren't strict locomotion
                        // priorities — the next UM the server sends will
                        // refine the cycle if the player is mid-strafe
                        // when they land; this just gets the legs out
                        // of Falling immediately.
                        if (ae.Sequencer is not null)
                        {
                            uint style = ae.Sequencer.CurrentStyle != 0
                                ? ae.Sequencer.CurrentStyle
                                : 0x8000003Du;
                            uint landingCmd = rm.Motion.InterpretedState.ForwardCommand;
                            if (landingCmd == 0)
                                landingCmd = AcDream.Core.Physics.MotionCommand.Ready;
                            float landingSpeed = rm.Motion.InterpretedState.ForwardSpeed;
                            if (landingSpeed <= 0f) landingSpeed = 1f;
                            ae.Sequencer.SetCycle(style, landingCmd, landingSpeed);
                        }

                        if (Environment.GetEnvironmentVariable("ACDREAM_DUMP_MOTION") == "1")
                            Console.WriteLine($"VU.land guid=0x{serverGuid:X8} Z={rm.Body.Position.Z:F2}");
                    }
                }

                ae.Entity.Position = rm.Body.Position;
                ae.Entity.Rotation = rm.Body.Orientation;
            }

            // ── Get per-part (origin, orientation) from either sequencer or legacy ──
            IReadOnlyList<AcDream.Core.Physics.PartTransform>? seqFrames = null;
            if (ae.Sequencer is not null)
            {
                seqFrames = ae.Sequencer.Advance(dt);

                // Phase E.1: drain animation hooks (footstep sounds, attack
                // damage frames, particle spawns, part swaps, etc.) and fan
                // them out to registered subsystems via the hook router.
                // Mirrors ACE's PhysicsObj.add_anim_hook dispatch path.
                var hooks = ae.Sequencer.ConsumePendingHooks();
                if (hooks.Count > 0)
                {
                    System.Numerics.Vector3 worldPos = ae.Entity.Position;
                    for (int hi = 0; hi < hooks.Count; hi++)
                    {
                        var hook = hooks[hi];
                        if (hook is null) continue;
                        _hookRouter.OnHook(ae.Entity.Id, worldPos, hook);
                    }
                }
            }
            else
            {
                // Legacy path (entities without a MotionTable / sequencer).
                int span = ae.HighFrame - ae.LowFrame;
                if (span <= 0) continue;
                ae.CurrFrame += dt * ae.Framerate;
                if (ae.CurrFrame > ae.HighFrame)
                {
                    float over = ae.CurrFrame - ae.LowFrame;
                    ae.CurrFrame = ae.LowFrame + (over % (span + 1));
                }
                else if (ae.CurrFrame < ae.LowFrame)
                    ae.CurrFrame = ae.LowFrame;
            }

            int partCount = ae.PartTemplate.Count;
            var newMeshRefs = new List<AcDream.Core.World.MeshRef>(partCount);
            var scaleMat = ae.Scale == 1.0f
                ? System.Numerics.Matrix4x4.Identity
                : System.Numerics.Matrix4x4.CreateScale(ae.Scale);

            for (int i = 0; i < partCount; i++)
            {
                System.Numerics.Vector3 origin;
                System.Numerics.Quaternion orientation;

                if (seqFrames is not null)
                {
                    // Sequencer path.
                    if (i < seqFrames.Count)
                    {
                        origin = seqFrames[i].Origin;
                        orientation = seqFrames[i].Orientation;
                    }
                    else
                    {
                        origin = System.Numerics.Vector3.Zero;
                        orientation = System.Numerics.Quaternion.Identity;
                    }
                }
                else
                {
                    // Legacy slerp path.
                    int frameIdx = (int)Math.Floor(ae.CurrFrame);
                    if (frameIdx < ae.LowFrame || frameIdx > ae.HighFrame
                        || frameIdx >= ae.Animation.PartFrames.Count)
                        frameIdx = ae.LowFrame;
                    int nextIdx = frameIdx + 1;
                    if (nextIdx > ae.HighFrame || nextIdx >= ae.Animation.PartFrames.Count)
                        nextIdx = ae.LowFrame;
                    float t = ae.CurrFrame - frameIdx;
                    if (t < 0f) t = 0f; else if (t > 1f) t = 1f;
                    var partFrames = ae.Animation.PartFrames[frameIdx].Frames;
                    var partFramesNext = ae.Animation.PartFrames[nextIdx].Frames;
                    if (i < partFrames.Count)
                    {
                        var f0 = partFrames[i];
                        var f1 = i < partFramesNext.Count ? partFramesNext[i] : f0;
                        origin = System.Numerics.Vector3.Lerp(f0.Origin, f1.Origin, t);
                        orientation = System.Numerics.Quaternion.Slerp(f0.Orientation, f1.Orientation, t);
                    }
                    else
                    {
                        origin = System.Numerics.Vector3.Zero;
                        orientation = System.Numerics.Quaternion.Identity;
                    }
                }

                // Per-part default scale from the Setup, matching SetupMesh.Flatten's
                // composition order: scale → rotate → translate.
                var defaultScale = i < ae.Setup.DefaultScale.Count
                    ? ae.Setup.DefaultScale[i]
                    : System.Numerics.Vector3.One;

                var partTransform =
                    System.Numerics.Matrix4x4.CreateScale(defaultScale) *
                    System.Numerics.Matrix4x4.CreateFromQuaternion(orientation) *
                    System.Numerics.Matrix4x4.CreateTranslation(origin);

                // Bake the entity's ObjScale on top, matching the hydration
                // order (PartTransform * scaleMat) — see comment in OnLiveEntitySpawned.
                if (ae.Scale != 1.0f)
                    partTransform = partTransform * scaleMat;

                var template = ae.PartTemplate[i];
                newMeshRefs.Add(new AcDream.Core.World.MeshRef(template.GfxObjId, partTransform)
                {
                    SurfaceOverrides = template.SurfaceOverrides,
                });
            }

            ae.Entity.MeshRefs = newMeshRefs;
        }
    }

    /// <summary>
    /// Phase B.2: switch the locally-controlled player entity's animation cycle
    /// to match the current motion command. Only re-resolves when the command
    /// actually changes (forward → run, idle → walk, etc.) to avoid re-building
    /// the animation entry every frame.
    ///
    /// <para>
    /// Action motions (Jump, FallDown, emotes, attacks) are routed through
    /// <see cref="AcDream.Core.Physics.AnimationSequencer.PlayAction"/> — they
    /// live in the motion table's Modifiers dict, not the Cycles dict, and
    /// are inserted into the queue on top of the current cycle instead of
    /// replacing it.
    /// </para>
    /// </summary>
    private void UpdatePlayerAnimation(AcDream.App.Input.MovementResult result)
    {
        if (_dats is null) return;

        // ── Airborne SubState (Falling) ────────────────────────────────────
        //
        // Retail models the jump-animation as a SubState swap to
        // MotionCommand.Falling (0x40000015) while airborne, NOT as an
        // Action overlay. Empirically verified: Links[(NonCombat,RunForward)]
        // has 3 transitions including 0x40000015 Falling. The SubState cycle
        // for Falling lives in Cycles[(style, Falling)] and loops while
        // airborne. On land, we transition back to whatever SubState the
        // motion input implies (Ready / WalkForward / RunForward).
        //
        // Implementation: force animCommand = Falling when airborne; the
        // existing SetCycle pathway resolves the link + cycle correctly and
        // the transition back happens naturally when airborne becomes false.

        // Determine the animation command: airborne takes priority (Falling
        // SubState), then forward, sidestep, turn, then idle (Ready 0x41000003).
        //
        // Airborne → Falling (retail behavior; see airborne note above).
        // Otherwise: LocalAnimationCommand (RunForward when running) preferred,
        // falling back to wire ForwardCommand (WalkForward / WalkBackward).
        uint animCommand;
        if (!result.IsOnGround)
            animCommand = AcDream.Core.Physics.MotionCommand.Falling;
        else if (result.LocalAnimationCommand is { } localCmd)
            animCommand = localCmd;
        else if (result.ForwardCommand is { } fwd)
            animCommand = fwd;
        else if (result.SidestepCommand is { } ss)
            animCommand = ss;
        else if (result.TurnCommand is { } tc)
            animCommand = tc;
        else
            animCommand = 0x41000003u;  // Ready (idle)

        // Fast path: no command change AND speed delta is negligible. If
        // command is unchanged but speed changed, we must still propagate
        // so the sequencer can MultiplyCyclicFramerate — keeping the run
        // loop smooth without restart.
        // K-fix5 (2026-04-26): use LocalAnimationSpeed (cycle pace) NOT
        // ForwardSpeed (wire field) — backward+run + strafe+run keep
        // ForwardSpeed/SidestepSpeed at 1.0 for ACE compatibility but
        // need the local cycle to play at runRate × so the animation
        // matches the actual movement velocity.
        float newSpeed = result.LocalAnimationSpeed;
        bool sameCmd = animCommand == _playerCurrentAnimCommand;
        bool sameSpeed = MathF.Abs(newSpeed - _playerCurrentAnimSpeed) < 1e-3f;
        if (sameCmd && sameSpeed) return;
        _playerCurrentAnimCommand = animCommand;
        _playerCurrentAnimSpeed = newSpeed;

        if (!_entitiesByServerGuid.TryGetValue(_playerServerGuid, out var pe)) return;

        // The player entity may not be in _animatedEntities if a post-spawn
        // UpdateMotion removed it (Phase 6.8 pattern). In that case, load
        // the Setup and re-register. This is the player's own character so
        // we always want it animated in player mode.
        if (!_animatedEntities.TryGetValue(pe.Id, out var ae))
        {
            var setup = _dats.Get<DatReaderWriter.DBObjs.Setup>(pe.SourceGfxObjOrSetupId);
            if (setup is null) return;
            _physicsDataCache.CacheSetup(pe.SourceGfxObjOrSetupId, setup);

            // Build a minimal part template from the entity's current MeshRefs.
            var template = new (uint, IReadOnlyDictionary<uint, uint>?)[pe.MeshRefs.Count];
            for (int i = 0; i < pe.MeshRefs.Count; i++)
                template[i] = (pe.MeshRefs[i].GfxObjId, pe.MeshRefs[i].SurfaceOverrides);

            ae = new AnimatedEntity
            {
                Entity = pe,
                Setup = setup,
                Animation = null!,  // filled below
                LowFrame = 0,
                HighFrame = 0,
                Framerate = 30f,
                Scale = 1f,
                PartTemplate = template,
                CurrFrame = 0f,
            };
            _animatedEntities[pe.Id] = ae;
        }

        // The motion table cycle key is (style << 16) | (command & 0xFFFFFF).
        // Without a stance override, the resolver uses the table default
        // (which always maps to the idle/Ready cycle regardless of command).
        // Pass the NonCombat stance (0x003D) so the resolver builds the
        // correct cycle key for walk/run/turn commands.
        ushort cmdOverride = (ushort)(animCommand & 0xFFFFu);
        const ushort NonCombatStance = 0x003D;
        var cycle = AcDream.Core.Meshing.MotionResolver.GetIdleCycle(
            ae.Setup, _dats,
            motionTableIdOverride: _playerMotionTableId,
            stanceOverride: NonCombatStance,
            commandOverride: cmdOverride);

        // Sequencer path: SetCycle handles adjust_motion internally
        // (TurnLeft→TurnRight with negative speed, etc.)
        //
        // Speed scaling: K-fix5 (2026-04-26) — use LocalAnimationSpeed
        // (the PlayerMovementController-computed cycle pace) instead of
        // the wire ForwardSpeed. Forward+Run = runRate; Backward+Run =
        // runRate (where ForwardSpeed is the ACE-compatible 1.0);
        // Strafe+Run = runRate (where SidestepSpeed is 1.0). Anything
        // not in run = 1.0. The animation cycle now visually matches
        // the movement velocity in every direction.
        if (ae.Sequencer is not null)
        {
            uint fullStyle = 0x80000000u | (uint)NonCombatStance;
            float animSpeed = result.LocalAnimationSpeed > 0f
                ? result.LocalAnimationSpeed
                : 1f;
            // ACDREAM_ANIM_SPEED_SCALE: optional visual-pacing knob. Retail's
            // animation framerate scales linearly with speedMod (r03 §8.3),
            // and our speedMod = runRate. If the visual feel doesn't match
            // retail, override via env var (default 1.0 = no change).
            float animScale = 1.0f;
            if (float.TryParse(
                    Environment.GetEnvironmentVariable("ACDREAM_ANIM_SPEED_SCALE"),
                    System.Globalization.NumberStyles.Float,
                    System.Globalization.CultureInfo.InvariantCulture,
                    out var s) && s > 0f)
            {
                animScale = s;
            }
            // K-fix18 (2026-04-26): when transitioning into Falling
            // (jump start), skip the link so the legs engage Falling
            // immediately. Without this the local player visibly
            // stood still for ~100 ms at the start of every jump
            // while the RunForward→Falling transition link drained.
            // For everything else (Walk → Run, Run → Ready, etc.) we
            // keep the link so transitions stay smooth.
            bool skipLink = animCommand == AcDream.Core.Physics.MotionCommand.Falling;
            ae.Sequencer.SetCycle(fullStyle, animCommand, animSpeed * animScale,
                skipTransitionLink: skipLink);
        }

        // Legacy path: update the manual slerp fields (for entities without sequencer)
        if (cycle is null || cycle.Framerate == 0f || cycle.HighFrame <= cycle.LowFrame) return;
        ae.Animation = cycle.Animation;
        ae.LowFrame  = Math.Max(0, cycle.LowFrame);
        ae.HighFrame = Math.Min(cycle.HighFrame, cycle.Animation.PartFrames.Count - 1);
        ae.Framerate = cycle.Framerate;
        ae.CurrFrame = ae.LowFrame;
    }

    /// <summary>
    /// Phase 3a — re-roll the active DayGroup whenever the current
    /// Dereth-day index differs from what we last installed. Idempotent
    /// within the same server-day. Swaps both the
    /// <see cref="AcDream.Core.World.SkyStateProvider"/> feeding
    /// <see cref="WorldTime"/> (for lighting interp) and the cached
    /// <see cref="_activeDayGroup"/> (for the sky-object render loop).
    ///
    /// <para>
    /// Honors <c>ACDREAM_DAY_GROUP=N</c> — when set, every call picks
    /// group N regardless of day index. Useful for A/B testing each
    /// weather preset against retail. See
    /// <see cref="AcDream.Core.World.LoadedSkyDesc.SelectDayGroupIndex"/>
    /// for the roller.
    /// </para>
    /// </summary>
    private void RefreshSkyForCurrentDay()
    {
        if (_loadedSkyDesc is null || _loadedSkyDesc.DayGroups.Count == 0)
            return;

        // Retail FUN_00501990 seeds the LCG with the triple stored in
        //   TimeOfDay +0x64 (Year), +0x10 (misc. int), +0x68 (DayOfYear)
        //
        // The decompile agent labeled +0x10 "SecondsPerDay (int copy)"
        // but a live memory probe of retail's acclient.exe (2026-04-23,
        // tools/RetailTimeProbe) shows the value is actually **360** —
        // semantically DaysPerYear, not seconds. So the LCG seed is
        //   seed = Year × DaysPerYear + DayOfYear
        // which is literally "total days since epoch" (a flat day index),
        // confirmed against retail's Year=116, DayOfYear=47, seed=41807.
        //
        // Previously we passed 7620 (DayTicks), producing seed 883967 —
        // a completely different LCG output → wrong DayGroup pick →
        // user-observed weather mismatch (acdream clear while retail
        // stormy, 2026-04-23). The live probe nailed the fix.
        double ticks = WorldTime.NowTicks;
        int absYear = AcDream.Core.World.DerethDateTime.AbsoluteYear(ticks);
        int dayOfYear = AcDream.Core.World.DerethDateTime.DayOfYear(ticks);
        int secondsPerDay = AcDream.Core.World.DerethDateTime.DaysInAMonth
                          * AcDream.Core.World.DerethDateTime.MonthsInAYear;  // 360

        // Composite day key for change-detection and logging only; the
        // LCG seed is computed inside SelectDayGroupIndex from (absYear,
        // secondsPerDay, dayOfYear).
        long dayIndex = (long)absYear * 360 + dayOfYear;

        int idx = _loadedSkyDesc.SelectDayGroupIndex(absYear, secondsPerDay, dayOfYear);
        var grp = idx >= 0 && idx < _loadedSkyDesc.DayGroups.Count
            ? _loadedSkyDesc.DayGroups[idx]
            : null;

        bool dayChanged = dayIndex != _loadedSkyDayIndex;
        bool groupChanged = !ReferenceEquals(grp, _activeDayGroup);

        if (!dayChanged && !groupChanged) return;

        _loadedSkyDayIndex = dayIndex;
        _activeDayGroup = grp;

        if (grp is not null && grp.SkyTimes.Count > 0)
        {
            WorldTime.SetProvider(
                new AcDream.Core.World.SkyStateProvider(
                    grp.SkyTimes.Select(s => s.Keyframe).ToList()));

            // Phase 3e: drive the atmospheric weather (rain/snow emitters,
            // fog-override categories, lightning strobe) from the retail
            // DayGroup name. Stops the legacy WeatherSystem.RollKind hash
            // from spawning rain particles on a "Sunny" day (user-observed
            // rain regression 2026-04-23 after the retail picker landed on
            // DayGroup[6] "Sunny" but the internal hash picked Rain).
            Weather.SetKindFromDayGroupName(grp.Name);

            Console.WriteLine(
                $"sky: PY{absYear} day{dayOfYear} → DayGroup[{idx}] \"{grp.Name}\" " +
                $"(Chance={grp.ChanceOfOccur:F2}, {grp.SkyObjects.Count} objects, " +
                $"{grp.SkyTimes.Count} keyframes, weather={Weather.Kind})");
        }
    }

    /// <summary>
    /// Derive the current sun (directional light, slot 0 of the UBO)
    /// from the interpolated <see cref="AcDream.Core.World.SkyKeyframe"/>,
    /// plus the cell ambient. Indoor cells force the sun intensity to
    /// zero (r13 §13.7) and substitute a fixed dungeon-tone ambient.
    /// </summary>
    private void UpdateSunFromSky(AcDream.Core.World.SkyKeyframe kf, bool cameraInsideCell)
    {
        // Sun direction: points FROM the sun TOWARDS the world. Our
        // shader does dot(N, -forward) so a positive N·L means the
        // surface faces the sun.
        var sunToWorld = -AcDream.Core.World.SkyStateProvider.SunDirectionFromKeyframe(kf);

        if (cameraInsideCell)
        {
            // Dungeon default per r13 §3 — warm-dark ambient, no sun.
            Lighting.Sun = new AcDream.Core.Lighting.LightSource
            {
                Kind = AcDream.Core.Lighting.LightKind.Directional,
                WorldForward = sunToWorld,
                ColorLinear = System.Numerics.Vector3.Zero,
                Intensity = 0f,
                Range = 1f,
            };
            Lighting.CurrentAmbient = new AcDream.Core.Lighting.CellAmbientState(
                AmbientColor: new System.Numerics.Vector3(0.10f, 0.09f, 0.08f),
                SunColor:     System.Numerics.Vector3.Zero,
                SunDirection: sunToWorld);
        }
        else
        {
            // Outdoor: full keyframe sun + ambient. The SkyKeyframe stores
            // raw DirColor + DirBright (and AmbColor + AmbBright) for
            // retail-faithful per-channel keyframe interpolation; the
            // computed `kf.SunColor` / `kf.AmbientColor` properties return
            // the post-multiplied product the shader expects.
            Lighting.Sun = new AcDream.Core.Lighting.LightSource
            {
                Kind = AcDream.Core.Lighting.LightKind.Directional,
                WorldForward = sunToWorld,
                ColorLinear = kf.SunColor,
                Intensity = 1f,
                Range = 1f,
            };
            Lighting.CurrentAmbient = new AcDream.Core.Lighting.CellAmbientState(
                AmbientColor: kf.AmbientColor,
                SunColor:     kf.SunColor,
                SunDirection: sunToWorld);
        }
    }

    // ── Phase I.2 — DebugPanel helpers ────────────────────────────────
    //
    // The ImGui DebugPanel reads through DebugVM closures that ask
    // GameWindow for live state on every frame. The helper methods below
    // are the *named* targets of those closures (and of the F-key
    // shortcuts that share the same actions). Keeping them as methods
    // (vs ad-hoc lambdas where the VM is constructed) means both the
    // panel button and the keybind run the *same* code, so behavior
    // can't drift between the two surfaces.

    /// <summary>Player-mode-aware position source for the DebugPanel.</summary>
    private System.Numerics.Vector3 GetDebugPlayerPosition()
    {
        if (_playerMode && _playerController is not null)
            return _playerController.Position;
        if (_cameraController?.Active is { } cam)
        {
            // Camera world position from inverse of view matrix — same
            // computation used by the scene-lighting UBO each frame.
            System.Numerics.Matrix4x4.Invert(cam.View, out var inv);
            return new System.Numerics.Vector3(inv.M41, inv.M42, inv.M43);
        }
        return System.Numerics.Vector3.Zero;
    }

    /// <summary>Heading in degrees, [0..360). Player yaw in player mode, camera-forward heading otherwise.</summary>
    private float GetDebugPlayerHeadingDeg()
    {
        float deg;
        if (_playerMode && _playerController is not null)
        {
            deg = _playerController.Yaw * (180f / MathF.PI);
        }
        else if (_cameraController?.Active is { } cam)
        {
            // Camera-relative heading from view matrix forward vector. Use
            // the same -invView.Mxx convention the snapshot block used.
            System.Numerics.Matrix4x4.Invert(cam.View, out var inv);
            var fwd = new System.Numerics.Vector3(-inv.M31, -inv.M32, -inv.M33);
            deg = MathF.Atan2(fwd.Y, fwd.X) * (180f / MathF.PI);
        }
        else
        {
            return 0f;
        }
        deg %= 360f;
        if (deg < 0f) deg += 360f;
        return deg;
    }

    private uint GetDebugPlayerCellId() =>
        _playerMode && _playerController is not null ? _playerController.CellId : 0u;

    private bool GetDebugPlayerOnGround() =>
        _playerMode && _playerController is not null && !_playerController.IsAirborne;

    private float GetActiveSensitivity()
    {
        if (_playerMode && _cameraController?.IsChaseMode == true) return _sensChase;
        if (_cameraController?.IsFlyMode == true) return _sensFly;
        return _sensOrbit;
    }

    /// <summary>
    /// Cycle the time-of-day debug override. Same body as the old F7
    /// keybind handler; called by both the keybind AND the DebugPanel
    /// "Cycle time of day" button via DebugVM.CycleTimeOfDay.
    /// </summary>
    private void CycleTimeOfDay()
    {
        // none → 0.0 (midnight) → 0.25 (dawn) → 0.5 (noon) → 0.75 (dusk) → none
        _timeDebugStep = (_timeDebugStep + 1) % 5;
        float? pick = _timeDebugStep switch
        {
            0 => (float?)null,
            1 => 0.0f,
            2 => 0.25f,
            3 => 0.5f,
            4 => 0.75f,
            _ => null,
        };
        if (pick.HasValue)
        {
            WorldTime.SetDebugTime(pick.Value);
            _debugVm?.AddToast($"Time override = {pick.Value:F2}");
        }
        else
        {
            WorldTime.ClearDebugTime();
            _debugVm?.AddToast("Time override cleared");
        }
    }

    /// <summary>
    /// Cycle the weather kind. Same body as the old F10 keybind handler.
    /// </summary>
    private void CycleWeather()
    {
        var kinds = new[]
        {
            AcDream.Core.World.WeatherKind.Clear,
            AcDream.Core.World.WeatherKind.Overcast,
            AcDream.Core.World.WeatherKind.Rain,
            AcDream.Core.World.WeatherKind.Snow,
            AcDream.Core.World.WeatherKind.Storm,
        };
        _weatherDebugStep = (_weatherDebugStep + 1) % kinds.Length;
        Weather.ForceWeather(kinds[_weatherDebugStep]);
        _debugVm?.AddToast($"Weather = {kinds[_weatherDebugStep]}");
    }

    /// <summary>
    /// Toggle the collision-wires debug renderer. Same body as the old
    /// F2 keybind handler.
    /// </summary>
    private void ToggleCollisionWires()
    {
        _debugCollisionVisible = !_debugCollisionVisible;
        _debugVm?.AddToast($"Collision wireframes {(_debugCollisionVisible ? "ON" : "OFF")}");
    }

    /// <summary>
    /// Yields the registered DebugPanel(s) so F1 can flip their
    /// visibility. Returns nothing when devtools are off.
    /// </summary>
    private IEnumerable<AcDream.UI.Abstractions.IPanel> EnumerateDebugPanel()
    {
        // The current ImGuiPanelHost only exposes Register/Unregister,
        // not enumerate. We track the DebugPanel through the VM presence
        // — the panel is registered iff _debugVm is non-null. Look it
        // up via the panel ID convention.
        // Defer the actual lookup to the panel host once it grows an
        // accessor; for now, no-op when devtools are off.
        if (_debugPanel is not null) yield return _debugPanel;
    }

    // Cached panel reference so EnumerateDebugPanel can return it. Set
    // in the DevToolsEnabled construction block above; null otherwise.
    private AcDream.UI.Abstractions.Panels.Debug.DebugPanel? _debugPanel;

    // Cached chat-panel reference so the dispatcher's ToggleChatEntry
    // (Tab) handler can call FocusInput() programmatically. Set in the
    // DevToolsEnabled construction block; null otherwise.
    private AcDream.UI.Abstractions.Panels.Chat.ChatPanel? _chatPanel;

    // Phase K.3 — Settings panel (click-to-rebind keymap UI). Hidden by
    // default; F11 / View → Settings toggles. Null when devtools are off.
    private AcDream.UI.Abstractions.Panels.Settings.SettingsPanel? _settingsPanel;
    private AcDream.UI.Abstractions.Panels.Settings.SettingsVM? _settingsVm;
    // L.0: settings.json store + active toon key. The store is held as
    // a field so BeginLiveSessionAsync can re-load the chosen toon's
    // bag once we know its name (post-EnterWorld). Toon key starts as
    // "default" and gets swapped to the actual character name on the
    // first EnterWorld.
    private AcDream.UI.Abstractions.Panels.Settings.SettingsStore? _settingsStore;
    private string _activeToonKey = "default";
    // L.0 follow-up: persisted-settings cache populated by
    // LoadAndApplyPersistedSettings (runs unconditionally in OnLoad,
    // not gated on DevToolsEnabled). The Settings PANEL construction
    // — which IS gated on devtools — reads these fields when wiring
    // SettingsVM. Defaults are placeholders; LoadAndApplyPersistedSettings
    // overwrites them with values from settings.json (or per-section
    // defaults when the file is missing/corrupt).
    private AcDream.UI.Abstractions.Panels.Settings.DisplaySettings _persistedDisplay
        = AcDream.UI.Abstractions.Panels.Settings.DisplaySettings.Default;
    private AcDream.UI.Abstractions.Panels.Settings.AudioSettings _persistedAudio
        = AcDream.UI.Abstractions.Panels.Settings.AudioSettings.Default;
    private AcDream.UI.Abstractions.Panels.Settings.GameplaySettings _persistedGameplay
        = AcDream.UI.Abstractions.Panels.Settings.GameplaySettings.Default;
    private AcDream.UI.Abstractions.Panels.Settings.ChatSettings _persistedChat
        = AcDream.UI.Abstractions.Panels.Settings.ChatSettings.Default;
    private AcDream.UI.Abstractions.Panels.Settings.CharacterSettings _persistedCharacter
        = AcDream.UI.Abstractions.Panels.Settings.CharacterSettings.Default;

    /// <summary>
    /// L.0 follow-up: load every section from settings.json + apply the
    /// runtime-affecting ones (Display window state + Audio engine
    /// volumes) at startup. Runs unconditionally — settings are runtime
    /// state, not devtools state. Without this, a user running with
    /// <c>ACDREAM_DEVTOOLS=0</c> would silently get WindowOptions
    /// defaults instead of their saved Display/Audio preferences.
    /// </summary>
    private void LoadAndApplyPersistedSettings()
    {
        _settingsStore = new AcDream.UI.Abstractions.Panels.Settings.SettingsStore(
            AcDream.UI.Abstractions.Panels.Settings.SettingsStore.DefaultPath());
        _persistedDisplay   = _settingsStore.LoadDisplay();
        _persistedAudio     = _settingsStore.LoadAudio();
        _persistedGameplay  = _settingsStore.LoadGameplay();
        _persistedChat      = _settingsStore.LoadChat();
        // _activeToonKey is "default" pre-EnterWorld; the post-login
        // branch in BeginLiveSessionAsync swaps to the chosen toon's
        // name and re-loads via SettingsVM.LoadCharacterContext.
        _persistedCharacter = _settingsStore.LoadCharacter(_activeToonKey);

        // Apply Display to the Silk.NET window. VSync goes via the
        // window property; resolution + fullscreen go through
        // ApplyDisplayWindowState which is shared with the on-Save path.
        if (_window is not null)
        {
            if (_window.VSync != _persistedDisplay.VSync)
                _window.VSync = _persistedDisplay.VSync;
            ApplyDisplayWindowState(_persistedDisplay);
        }

        // Apply Audio to the OpenAL engine. Master + Sfx are wired
        // through to the engine; Music + Ambient are stored but inert
        // until R5 MIDI/ambient-loop engines exist (assigning them is
        // harmless — the engine just doesn't read them yet).
        if (_audioEngine is not null && _audioEngine.IsAvailable)
        {
            _audioEngine.MasterVolume  = _persistedAudio.Master;
            _audioEngine.MusicVolume   = _persistedAudio.Music;
            _audioEngine.SfxVolume     = _persistedAudio.Sfx;
            _audioEngine.AmbientVolume = _persistedAudio.Ambient;
        }
    }

    /// <summary>
    /// L.0 Display tab: framebuffer-resize handler — update GL viewport
    /// + camera aspect when the window is resized (by the user dragging
    /// the corner OR by ApplyDisplayWindowState applying a saved
    /// Resolution). Without this, the viewport stays pinned at the
    /// startup size, producing a small render inside a big window.
    /// Also force-resets ImGui panel layout so panels that were
    /// previously off the new viewport snap back to default positions.
    /// </summary>
    private void OnFramebufferResize(Silk.NET.Maths.Vector2D<int> newSize)
    {
        if (newSize.X <= 0 || newSize.Y <= 0) return;
        _gl?.Viewport(0, 0, (uint)newSize.X, (uint)newSize.Y);
        _cameraController?.SetAspect(newSize.X / (float)newSize.Y);
        // Resize is always a force-reset — the alternative ("clamp
        // existing positions") would require tracking each panel's
        // current pos+size, which ImGuiNET doesn't expose by name.
        // Force-reset is acceptable UX because resizing happens rarely
        // and the user can always drag panels back where they want.
        if (DevToolsEnabled && _imguiBootstrap is not null)
            ResetPanelLayout(ImGuiNET.ImGuiCond.Always);
    }

    /// <summary>
    /// L.0 Display tab: position every registered panel to its default
    /// landing spot, computed relative to the current window size so
    /// the layout adapts to any resolution. Called from:
    /// <list type="bullet">
    ///   <item>OnFramebufferResize (cond=Always — force-reset on resize).</item>
    ///   <item>The View → "Reset window layout" menu item (cond=Always).</item>
    ///   <item>OnLoad after panel registration (cond=FirstUseEver — only
    ///         applies when imgui.ini has no saved position for that
    ///         panel; on subsequent launches the saved positions win).</item>
    /// </list>
    /// </summary>
    private void ResetPanelLayout(ImGuiNET.ImGuiCond cond)
    {
        if (_window is null) return;
        float w = _window.Size.X;
        float h = _window.Size.Y;
        // Sane minimums so the math doesn't blow up on a tiny window.
        if (w < 480) w = 480;
        if (h < 320) h = 320;

        // Panel positions chosen to be classic-MMO discoverable on a
        // 1280x720 window: vitals top-left under the menu bar, chat
        // bottom-left, debug top-right, settings centered. All sizes
        // are reasonable defaults the user can resize from.
        SetPanelLayout(_vitalsPanel?.Title,    new System.Numerics.Vector2(10f, 30f),
                                                 new System.Numerics.Vector2(220f, 110f), cond);
        SetPanelLayout(_chatPanel?.Title,      new System.Numerics.Vector2(10f, h - 320f),
                                                 new System.Numerics.Vector2(450f, 300f), cond);
        SetPanelLayout(_debugPanel?.Title,     new System.Numerics.Vector2(w - 380f, 30f),
                                                 new System.Numerics.Vector2(370f, 520f), cond);
        SetPanelLayout(_settingsPanel?.Title,  new System.Numerics.Vector2((w - 700f) * 0.5f, (h - 500f) * 0.5f),
                                                 new System.Numerics.Vector2(700f, 500f), cond);
    }

    private static void SetPanelLayout(
        string? title,
        System.Numerics.Vector2 pos,
        System.Numerics.Vector2 size,
        ImGuiNET.ImGuiCond cond)
    {
        if (string.IsNullOrEmpty(title)) return;
        // SetWindowPos/SetWindowSize by name work even when the window
        // has never been Begin'd — ImGui stores the value for next
        // appearance.
        ImGuiNET.ImGui.SetWindowPos(title, pos, cond);
        ImGuiNET.ImGui.SetWindowSize(title, size, cond);
    }

    /// <summary>
    /// L.0 Display tab: apply the window-state-dependent settings
    /// (Resolution + Fullscreen) from a <see cref="AcDream.UI.Abstractions.Panels.Settings.DisplaySettings"/>
    /// to the live Silk.NET window. Called at startup (with persisted
    /// values) and on every Save (with the saved values). Resolution
    /// parses "<c>WIDTHxHEIGHT</c>" (e.g. <c>"1920x1080"</c>); a malformed
    /// or unparseable string is silently ignored to avoid crashing the
    /// client mid-session.
    /// </summary>
    private void ApplyDisplayWindowState(
        AcDream.UI.Abstractions.Panels.Settings.DisplaySettings display)
    {
        if (_window is null) return;

        // Resolution: parse and resize if changed.
        if (TryParseResolution(display.Resolution, out int w, out int h))
        {
            if (_window.Size.X != w || _window.Size.Y != h)
                _window.Size = new Silk.NET.Maths.Vector2D<int>(w, h);
        }

        // Fullscreen: borderless via Silk.NET's WindowState.Fullscreen
        // (no exclusive-mode DXGI dance needed).
        var desiredState = display.Fullscreen
            ? Silk.NET.Windowing.WindowState.Fullscreen
            : Silk.NET.Windowing.WindowState.Normal;
        if (_window.WindowState != desiredState)
            _window.WindowState = desiredState;
    }

    private static bool TryParseResolution(string spec, out int width, out int height)
    {
        width = height = 0;
        if (string.IsNullOrWhiteSpace(spec)) return false;
        var parts = spec.Split('x', 2);
        if (parts.Length != 2) return false;
        return int.TryParse(parts[0], out width)
            && int.TryParse(parts[1], out height)
            && width > 0
            && height > 0;
    }
    // Vitals panel reference cached for the View menu's toggle entry.
    private AcDream.UI.Abstractions.Panels.Vitals.VitalsPanel? _vitalsPanel;

    // ── K.1b: dispatcher action handler ──────────────────────────────────
    //
    // SINGLE place where every game-side keyboard/mouse-button reaction
    // lives. The legacy direct kb.KeyDown switch + mouse.MouseDown/MouseUp
    // handlers are gone; everything now flows through InputDispatcher.Fired
    // → here. New behaviors register a new InputAction in the enum + a
    // case in this switch + a binding in KeyBindings.

    /// <summary>
    /// K.1b — multicast subscriber on <see cref="InputDispatcher.Fired"/>.
    /// Handles every game-side reaction to a keyboard/mouse-button chord.
    /// Per-frame held-state polling (movement WASD/Shift/Space) lives in
    /// <see cref="OnUpdate"/> via <see cref="InputDispatcher.IsActionHeld"/>;
    /// this method handles transitional Press/Release events only.
    /// </summary>
    private void OnInputAction(
        AcDream.UI.Abstractions.Input.InputAction action,
        AcDream.UI.Abstractions.Input.ActivationType activation)
    {
        // Diagnostic — kept from K.1a; helpful for K.1c verification.
        Console.WriteLine($"[input] {action} {activation}");

        // RMB-orbit hold: track press/release transitions explicitly so
        // _rmbHeld is true exactly while the chord is held. Hold-type
        // chords also fire Press on key-down + Release on key-up; we
        // ignore the in-between Hold ticks here (the mouse-move handler
        // checks _rmbHeld each frame anyway).
        if (action == AcDream.UI.Abstractions.Input.InputAction.AcdreamRmbOrbitHold)
        {
            if (activation == AcDream.UI.Abstractions.Input.ActivationType.Press)
                _rmbHeld = _playerMode && _cameraController?.IsChaseMode == true;
            else if (activation == AcDream.UI.Abstractions.Input.ActivationType.Release)
                _rmbHeld = false;
            return;
        }

        // Phase K.2 — MMB-hold instant mouse-look. Press hides the
        // cursor + activates yaw drive; release restores. WantCapture
        // edge handling lives in OnUpdate; only Press needs to read it
        // for the initial gate (defense in depth — the dispatcher
        // already filters on WantCaptureMouse in OnMouseDown).
        if (action == AcDream.UI.Abstractions.Input.InputAction.CameraInstantMouseLook)
        {
            if (_mouseLook is null) return;
            if (activation == AcDream.UI.Abstractions.Input.ActivationType.Press)
            {
                bool wcm = DevToolsEnabled && ImGuiNET.ImGui.GetIO().WantCaptureMouse;
                _mouseLook.Press(_lastMouseX, _lastMouseY, wcm);
                if (_mouseLook.Active) HideCursorForMouseLook();
            }
            else if (activation == AcDream.UI.Abstractions.Input.ActivationType.Release)
            {
                bool wasActive = _mouseLook.Active;
                _mouseLook.Release();
                if (wasActive) RestoreCursorAfterMouseLook();
            }
            return;
        }

        // ScrollUp / ScrollDown — emit by InputDispatcher.OnScroll on every
        // wheel tick. Press is the only activation type for wheel.
        if (action == AcDream.UI.Abstractions.Input.InputAction.ScrollUp
            || action == AcDream.UI.Abstractions.Input.InputAction.ScrollDown)
        {
            if (activation != AcDream.UI.Abstractions.Input.ActivationType.Press) return;
            HandleScrollAction(action);
            return;
        }

        // Every other action fires on Press only (no Release / Hold side-
        // effects in the K.1b set). Filter out non-Press activations early
        // so subscribers that have Release-mode bindings don't accidentally
        // re-fire.
        if (activation != AcDream.UI.Abstractions.Input.ActivationType.Press) return;

        // K-fix1 (2026-04-26): Q is autorun TOGGLE, not hold-to-run. Press
        // Q to start, press Q again to stop. Pressing Backup / Stop /
        // StrafeLeft / StrafeRight while autorun is active also cancels it
        // — retail-faithful: any deliberate movement input wins. (Pressing
        // Forward AGAIN does NOT cancel — retail's autorun stays active
        // even when you press W; the two stack.)
        if (action == AcDream.UI.Abstractions.Input.InputAction.MovementRunLock)
        {
            _autoRunActive = !_autoRunActive;
            return;
        }
        if (_autoRunActive
            && (action == AcDream.UI.Abstractions.Input.InputAction.MovementBackup
             || action == AcDream.UI.Abstractions.Input.InputAction.MovementStop
             || action == AcDream.UI.Abstractions.Input.InputAction.MovementStrafeLeft
             || action == AcDream.UI.Abstractions.Input.InputAction.MovementStrafeRight))
        {
            _autoRunActive = false;
            // Fall through — these actions still need their normal handling
            // (e.g. Stop is currently a no-op in the switch, but keeping the
            // fall-through means future logic fires).
        }

        switch (action)
        {
            case AcDream.UI.Abstractions.Input.InputAction.AcdreamToggleDebugPanel:
                foreach (var panel in EnumerateDebugPanel())
                {
                    panel.IsVisible = !panel.IsVisible;
                    _debugVm?.AddToast($"Debug panel {(panel.IsVisible ? "ON" : "OFF")}");
                }
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamToggleCollisionWires:
                ToggleCollisionWires();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamDumpNearby:
                DumpPlayerAndNearbyEntities();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamCycleTimeOfDay:
                CycleTimeOfDay();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamSensitivityDown:
                AdjustActiveSensitivity(1f / 1.2f);
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamSensitivityUp:
                AdjustActiveSensitivity(1.2f);
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamCycleWeather:
                CycleWeather();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamToggleFlyMode:
                // K-fix3 (2026-04-26): proper round-trip when player has
                // an active chase camera. ToggleFly() only swaps
                // Fly↔Orbit, so a user who flew out of player mode used
                // to land in Holtburg-orbit on toggle-back. With a chase
                // camera available, prefer Fly→Chase / Chase→Fly so the
                // user round-trips back to the same player view.
                ToggleFlyOrChase();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.AcdreamTogglePlayerMode:
                TogglePlayerMode();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.ToggleChatEntry:
                // K.2: Tab focuses the chat input. ChatPanel.FocusInput()
                // sets a one-shot flag that emits SetKeyboardFocusHere on
                // the next render. No-op when devtools/_chatPanel is null
                // (offline / non-devtools build) — the dispatcher still
                // logs the action via the [input] diagnostic above so the
                // path is observable in either case.
                _chatPanel?.FocusInput();
                break;

            case AcDream.UI.Abstractions.Input.InputAction.ToggleOptionsPanel:
                // K.3: F11 toggles the Settings panel. Null-safe vs.
                // devtools-off / panel-not-registered — the [input] log
                // line above still records the press regardless.
                if (_settingsPanel is not null)
                    _settingsPanel.IsVisible = !_settingsPanel.IsVisible;
                break;

            case AcDream.UI.Abstractions.Input.InputAction.EscapeKey:
                if (_cameraController?.IsFlyMode == true)
                    _cameraController.ToggleFly();  // exit fly, release cursor
                else if (_playerMode)
                {
                    _playerMode = false;
                    _cameraController?.ExitChaseMode();
                    _playerController = null;
                    _chaseCamera = null;
                    _playerCurrentAnimCommand = null;
                }
                else
                    _window!.Close();
                break;
        }
    }

    /// <summary>
    /// K.1b: Tab handler extracted into a method so the dispatcher
    /// subscriber can call it. Same body as the previous Tab branch in
    /// the legacy direct keyboard handler — toggle player↔fly mode, set
    /// up <see cref="PlayerMovementController"/> + <see cref="ChaseCamera"/>
    /// when entering player mode, tear them down on exit.
    /// K.2: also disarms the auto-entry trigger when the user toggles
    /// manually (their choice wins).
    /// </summary>
    private void TogglePlayerMode()
    {
        // Phase B.2 guard: only active when a live session is in-world.
        if (_liveSession is null
            || _liveSession.CurrentState != AcDream.Core.Net.WorldSession.State.InWorld)
            return;

        // Manual toggle pre-empts the K.2 auto-entry trigger regardless
        // of direction — entering means "I'm in player mode now"; exiting
        // means "I want fly, don't snap me back".
        _playerModeAutoEntry?.Cancel();

        _playerMode = !_playerMode;
        if (_playerMode)
        {
            if (!EnterPlayerModeNow(loggingTag: "Tab"))
                _playerMode = false;
        }
        else
        {
            _cameraController?.ExitChaseMode();
            _playerController = null;
            _chaseCamera = null;
            _playerCurrentAnimCommand = null;
            _playerMouseDeltaX = 0f;
        }
    }

    /// <summary>
    /// K.2: callback the <see cref="AcDream.App.Input.PlayerModeAutoEntry"/>
    /// guard invokes once login + entity stream + controller readiness
    /// have all converged. Sets <c>_playerMode = true</c> and runs the
    /// same construction path the manual Tab handler uses. Predicates on
    /// the guard already guarantee <c>_entitiesByServerGuid</c> contains
    /// the player guid, so the inner TryGetValue is a fast-path success.
    /// </summary>
    private void EnterPlayerModeFromAutoEntry()
    {
        _playerMode = true;
        if (!EnterPlayerModeNow(loggingTag: "auto-entry"))
        {
            // Defense in depth: if construction failed (e.g. entity
            // disappeared between predicate eval and here) drop back
            // out cleanly. Re-arm so a later Tab still works.
            _playerMode = false;
        }
        else
        {
            Console.WriteLine($"live: auto-entered player mode for 0x{_playerServerGuid:X8}");
        }
    }

    /// <summary>
    /// K-fix3 (2026-04-26): the right "toggle free-fly mode" routine
    /// when a chase camera is in play. <see cref="CameraController.ToggleFly"/>
    /// only knows Fly↔Orbit and would strand a player-mode user in the
    /// orbit camera (Holtburg view) when they exit fly. This wrapper
    /// gives the round-trip the user actually wants:
    /// <list type="bullet">
    /// <item>Chase → Fly: cancel auto-entry (user's choice wins) and
    /// switch to fly camera while keeping <c>_playerMode = true</c> +
    /// the chase camera alive so we can return.</item>
    /// <item>Fly → Chase: when <c>_playerMode</c> is still true and the
    /// chase camera survived, re-enter chase via
    /// <see cref="CameraController.EnterChaseMode"/>.</item>
    /// <item>Otherwise (no chase available): the original Fly↔Orbit
    /// toggle for offline / pre-login flows.</item>
    /// </list>
    /// </summary>
    private void ToggleFlyOrChase()
    {
        if (_cameraController is null) return;
        _playerModeAutoEntry?.Cancel();

        if (_cameraController.IsFlyMode
            && _playerMode
            && _chaseCamera is not null)
        {
            _cameraController.EnterChaseMode(_chaseCamera);
            return;
        }
        _cameraController.ToggleFly();
    }

    /// <summary>
    /// K.2: shared "construct controller + chase camera + enter chase
    /// mode" body extracted from the on-enter branch of
    /// <see cref="TogglePlayerMode"/>. Returns false when the player
    /// entity isn't in <c>_entitiesByServerGuid</c> yet — caller must
    /// reset <c>_playerMode</c> in that case.
    /// </summary>
    private bool EnterPlayerModeNow(string loggingTag)
    {
        if (!_entitiesByServerGuid.TryGetValue(_playerServerGuid, out var playerEntity))
        {
            Console.WriteLine($"live: {loggingTag} — player entity 0x{_playerServerGuid:X8} not found yet");
            return false;
        }

        _playerController = new AcDream.App.Input.PlayerMovementController(_physicsEngine);
        // K-fix7 (2026-04-26): if PlayerDescription already arrived, the
        // server's Run / Jump skill values are cached here — push them
        // into the freshly-constructed controller so the runRate /
        // jump-arc formulas use real character data instead of the
        // hardcoded ACDREAM_*_SKILL defaults. PD always arrives at
        // login before auto-entry fires, so this branch normally hits.
        if (_lastSeenRunSkill >= 0 && _lastSeenJumpSkill >= 0)
        {
            _playerController.SetCharacterSkills(_lastSeenRunSkill, _lastSeenJumpSkill);
            Console.WriteLine($"live: {loggingTag} — applied server skills run={_lastSeenRunSkill} jump={_lastSeenJumpSkill}");
        }
        // Read the real step height from the player's Setup dat.
        if (_dats is not null && (playerEntity.SourceGfxObjOrSetupId & 0xFF000000u) == 0x02000000u)
        {
            var playerSetup = _dats.Get<DatReaderWriter.DBObjs.Setup>(playerEntity.SourceGfxObjOrSetupId);
            if (playerSetup is not null)
                _physicsDataCache.CacheSetup(playerEntity.SourceGfxObjOrSetupId, playerSetup);
            _playerController.StepUpHeight = (playerSetup is not null && playerSetup.StepUpHeight > 0f)
                ? playerSetup.StepUpHeight
                : 2f;
        }
        else
        {
            _playerController.StepUpHeight = 2f;
        }
        int plbX = _liveCenterX + (int)MathF.Floor(playerEntity.Position.X / 192f);
        int plbY = _liveCenterY + (int)MathF.Floor(playerEntity.Position.Y / 192f);
        uint pinitCellId = ((uint)plbX << 24) | ((uint)plbY << 16) | 0x0001u;
        var initResult = _physicsEngine.Resolve(
            playerEntity.Position, pinitCellId & 0xFFFFu,
            System.Numerics.Vector3.Zero, 100f);
        _playerController.SetPosition(initResult.Position, initResult.CellId);

        if (_animatedEntities.TryGetValue(playerEntity.Id, out var playerAE)
            && playerAE.Sequencer is { } playerSeq)
        {
            _playerController.AttachCycleVelocityAccessor(() => playerSeq.CurrentVelocity);
        }

        var q = playerEntity.Rotation;
        float rawYaw = MathF.Atan2(
            2f * (q.W * q.Z + q.X * q.Y),
            1f - 2f * (q.Y * q.Y + q.Z * q.Z));
        _playerController.Yaw = rawYaw + MathF.PI / 2f;

        _chaseCamera = new AcDream.App.Rendering.ChaseCamera
        {
            Aspect = _window!.Size.X / (float)_window.Size.Y,
        };
        // K.1b: _playerMouseDeltaX is no longer consumed by
        // MovementInput, but we still reset it here so any stale
        // accumulated value from a previous session doesn't leak
        // into a future code path that re-enables mouse-yaw.
        _playerMouseDeltaX = 0f;
        _cameraController?.EnterChaseMode(_chaseCamera);
        // K-fix1 (2026-04-26): latch the "we have entered chase at least
        // once" flag so the live-mode pre-login render gate stops
        // suppressing the scene. From here on, the orbit camera (if the
        // user ever returns to it via Escape) shows whatever's loaded —
        // we don't re-blank the world.
        _chaseModeEverEntered = true;
        return true;
    }

    /// <summary>
    /// Phase K.2: hide the system cursor while MMB instant mouse-look is
    /// held. Saves the previous CursorMode so <see cref="RestoreCursorAfterMouseLook"/>
    /// can put it back exactly. Skips when no mouse / no input — tests
    /// and headless runs stay clean.
    /// </summary>
    private void HideCursorForMouseLook()
    {
        if (_input is null) return;
        var mouse = _input.Mice.FirstOrDefault();
        if (mouse is null) return;
        // Save previous mode (Normal in orbit, Raw in chase/fly) so the
        // exact pre-hold mode is restored on release.
        _mouseLookSavedCursorMode = mouse.Cursor.CursorMode;
        mouse.Cursor.CursorMode = CursorMode.Hidden;
    }

    /// <summary>
    /// Phase K.2: restore the saved cursor mode after MMB instant
    /// mouse-look ends. Called from the Release branch and from the
    /// WantCaptureMouse-edge suspend path so the cursor never gets
    /// stuck hidden.
    /// </summary>
    private void RestoreCursorAfterMouseLook()
    {
        if (_input is null) return;
        var mouse = _input.Mice.FirstOrDefault();
        if (mouse is null) return;
        if (_mouseLookSavedCursorMode is { } saved)
        {
            mouse.Cursor.CursorMode = saved;
            _mouseLookSavedCursorMode = null;
        }
        else
        {
            // Defense in depth: never observed the saved value, fall
            // back to Normal so the user always gets a visible cursor.
            mouse.Cursor.CursorMode = CursorMode.Normal;
        }
    }

    /// <summary>
    /// K.1b: F8/F9 sensitivity adjust extracted into a helper. Multiplies
    /// the currently-active mode's sensitivity (chase / fly / orbit) by the
    /// given factor and clamps to [0.005, 3.0].
    /// </summary>
    private void AdjustActiveSensitivity(float factor)
    {
        string modeLabel;
        float current;
        if (_playerMode && _cameraController?.IsChaseMode == true)
        { modeLabel = "Chase"; current = _sensChase; }
        else if (_cameraController?.IsFlyMode == true)
        { modeLabel = "Fly";   current = _sensFly; }
        else
        { modeLabel = "Orbit"; current = _sensOrbit; }

        float next = MathF.Min(3.0f, MathF.Max(0.005f, current * factor));
        if (modeLabel == "Chase") _sensChase = next;
        else if (modeLabel == "Fly") _sensFly = next;
        else _sensOrbit = next;
        _debugVm?.AddToast($"{modeLabel} sens {next:F3}x");
    }

    /// <summary>
    /// K.1b: F3 dump handler extracted into a method. Same body as the
    /// previous in-line F3 branch — prints the player's position +
    /// nearby visible entities + nearby shadow physics objects.
    /// </summary>
    private void DumpPlayerAndNearbyEntities()
    {
        System.Numerics.Vector3 pos;
        if (_playerMode && _playerController is not null)
            pos = _playerController.Position;
        else
        {
            System.Numerics.Matrix4x4.Invert(_cameraController!.Active.View, out var iv);
            pos = new System.Numerics.Vector3(iv.M41, iv.M42, iv.M43);
        }
        int lbX = _liveCenterX + (int)MathF.Floor(pos.X / 192f);
        int lbY = _liveCenterY + (int)MathF.Floor(pos.Y / 192f);
        Console.WriteLine(
            $"=== F3 DEBUG DUMP ===\n" +
            $"  player pos=({pos.X:F2},{pos.Y:F2},{pos.Z:F2})\n" +
            $"  landblock=0x{(uint)((lbX<<24)|(lbY<<16)|0xFFFF):X8} local=({pos.X - (lbX-_liveCenterX)*192f:F2},{pos.Y - (lbY-_liveCenterY)*192f:F2})\n" +
            $"  total shadow objects: {_physicsEngine.ShadowObjects.TotalRegistered}");

        var visibleNearby = new List<AcDream.Core.World.WorldEntity>();
        foreach (var e in _worldState.Entities)
        {
            float dx = e.Position.X - pos.X;
            float dy = e.Position.Y - pos.Y;
            if (dx * dx + dy * dy < 15f * 15f) visibleNearby.Add(e);
        }
        Console.WriteLine($"  VISIBLE entities within 15m: {visibleNearby.Count}");
        foreach (var e in visibleNearby.OrderBy(e => (e.Position - pos).Length()).Take(12))
        {
            float d = (e.Position - pos).Length();
            Console.WriteLine(
                $"    VIS  id=0x{e.Id:X8} src=0x{e.SourceGfxObjOrSetupId:X8} " +
                $"pos=({e.Position.X:F2},{e.Position.Y:F2},{e.Position.Z:F2}) dist={d:F2} scale={e.Scale:F2}");
        }

        var sorted = new List<(AcDream.Core.Physics.ShadowEntry obj, float dist)>();
        foreach (var o in _physicsEngine.ShadowObjects.AllEntriesForDebug())
        {
            float dx = o.Position.X - pos.X;
            float dy = o.Position.Y - pos.Y;
            float d = MathF.Sqrt(dx * dx + dy * dy);
            if (d < 15f) sorted.Add((o, d));
        }
        sorted.Sort((a, b) => a.dist.CompareTo(b.dist));
        Console.WriteLine($"  SHADOW objects within 15m: {sorted.Count}");
        foreach (var (o, d) in sorted.Take(12))
        {
            Console.WriteLine(
                $"    SHAD id=0x{o.EntityId:X8} {o.CollisionType} r={o.Radius:F2} h={o.CylHeight:F2} " +
                $"pos=({o.Position.X:F2},{o.Position.Y:F2},{o.Position.Z:F2}) dist={d:F2}");
        }
    }

    /// <summary>
    /// K.1b: ScrollUp / ScrollDown action handler. Adjusts whichever
    /// camera distance is current — chase camera distance in player mode,
    /// orbit camera distance otherwise. Fly mode ignores scroll. Magnitude
    /// is fixed-step (the previous proportional scroll.Y was lost when we
    /// moved scroll into the dispatcher, but the discrete step matches
    /// retail wheel feel).
    /// </summary>
    private void HandleScrollAction(AcDream.UI.Abstractions.Input.InputAction action)
    {
        if (_cameraController is null) return;
        float dir = (action == AcDream.UI.Abstractions.Input.InputAction.ScrollUp) ? 1f : -1f;

        if (_playerMode && _cameraController.IsChaseMode && _chaseCamera is not null)
        {
            // Chase mode: zoom (closer on ScrollUp).
            _chaseCamera.AdjustDistance(-dir * 0.8f);
        }
        else if (_cameraController.IsFlyMode)
        {
            // Fly mode: no-op (could adjust move speed later).
        }
        else
        {
            _cameraController.Orbit.Distance = Math.Clamp(
                _cameraController.Orbit.Distance - dir * 20f, 50f, 2000f);
        }
    }

    private void OnClosing()
    {
        // Phase A.1: join the streamer worker thread before tearing down GL
        // state. The worker may still be processing a load job that references
        // _dats; Dispose cancels the token and waits up to 2s for the thread.
        _streamer?.Dispose();
        // Phase I.7: unsubscribe combat → chat translator before the
        // session it depends on goes away.
        _combatChatTranslator?.Dispose();
        _liveSession?.Dispose();
        _audioEngine?.Dispose();  // Phase E.2: stop all voices, close AL context
        _staticMesh?.Dispose();
        _textureCache?.Dispose();
        _meshShader?.Dispose();
        _terrain?.Dispose();
        _shader?.Dispose();
        _sceneLightingUbo?.Dispose();
        _skyRenderer?.Dispose();
        _particleRenderer?.Dispose();
        _debugLines?.Dispose();
        _textRenderer?.Dispose();
        _debugFont?.Dispose();
        _dats?.Dispose();
        _input?.Dispose();
        _gl?.Dispose();
    }

    public void Dispose() => _window?.Dispose();

    // ── Phase I.6 — TurbineChat outbound helpers ──────────────────

    /// <summary>
    /// Result of resolving a UI <see cref="AcDream.UI.Abstractions.ChatChannelKind"/>
    /// to a runtime Turbine room. Returned by
    /// <see cref="ResolveTurbineForKind"/> when the player has access
    /// to that Turbine channel; null otherwise.
    /// </summary>
    private readonly record struct TurbineResolution(uint RoomId, uint ChatType, string DisplayName);

    /// <summary>
    /// Map a <see cref="AcDream.UI.Abstractions.ChatChannelKind"/> to a
    /// runtime Turbine room id + chat-type. Returns null when
    /// <paramref name="state"/> isn't <see cref="AcDream.Core.Chat.TurbineChatState.Enabled"/>
    /// or the channel has no assigned room (e.g. player not in a society).
    /// Mirrors holtburger's <c>resolve_turbine_channel</c>
    /// (<c>references/holtburger/.../client/commands.rs</c> lines 64-98).
    /// </summary>
    private static TurbineResolution? ResolveTurbineForKind(
        AcDream.UI.Abstractions.ChatChannelKind kind,
        AcDream.Core.Chat.TurbineChatState state)
    {
        if (!state.Enabled) return null;

        var (room, chatType, name) = kind switch
        {
            AcDream.UI.Abstractions.ChatChannelKind.Allegiance =>
                (state.AllegianceRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.Allegiance, "Allegiance"),
            AcDream.UI.Abstractions.ChatChannelKind.General =>
                (state.GeneralRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.General, "General"),
            AcDream.UI.Abstractions.ChatChannelKind.Trade =>
                (state.TradeRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.Trade, "Trade"),
            AcDream.UI.Abstractions.ChatChannelKind.Lfg =>
                (state.LfgRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.Lfg, "LFG"),
            AcDream.UI.Abstractions.ChatChannelKind.Roleplay =>
                (state.RoleplayRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.Roleplay, "Roleplay"),
            AcDream.UI.Abstractions.ChatChannelKind.Society =>
                (state.SocietyRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.Society, "Society"),
            AcDream.UI.Abstractions.ChatChannelKind.Olthoi =>
                (state.OlthoiRoom, (uint)AcDream.Core.Net.Messages.TurbineChat.ChatType.Olthoi, "Olthoi"),
            _ => (0u, 0u, string.Empty),
        };

        if (room == 0u) return null;
        return new TurbineResolution(room, chatType, name);
    }

    /// <summary>
    /// Pick a human-readable label for a Turbine room broadcast. Uses
    /// the chat-type when known (semantic name), falls back to the
    /// numeric room id for unknown rooms.
    /// </summary>
    private static string TurbineRoomDisplayName(uint roomId, uint chatType)
    {
        return (AcDream.Core.Net.Messages.TurbineChat.ChatType)chatType switch
        {
            AcDream.Core.Net.Messages.TurbineChat.ChatType.Allegiance    => "Allegiance",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.General       => "General",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.Trade         => "Trade",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.Lfg           => "LFG",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.Roleplay      => "Roleplay",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.Society       => "Society",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.SocietyCelHan => "Celestial Hand",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.SocietyEldWeb => "Eldrytch Web",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.SocietyRadBlo => "Radiant Blood",
            AcDream.Core.Net.Messages.TurbineChat.ChatType.Olthoi        => "Olthoi",
            _ => $"Room 0x{roomId:X8}",
        };
    }
}