feat: Upgrade server with HyNB v2.4 modular architecture, minigames, admin GM web panel, companion summons, and car radio

Ananta.Server/Ananta.Handlers/Game/GameRouter.Metro.cs

@@ -2,9 +2,7 @@ using Ananta.SDK.Network;
 using Ananta.SDK.Rpc;
 using Ananta.SDK.Serialization;
 using Ananta.Server.ClientData.Client4229938;
-using Ananta.Server.Gameplay.Traffic;
 using Ananta.Server.Protocol.Client4229938;
-using GameMethods = Ananta.Server.RpcTypes.Client4229938.Methods.Game;
 using SceneMethods = Ananta.Server.RpcTypes.Client4229938.Methods.GameScene;
 
 namespace Ananta.Server.Handlers.Game;
@@ -21,11 +19,32 @@ namespace Ananta.Server.Handlers.Game;
 /// The schedule comes straight out of the client's own Rail*Config tables (RailLineConfig /
 /// RailStopConfig / RailStationConfig), which the panel exposes as "where is the train, which stop is
 /// it at, how long / how far until the next one".
+///
+/// Round 54 got the scheduling right but not the clock: see MetroDefaultTimeFactor for the round-55 fix.
 /// </summary>
 internal sealed partial class GameRouter
 {
     private const string MetroKey = "client4229938-metro";
-    private const int MetroDefaultPushMs = 250;
+
+    /// <summary>
+    /// 玩家在轨道附近时的推送周期。250 ms（4 Hz）原本是全程恒定值，实测
+    /// `SyncRunningMetroInfos` 占了 S2C 总字节的 54%（11 分钟 1312 包 / 682 KB，每包 37 列车）。
+    /// 现在 1000 ms 是基准，远离轨道时再降到 <see cref="MetroIdlePushMs"/>。
+    /// ⛑️ 安全前提：列车位置由**客户端**自己沿烘焙好的 MetroPath 推进
+    /// （MetroManager 负责，见本文件顶部说明），服务端推的 ElapsedTime 只是对时锚点。
+    /// 所以降频不会让车"卡住"，只影响纠偏粒度。若观感变差，把面板的推送周期调回 250 即可。
+    /// </summary>
+    private const int MetroDefaultPushMs = 1000;
+
+    /// <summary>玩家远离轨道时的推送周期。列车看不见，慢一点没有代价。</summary>
+    private const int MetroIdlePushMs = 3000;
+
+    /// <summary>
+    /// "看得见列车"的半径（世界单位 ≈ 米）：玩家到**最近轨道段**的距离小于它就用
+    /// <see cref="MetroDefaultPushMs"/>，否则用 <see cref="MetroIdlePushMs"/>。
+    /// 按轨道段而不是车站算，因为相邻车站间距可达 1 km，只按车站判会把大半条线漏掉。
+    /// </summary>
+    private const double MetroNearTrackRadius = 300.0;
 
     /// <summary>
     /// ElapsedTime is a reading of the *server* clock, not a scene second count. The client converts it
@@ -35,19 +54,56 @@ internal sealed partial class GameRouter
     /// is real seconds (the Bayshore ring takes 1123 s for roughly 12 m/s between its stations), so what
     /// we push has to be the timetable second multiplied by 15.
     /// Pushing the raw timetable second made every carriage sit around the beginning of its own line
-    /// crawling at 1/15 speed, which is exactly what round 55 was called in to fix.
+    /// crawling at 1/15 speed, which is exactly what round 55 was called in to fix. The factor is exposed
+    /// on the panel so the two other candidates (1 and 1/15) can be tested without a rebuild.
     /// </summary>
     private const double MetroDefaultTimeFactor = 15.0;
 
     /// <summary>
-    /// Lines enabled on a fresh session: the four city light-rail rings
-    /// (1 = Bayshore inner, 2 = Bayshore outer, 3 = Central, 4 = East).
-    /// The Chongxiao lines 9..14 and the developer test paths 5..8 belong to other scenes, so they stay
-    /// off until the panel turns them on - the client cannot find a MetroPath for a line the loaded
-    /// scene does not contain.
+    /// 兜底线路：只在「当前 raid 没配 <c>LightRailLineIds</c>」或「还没进世界、拿不到 raid」时用。
+    /// 正常情况下推的是 <see cref="MetroLinesForRaid"/> 的结果。
+    ///
+    /// 为什么不能全局固定这四条：它们是新启（raid 23300888）的环线。凌云/重霄（23300999）配的是
+    /// 9–14（+15 画舫），客户端为那六条线烘焙的走行路径是另一套（<c>LightRailPath_cx*_upline/downline</c>）。
+    /// 在凌云里推 1–4，客户端按新启的路径跑车 ⇒ 车不在凌云的铁轨上。
     /// </summary>
     private static readonly uint[] MetroDefaultLines = [1, 2, 3, 4];
 
+    /// <summary>
+    /// 当前 raid 该推哪几条线。取 <c>RaidConfig.LightRailLineIds</c>
+    /// （23300888 = 1–4，23300999 = 9–14 + 15，23301227 = 5–8，23301271 = 1–4），
+    /// 取不到就落回 <see cref="MetroDefaultLines"/>。
+    /// </summary>
+    private static uint[] MetroLinesForRaid(TcpSession session)
+    {
+        var raidId = GetStateIfExists(session)?.ActiveRaidId ?? 0u;
+        var lines = RailCatalog4229938.LinesForRaid(raidId);
+        return lines.Count > 0 ? lines.ToArray() : MetroDefaultLines;
+    }
+
+    /// <summary>
+    /// raid 变了就把自动选的线换掉。手动模式（<see cref="MetroSessionState.AutoRaidLines"/> = false，
+    /// 即面板显式下发过 lines）**一个字都不动**，免得和用户手选打架。
+    /// 返回 true = 这次真的换过了，调用方负责打日志。
+    /// </summary>
+    private static bool SyncMetroLinesToRaid(TcpSession session, MetroSessionState owner, bool force = false)
+    {
+        var raidId = GetStateIfExists(session)?.ActiveRaidId ?? 0u;
+        lock (owner.SyncRoot)
+        {
+            if (!owner.AutoRaidLines)
+                return false;
+            // 已经有线且 raid 没变 ⇒ 什么都不做（避免每次 tick 都重建集合）。
+            if (!force && owner.AutoRaidId == raidId && owner.Lines.Count > 0)
+                return false;
+
+            var lines = RailCatalog4229938.LinesForRaid(raidId);
+            owner.Lines = lines.Count > 0 ? [.. lines] : [.. MetroDefaultLines];
+            owner.AutoRaidId = raidId;
+            return true;
+        }
+    }
+
     internal sealed class MetroSessionState
     {
         internal object SyncRoot { get; } = new();
@@ -58,12 +114,22 @@ internal sealed partial class GameRouter
         /// <summary>Push cadence in milliseconds.</summary>
         internal int PushMs = MetroDefaultPushMs;
 
-        /// <summary>Multiplier applied to the timetable second before it goes out as ElapsedTime.</summary>
+        /// <summary>Multiplier applied to the timetable second before it goes out as ElapsedTime (see MetroDefaultTimeFactor).</summary>
         internal double TimeFactor = MetroDefaultTimeFactor;
 
         /// <summary>Lines currently being pushed.</summary>
         internal HashSet<uint> Lines = [];
 
+        /// <summary>
+        /// 线路跟随当前 raid（<c>RaidConfig.LightRailLineIds</c>）自动切换。
+        /// 面板一旦显式下发 <c>lines</c> 就置 false —— 之后不再自动改，避免和用户手选打架；
+        /// 要切回自动，面板走 <c>auto: true</c>。
+        /// </summary>
+        internal bool AutoRaidLines = true;
+
+        /// <summary>上次自动选线时用的 raid。只在它变化时才重建 <see cref="Lines"/>。</summary>
+        internal uint AutoRaidId;
+
         /// <summary>
         /// The scene has actually asked for the metro list at least once. Pushes stay silent until then:
         /// the client only has its MetroPaths after it has loaded the scene, so an early
@@ -71,6 +137,12 @@ internal sealed partial class GameRouter
         /// </summary>
         internal bool Requested;
 
+        /// <summary>
+        /// 上一拍玩家是否处在轨道附近。只用来在切换时打一条日志，避免在控制台刷屏。
+        /// 初值 true = 还没拿到玩家坐标时按"近处"处理，不牺牲画面。
+        /// </summary>
+        internal bool NearTrack = true;
+
         /// <summary>Seconds of service folded away by a previous stop, so a restart does not jump the trains.</summary>
         internal double OffsetSeconds;
 
@@ -99,7 +171,8 @@ internal sealed partial class GameRouter
                 return existing;
 
             var created = new MetroSessionState();
-            foreach (var id in MetroDefaultLines)
+            created.AutoRaidId = GetStateIfExists(session)?.ActiveRaidId ?? 0u;
+            foreach (var id in MetroLinesForRaid(session))
                 created.Lines.Add(id);
             session.Items[MetroKey] = created;
             return created;
@@ -126,22 +199,27 @@ internal sealed partial class GameRouter
 
     /// <summary>
     /// The scene asks once per load, with no arguments, and expects the list of metros currently
-    /// running. Answering with an empty/placeholder list is why no carriage ever appeared before.
+    /// running. Everything before round 54 answered with the typed-default empty list, which is why no
+    /// carriage ever appeared.
     /// </summary>
-    [Handler(MethodId.AskGetAllMetroInfos, HandlerPacketKind.Invoke)]
+    [Handler(MethodId.AskGetAllMetroInfos)]
     private async Task AskGetAllMetroInfos(Connection conn, UxRpcMessage msg)
     {
         var owner = GetMetroState(msg.Context.Session);
+        // 场景刚加载完，raid 可能是新的（切地区 / 传送）⇒ 先按新 raid 重选一次线路，
+        // 再回答"现在有哪些车"，否则会把上一个 raid 的线一路推下去。
+        if (SyncMetroLinesToRaid(msg.Context.Session, owner))
+            conn.Log.Info($"[METRO] raid -> {owner.AutoRaidId}, lines=[{MetroLineSummary(owner)}]");
         lock (owner.SyncRoot)
             owner.Requested = true;
 
         var infos = BuildMetroInfos(owner);
-        conn.Log.Info($"[METRO] AskGetAllMetroInfos -> {infos.Count} train(s) lines=[{MetroLineSummary(owner)}]");
+        conn.Log.Info($"[METRO] AskGetAllMetroInfos -> {infos.Count} train(s) lines=[{MetroLineSummary(owner)}] raid={owner.AutoRaidId}");
         await conn.ReturnAsync(msg, infos);
         EnsureMetroLoop(msg.Context.Session, owner);
     }
 
-    private static List<GameMethods.MetroClientInfo> BuildMetroInfos(MetroSessionState owner)
+    private static List<SceneMethods.MetroClientInfo> BuildMetroInfos(MetroSessionState owner)
     {
         List<uint> lines;
         double elapsed;
@@ -153,7 +231,7 @@ internal sealed partial class GameRouter
             timeFactor = owner.TimeFactor;
         }
 
-        var result = new List<GameMethods.MetroClientInfo>();
+        var result = new List<SceneMethods.MetroClientInfo>();
         foreach (var lineId in lines)
         {
             if (!RailCatalog4229938.TryGetLine(lineId, out var line))
@@ -164,7 +242,7 @@ internal sealed partial class GameRouter
             var count = line.EffectiveTrainCount;
             for (var i = 0; i < count; i++)
             {
-                result.Add(new GameMethods.MetroClientInfo
+                result.Add(new SceneMethods.MetroClientInfo
                 {
                     Id = (int)((lineId * 100) + (uint)i),
                     LineId = lineId,
@@ -176,6 +254,93 @@ internal sealed partial class GameRouter
         return result;
     }
 
+    // ------------------------------------------------- 轨道邻近度（决定推送频率）
+
+    /// <summary>
+    /// 所有线路的轨道段（相邻车站连线，环线额外补一条首尾段），只按到这些线段的距离判断
+    /// 玩家是否看得见列车。车站只有 34 个、线路 4 条，缓存一次即可。
+    /// </summary>
+    private static readonly Lazy<List<(RailStation4229938 A, RailStation4229938 B)>> MetroTrackSegments =
+        new(BuildMetroTrackSegments);
+
+    private static List<(RailStation4229938 A, RailStation4229938 B)> BuildMetroTrackSegments()
+    {
+        var segments = new List<(RailStation4229938, RailStation4229938)>();
+        foreach (var line in RailCatalog4229938.AllLines)
+        {
+            if (!RailCatalog4229938.TryGetRoute(line.Id, out var route))
+                continue;
+
+            var pts = new List<RailStation4229938>();
+            foreach (var stop in route.Stops)
+            {
+                if (RailCatalog4229938.TryGetStation(stop.StationId, out var station))
+                    pts.Add(station);
+            }
+            if (pts.Count < 2)
+                continue;
+
+            for (var i = 0; i + 1 < pts.Count; i++)
+                segments.Add((pts[i], pts[i + 1]));
+            if (line.RingLine && pts.Count >= 3)
+                segments.Add((pts[^1], pts[0]));
+        }
+        return segments;
+    }
+
+    /// <summary>点到轨道折线的最近距离（米）。段数为几十，每拍算一次开销可忽略。</summary>
+    private static double DistanceToMetroTrack(double px, double py, double pz)
+    {
+        var best = double.MaxValue;
+        foreach (var (a, b) in MetroTrackSegments.Value)
+        {
+            var abx = b.X - a.X;
+            var aby = b.Y - a.Y;
+            var abz = b.Z - a.Z;
+            var apx = px - a.X;
+            var apy = py - a.Y;
+            var apz = pz - a.Z;
+
+            var denom = abx * abx + aby * aby + abz * abz;
+            var t = denom > 0 ? (apx * abx + apy * aby + apz * abz) / denom : 0.0;
+            if (t < 0) t = 0; else if (t > 1) t = 1;
+
+            var dx = apx - abx * t;
+            var dy = apy - aby * t;
+            var dz = apz - abz * t;
+            var d = Math.Sqrt(dx * dx + dy * dy + dz * dz);
+            if (d < best)
+                best = d;
+        }
+        return best;
+    }
+
+    /// <summary>
+    /// 玩家是否看得见列车。拿不到坐标时返回 true（按近处处理），宁可多推也不牺牲画面。
+    /// </summary>
+    private static bool IsPlayerNearMetroTrack(TcpSession session, out double metres)
+    {
+        metres = -1;
+        // 轨道表没加载出来就无从判断，按近处处理（保持原频率），不要悄悄把地铁停掉。
+        if (MetroTrackSegments.Value.Count == 0)
+            return true;
+
+        var state = GetStateIfExists(session);
+        if (state is null || !state.HasLastReportedPlayerTransform)
+            return true;
+
+        double px, py, pz;
+        lock (state.SyncRoot)
+        {
+            px = state.LastReportedPlayerPosition.X;
+            py = state.LastReportedPlayerPosition.Y;
+            pz = state.LastReportedPlayerPosition.Z;
+        }
+
+        metres = DistanceToMetroTrack(px, py, pz);
+        return metres <= MetroNearTrackRadius;
+    }
+
     private static string MetroLineSummary(MetroSessionState owner)
     {
         lock (owner.SyncRoot)
@@ -191,7 +356,9 @@ internal sealed partial class GameRouter
         {
             try
             {
-                await TickMetroAsync(session, owner, token);
+                // 客户端挂起期间只睡不推 —— 见 GameRouter.IsBackgroundPushPaused 的说明。
+                if (!IsBackgroundPushPaused(session))
+                    await TickMetroAsync(session, owner, token);
             }
             catch (OperationCanceledException)
             {
@@ -213,9 +380,25 @@ internal sealed partial class GameRouter
             lock (owner.SyncRoot)
                 period = owner.PushMs;
 
+            // 远离轨道时降频。列车位置由客户端自己推进，ElapsedTime 只是对时锚点，
+            // 所以慢推不会让车卡住；玩家一旦靠近，下一拍立刻恢复常速并把时间校准回来。
+            var nearTrack = IsPlayerNearMetroTrack(session, out var metres);
+            bool modeChanged;
+            lock (owner.SyncRoot)
+            {
+                modeChanged = owner.NearTrack != nearTrack;
+                owner.NearTrack = nearTrack;
+            }
+            if (modeChanged)
+                session.Log.Info($"[METRO] cadence -> {(nearTrack ? "normal" : "idle")} " +
+                                 $"({period}ms / {MetroIdlePushMs}ms, nearest track " +
+                                 (metres < 0 ? "unknown" : $"{metres:F0}m") + ")");
+
+            var sleep = nearTrack ? period : Math.Max(period, MetroIdlePushMs);
+
             try
             {
-                await Task.Delay(Math.Clamp(period, 50, 2000), token);
+                await Task.Delay(Math.Clamp(sleep, 50, 10000), token);
             }
             catch (OperationCanceledException)
             {
@@ -227,6 +410,11 @@ internal sealed partial class GameRouter
 
     private static async Task TickMetroAsync(TcpSession session, MetroSessionState owner, CancellationToken token)
     {
+        // raid 也可能在**没有**重新 Ask 的情况下变掉（GM 传送 / 跨地区切场景不打招呼），
+        // 每拍顺手核一次。AutoRaidLines=false（面板手选过）时这里是 no-op。
+        if (SyncMetroLinesToRaid(session, owner))
+            session.Log.Info($"[METRO] raid -> {owner.AutoRaidId}, lines=[{MetroLineSummary(owner)}]");
+
         lock (owner.SyncRoot)
         {
             owner.Ticks++;
@@ -253,7 +441,7 @@ internal sealed partial class GameRouter
             session.Log.Info($"[METRO] push #{pushes} trains={infos.Count} lines=[{MetroLineSummary(owner)}]");
     }
 
-    // ---------------------------------------------------------------- panel API (future wiring)
+    // ---------------------------------------------------------------- panel API
 
     /// <summary>
     /// Read-only snapshot for the web panel: the whole catalog plus, for every running train, the stop
@@ -272,6 +460,11 @@ internal sealed partial class GameRouter
                 ok = true,
                 online = true,
                 started = false,
+                enabled = false,
+                running = false,
+                requested = false,
+                autoRaidLines = true,
+                raidId = 0u,
                 lines = MetroCatalogView([]),
                 trains = Array.Empty<object>(),
                 message = "the scene has not requested the metro list yet",
@@ -282,6 +475,8 @@ internal sealed partial class GameRouter
         int pushMs;
         double timeFactor;
         bool requested;
+        bool autoRaidLines;
+        uint raidId;
         long ticks, pushes, trainsSent;
         string? lastError;
         double elapsed;
@@ -293,6 +488,8 @@ internal sealed partial class GameRouter
             pushMs = owner.PushMs;
             timeFactor = owner.TimeFactor;
             requested = owner.Requested;
+            autoRaidLines = owner.AutoRaidLines;
+            raidId = owner.AutoRaidId;
             ticks = owner.Ticks;
             pushes = owner.Pushes;
             trainsSent = owner.TrainsSent;
@@ -312,6 +509,8 @@ internal sealed partial class GameRouter
             running,
             requested,
             pushMs,
+            autoRaidLines,
+            raidId,
             timeFactor = Math.Round(timeFactor, 4),
             ticks,
             pushes,
@@ -486,24 +685,106 @@ internal sealed partial class GameRouter
     }
 
     /// <summary>
-    /// Initial intersection list for SyncAetherAIInitDatas: one entry per mapped intersection
-    /// ZONE (InterZones.json — real city zone-graph indexes), carrying its current light
-    /// period, so the client's MassTraffic can resolve each entry against its baked
-    /// StaticIntersectionData blob and run ambient traffic from the moment the scene loads.
+    /// Panel update of the dispatcher. <paramref name="lines"/> null keeps the current selection (that is
+    /// how the panel changes only the push period or the time factor), an empty list turns every line off.
     /// </summary>
+    internal static object ConfigureMetroLines(TcpSession? session, IReadOnlyList<uint>? lines, int? pushMs, double? timeFactor, bool? auto = null)
+    {
+        if (session is null)
+            return new { ok = false, error = "session offline" };
+
+        var owner = GetMetroState(session);
+        var known = new List<uint>();
+        var unknown = new List<uint>();
+        var seen = new HashSet<uint>();
+        foreach (var id in lines ?? [])
+        {
+            if (!seen.Add(id))
+                continue;
+            if (RailCatalog4229938.TryGetLine(id, out _))
+                known.Add(id);
+            else
+                unknown.Add(id);
+        }
+
+        string lineLog;
+
+        // 先把「按 raid 重选」做完再进 lock：SyncMetroLinesToRaid 自己会锁 SyncRoot 并去读
+        // session.Items，嵌套进来会和 tick 线程（先 session.Items 后 SyncRoot）撞成 ABBA。
+        if (auto == true)
+        {
+            lock (owner.SyncRoot)
+                owner.AutoRaidLines = true;
+            SyncMetroLinesToRaid(session, owner, force: true);
+        }
+
+        lock (owner.SyncRoot)
+        {
+            if (auto == true)
+                lineLog = $"auto -> [{string.Join(",", owner.Lines.OrderBy(x => x))}] (raid {owner.AutoRaidId})";
+            else if (lines is not null)
+            {
+                // 显式下发过 lines ⇒ 转手动，之后 raid 变了也不再自动改，免得和用户手选打架。
+                owner.AutoRaidLines = false;
+                owner.Lines = [.. known];
+                lineLog = $"-> [{string.Join(",", known)}] (manual, raid-follow off)";
+            }
+            else
+            {
+                lineLog = $"kept [{string.Join(",", owner.Lines.OrderBy(x => x))}]";
+            }
+
+            if (pushMs is > 0)
+                owner.PushMs = Math.Clamp(pushMs.Value, 50, 2000);
+            if (timeFactor is > 0)
+                owner.TimeFactor = Math.Clamp(timeFactor.Value, 0.0001, 1000);
+        }
+        session.Log.Info($"[METRO] lines {lineLog}" +
+            (unknown.Count > 0 ? $" (unknown ignored: {string.Join(",", unknown)})" : string.Empty) +
+            $" push={owner.PushMs}ms timeFactor={owner.TimeFactor:0.####}");
+        EnsureMetroLoop(session, owner);
+        return MetroStatus(session);
+    }
+
+    internal static object StopMetro(TcpSession? session)
+    {
+        if (session is null)
+            return new { ok = false, error = "session offline" };
+
+        var owner = TryGetMetroState(session);
+        if (owner is null)
+            return new { ok = true, stopped = false, message = "not running" };
+
+        CancellationTokenSource? cts;
+        lock (owner.SyncRoot)
+        {
+            owner.OffsetSeconds += (DateTime.UtcNow - owner.StartedUtc).TotalSeconds;
+            owner.StartedUtc = DateTime.UtcNow;
+            owner.Requested = false;
+            cts = owner.Cts;
+            owner.Cts = null;
+            owner.Loop = null;
+        }
+        cts?.Cancel();
+        cts?.Dispose();
+
+        session.Log.Info("[METRO] stopped by the panel (the client keeps the carriages it already has)");
+        return new { ok = true, stopped = true, status = MetroStatus(session) };
+    }
+
     internal static List<SceneMethods.ClientTrafficIntersectionInitInfo4229938> BuildAetherIntersectionInitList()
     {
         var result = new List<SceneMethods.ClientTrafficIntersectionInitInfo4229938>();
-        if (!CityTrafficEngine.Instance.AmbientIntersectionInit)
+        if (!Ananta.Server.Gameplay.Traffic.CityTrafficEngine.Instance.AmbientIntersectionInit)
             return result;
-        foreach (var zonePeriod in CityTrafficEngine.Instance
+        foreach (var zonePeriod in Ananta.Server.Gameplay.Traffic.CityTrafficEngine.Instance
             .GetAetherIntersectionZonePeriods(DateTimeOffset.UtcNow.ToUnixTimeSeconds()))
         {
             result.Add(new SceneMethods.ClientTrafficIntersectionInitInfo4229938
             {
                 InstanceId = zonePeriod.InstanceId,
                 ZoneIndex = zonePeriod.ZoneIndex,
-                CurrentState = 0, // MassTrafficIntersectionState.Start
+                CurrentState = 0,
                 CurrentPeriodIndex = zonePeriod.CurrentPeriod,
                 NextPeriodIndex = zonePeriod.NextPeriod,
                 RailPeriodIndex = 0,