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.Plot.cs

@@ -4,6 +4,39 @@ using SceneMethods = Ananta.Server.RpcTypes.Client4229938.Methods.GameScene;
 
 namespace Ananta.Server.Handlers.Game;
 
+/// <summary>
+/// 环境 NPC 的<b>剧情 / 刺激事件收尾</b>（2026-10-02 自 7k-v0.6 捐赠端
+/// <c>GameRouter.Plot.cs</c> 移植，三个全是 <b>Notify</b>）。
+///
+/// <para>★ 它<b>不驱动任务剧情</b>，只维护一个账本
+/// <c>WorldEntryState.StaticNpcPreparedPlotEvents[agentEntityId]</c>
+/// （= 这个环境 NPC 当前挂着哪条剧情事件，0 表示没有）。
+/// 这条账本主线<b>早就有了</b>（<c>WorldEntryState.cs:27</c>，注释里就写着
+/// "GameRouter.Plot uses it"，但主线一直没有 Plot 文件 ⇒ 从来没人真正消费它）。
+/// 铺市民 / DonorNpc / FunctionalNpc / RosterNpc 在生成时都会 <c>[id] = 0</c> 播种，
+/// 骰子对手离场时 <c>Remove(id)</c>。</para>
+///
+/// <para>★ 三条的语义：</para>
+/// <list type="number">
+/// <item><c>AskPreparePlotEvent</c>(67966346)：客户端说「这个 NPC 准备演 event X」⇒ 记账。</item>
+/// <item><c>AskEndPreparePlotEvent</c>(67025961)：准备结束 ⇒ 清账。</item>
+/// <item><c>AskTriggerPlotEvent</c>(67895788)：<b>演完了</b>，进入服务端反应阶段。
+/// 我们的环境 NPC <b>没有剧情后续</b>，所以显式把它关掉 —— 发
+/// <c>SyncPlotCurrentEvent(AgentEntityId, EventId=0)</c>，让客户端
+/// <c>SelectStimOnline</c> 不再拿「已经演完的那条事件」的优先级下限去压新的刺激。
+/// 只有账本里 pending 的那条对得上才发（<c>TryCompleteStaticNpcPlot</c>）。</item>
+/// </list>
+///
+/// <para>⛑ 游戏里的可见效果：环境 NPC 演完一次反应（被撞、被喊、盘查反应……）之后
+/// <b>能回到待机、能接受下一次刺激</b>，而不是卡在那条已完成的反应上不理人。</para>
+///
+/// <para>⛑ 坐标必须是有限数（<c>HasFinitePosition</c>）：捐赠端用这个挡掉
+/// 客户端偶尔发出来的 NaN / Infinity，避免日志和下游逻辑被脏数据带偏。</para>
+///
+/// <para>⛑ 回滚：把三个 <c>MethodId.*</c> 从 <c>GameRouter.cs</c> 的
+/// <c>Enabled4229938MethodIds</c> 里删掉即可 —— Notify 不回包，
+/// 不注册只是回到 <c>DefaultUnknownNotify4229938</c>（接受 + 打日志），不会卡客户端。</para>
+/// </summary>
 internal sealed partial class GameRouter
 {
     [Handler(MethodId.AskPreparePlotEvent, HandlerPacketKind.Notify)]
@@ -46,7 +79,7 @@ internal sealed partial class GameRouter
     }
 
     [Handler(MethodId.AskTriggerPlotEvent, HandlerPacketKind.Notify)]
-    private Task AskTriggerPlotEvent(Connection conn, UxRpcMessage msg)
+    private async Task AskTriggerPlotEvent(Connection conn, UxRpcMessage msg)
     {
         if (msg.Body.Length != SceneMethods.AskTriggerPlotEventArgs4229938.WireSize
             || !msg.TryGetArgs<SceneMethods.AskTriggerPlotEventArgs4229938>(out var args)
@@ -54,7 +87,7 @@ internal sealed partial class GameRouter
             || !HasFinitePosition(args.Parameter.Source2))
         {
             conn.Log.Warn($"[PLOT] AskTriggerPlotEvent invalid payload bytes={msg.Body.Length}");
-            return Task.CompletedTask;
+            return;
         }
 
         conn.Log.Info($"[PLOT] AskTriggerPlotEvent event={args.EventId} agent={args.AgentEntityId} "
@@ -66,12 +99,16 @@ internal sealed partial class GameRouter
         if (TryCompleteStaticNpcPlot(GetStateIfExists(conn.Session), args.AgentEntityId, args.EventId))
         {
             conn.Log.Info($"[PLOT] AMBIENT_RESPONSE_FINISHED agent={args.AgentEntityId} event={args.EventId} currentEvent=0");
-            return conn.NotifyAsync(MethodId.SyncPlotCurrentEvent,
+            await conn.NotifyAsync(MethodId.SyncPlotCurrentEvent,
                 new SceneMethods.SyncPlotCurrentEvent4229938 { AgentEntityId = args.AgentEntityId });
         }
-        return Task.CompletedTask;
     }
 
+    /// <summary>
+    /// 账本里这条 NPC 挂着的确实是 <paramref name="eventId"/> 就清成 0（表示「演完了」）。
+    /// <c>EventId == 0</c> 或账本里没有这个 NPC ⇒ 返回 false（不关、不发 SyncPlotCurrentEvent），
+    /// 免得把服务端没参与过的反应误关掉。
+    /// </summary>
     internal static bool TryCompleteStaticNpcPlot(WorldEntryState? state, ulong agentId, uint eventId)
     {
         if (state is null || eventId == 0) return false;