1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

flowchart TB
    subgraph Client["Unity 客户端"]
        GE[GameEntry]
        DS[DebugService]
        HUD[NormalGameUIInputView / NormalHud]
        NET[OnlineSession + OnlineHudCoordinator]
        GE -->|单机| DS
        GE -->|联机| NET
        DS --> HUD
        NET --> HUD
    end

    subgraph Server["ASP.NET 服务端"]
        HUB[GameHub SignalR]
        GLS[GameLoopService]
        SDH[ServerDebugHost]
        FP[FlowPublisher]
        HUB --> GLS
        GLS --> SDH
        SDH --> FP
        FP --> HUB
    end

    subgraph Core["GameCore 共享"]
        GS[GameSession]
        FC[FlowController]
        SK[SkillExecutor]
        IT[ItemService]
        FC --> GS
        GS --> SK
        GS --> IT
    end

    DS --> FC
    SDH --> FC
    HUB <-->|FlowStep / SubmitDecision| NET

1
2
3
4
5
6
7

NewRingGame.Server
├── Auth/           登录、注册、Token 签发与校验
├── Lobby/          在线玩家、房间列表
├── Room/           房间生命周期、准备状态、AI 补位、自动开局
├── Game/           GameLoopService、ServerDebugHost、FlowPublisher、MatchStore
├── Connection/     WebSocket 连接映射、断线清理
└── Hubs/GameHub    SignalR 实时消息入口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

public class GameSession
{
    public Random Random { get; private set; }
    public GameEventBus EventBus { get; } = new();
    public GameStateStack StateStack { get; } = new();
    public SkillExecutor SkillExecutor { get; } = new();
    public ItemService ItemService { get; private set; }
    public ChamberState Chamber { get; } = new();
    public TurnPhase CurrentPhase { get; private set; }
    public string TurnOwnerId { get; private set; }
    public FlowController Flow { get; private set; }
    public IDebugHost Debug { get; }

    public GameSession(IDebugHost debug)
    {
        Debug = debug;
        ItemService = new ItemService(SkillExecutor, Random);
        AI = new AIDecisionMaker(this);
        Flow = new FlowController(this);
    }
}

1

TurnStart(0) → MainAction(1) → Judgment(2) → Discard(3) → TurnEnd(4)

1
2
3
4
5
6
7
8

public class GameStateStack
{
    private readonly Stack<FlowStackEntry> _stack = new();
    public FlowStackEntry Peek() => _stack.Count > 0 ? _stack.Peek() : null;
    public void Push(FlowStackEntry entry) => _stack.Push(entry);
    public FlowStackEntry Pop() => _stack.Count > 0 ? _stack.Pop() : null;
    public int Count => _stack.Count;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

public IEnumerator RunGameCoroutine()
{
    yield return PresentStartingDealsIfAny();

    while (!_session.IsGameOver)
    {
        var player = _session.GetCurrentTurnPlayer();
        if (player == null) { _session.SetGameOver(); break; }

        _session.SetTurnOwner(player);
        player.ShootLockedThisTurn = false;

        yield return RunTurnCoroutine(player);
        if (_session.IsGameOver) break;

        _session.AdvanceTurn();
        PushAuthoritativeHudSnapshot(FlowBoundaryKind.TurnChange);
    }
}

1
2
3
4
5
6
7
8

public IEnumerator RunTurnCoroutine(PlayerEntity player)
{
    yield return RunTurnStartPhase(player);
    yield return RunMainActionPhase(player);
    yield return RunJudgmentPhase(player);
    yield return RunDiscardPhase(player);
    RunTurnEndPhase(player);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

flowchart TD
    A[TurnStart 发道具装弹] --> B[MainAction 主行动循环]
    B --> C{操作类型}
    C -->|Shoot| D[压栈 ShootResponse]
    D --> E[顺时针响应轮询]
    E --> F[Pop 栈 + ResolveShoot]
    F --> G{目标濒死?}
    G -->|是| H[HandlePlayerDying 压栈]
    H --> B
    G -->|否| B
    C -->|UseItem| I[ExecuteUseItem 即时结算]
    I --> B
    C -->|EndAction| J[Judgment 裁决]
    J --> K[Discard 弃牌]
    K --> L[TurnEnd]
    L --> M[AdvanceTurn]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

private IEnumerator RunMainActionPhase(PlayerEntity player)
{
    _session.Debug.NotifyPhase(_session, TurnPhase.MainAction, player);
    var ended = false;
    var failedShootAttempts = 0;

    while (!ended && player.IsAlive)
    {
        PlayerDecision decision = null;
        yield return _session.Debug.RequestMainActionDecision(player, _session, d => decision = d);
        if (decision?.MainAction == null) continue;

        switch (decision.MainAction)
        {
            case MainActionType.Shoot:
                yield return ExecuteShoot(player, decision.TargetPlayerId, ...);
                yield return WaitActionPresentation();
                break;
            case MainActionType.UseItem:
                yield return ExecuteUseItem(player, decision, ...);
                yield return WaitActionPresentation();
                break;
            case MainActionType.EndAction:
                ended = true;
                break;
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

private IEnumerator ExecuteShoot(PlayerEntity shooter, string targetId, Action<bool> onExecuted)
{
    
    var ctx = new ShootContext { ShooterId, TargetId, InitialBullet, FinalBullet };

    _session.StateStack.Push(new FlowStackEntry
    {
        StateType = FlowStateType.ShootResponse,
        Description = "开枪响应",
        Payload = ctx
    });

    _session.Publish(GameEventType.ShootDeclared);
    yield return RunShootResponseWindow(shooter, ctx);
    _session.StateStack.Pop();
    yield return ResolveShoot(shooter, target, ctx);
}

1
2
3
4
5
6

private void PushAuthoritativeHudSnapshot(FlowBoundaryKind boundary = FlowBoundaryKind.ActionSettle)
{
#if HEADLESS
    _session.Debug.PushAuthoritativeSnapshot(_session, boundary);
#endif
}

1
2
3
4
5
6
7
8

Session = new GameSession(new DebugService());


Session.IsNormalPlayMode = LastPlayMode != PlayModeKind.Debug;
Session.HideOpponentHandItems = LastPlayMode == PlayModeKind.Master;
Session.SetupGame(seats, null);
yield return Session.Flow.RunGameCoroutine();

1
2
3
4
5
6
7
8
9

flowchart LR
    FC[FlowController] --> PCR[PresentationCueRelay]
    FC -->|Request*Decision| DS[DebugService]
    PCR -->|QueuePresentationCue| DS
    DS --> PCP[PresentationCuePlayback]
    PCP --> FX[NormalHudPresentationFx]
    DS --> HUD[NormalGameUIInputView]
    HUD -->|SubmitHumanDecision| DS
    DS --> FC

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

public void StartMatch(RoomModel room, GameStarted started)
{
    var debugHost = new ServerDebugHost();
    var session = new GameSession(debugHost)
    {
        IsNormalPlayMode = true,
        HideOpponentHandItems = room.PlayMode == PlayMode.Master
    };
    var seatConfigs = RoomMatchSeatBuilder.Build(room, _connections, _matchOptions);
    session.SetupGame(seatConfigs, started.Seed);

    var match = new MatchInstance { MatchId, RoomId, Session, DebugHost, Seed, ... };
    var publisher = new FlowPublisher(match, buildSnapshot, BroadcastFlowStepAsync);
    match.FlowPublisher = publisher;
    debugHost.FlowPublisher = publisher;

    _matches.Add(match);
    _ = RunMatchAsync(match);
}

1
2
3
4
5
6

await match.FlowPublisher.PublishMatchStartAsync();
await CoroutineDriver.RunAsync(
    match.Session.Flow.RunGameCoroutine(),
    onIdle: null,
    match.Cancellation.Token);
await FinishMatchAsync(match);  

1
2
3
4
5
6
7
8

if (player.Control == ControlType.AI || AiDelegation.ShouldAutoDecide(player))
{
    var ai = GameDebugAiResolver.Resolve(session, player, kind, shoot);
    if (session.IsNormalPlayMode)
        yield return CoroutineDelay.Seconds(AiThinkPauseSeconds);  
    onComplete(ai);
    yield break;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

BeginWait(player, session, kind, shoot);  
_ = FlowPublisher?.PublishDecisionOpenAsync();

while (_waiting)
{
    if (超时 DecisionTimeoutMs)  
    {
        _resolvedDecision = GameDebugAiResolver.Resolve(...);
        _ = FlowPublisher?.PublishDecisionCloseAsync();
        break;
    }
    yield return null;
}
onComplete(_resolvedDecision);

1
2
3
4
5
6

public IEnumerator WaitActionPresentation(GameSession session)
{
    var holdMs = FlowPublisher.LastPresentationHoldMs;
    if (holdMs <= 0) yield break;
    yield return CoroutineDelay.Seconds(holdMs / 1000f);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

private Task PublishAsync(ProtoFlowBoundary boundary, bool includeHold)
{
    _revision++;
    var holdMs = includeHold ? PresentationHoldCalculator.ComputeMs(_bufferedCueSpecs) : 0;
    LastPresentationHoldMs = holdMs;

    var step = new FlowStep
    {
        Revision = _revision,
        Boundary = boundary,
        PresentationHoldMs = holdMs
    };
    
    
    

    _bufferedCueSpecs.Clear();
    _bufferedEvents.Clear();
    
    return _match.PresentationPipeline;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public static async Task RunAsync(IEnumerator root, Func<Task>? onIdle, CancellationToken ct)
{
    var stack = new Stack<IEnumerator>();
    stack.Push(root);
    while (stack.Count > 0)
    {
        if (current.Current is IEnumerator nested) { stack.Push(nested); continue; }
        if (current.Current is CoroutineDelay delay)
        {
            await Task.Delay(delay.Milliseconds, ct);
            continue;
        }
        await Task.Delay(100, ct);  
    }
}

1
2
3
4
5
6
7
8

message FlowStep {
  int64 revision = 1;
  FlowBoundaryKind boundary = 2;
  GameStateSnapshot snapshot = 3;
  repeated PresentationCue cues = 4;
  repeated GameEventLine events = 5;
  int32 presentation_hold_ms = 6;
}

1
2
3
4
5

FlowController 结算点
    ├─ PresentationCueRelay.Emit*  → ServerDebugHost.QueuePresentationCue → FlowPublisher.BufferCue
    ├─ LogEvent                    → FlowPublisher.BufferEvent
    └─ PushAuthoritativeSnapshot   → FlowPublisher.Publish*Async
                                          └─ 合并 → FlowStep → SignalR 广播

1
2
3
4
5
6
7
8
9
10
11
12
13

OnlineSession（Hub 消息入口）
    └─ OnlineHudCoordinator（统一协调）
           ├─ OnlineFlowOrchestrator（revision 排序 + Presenting 门禁）
           ├─ OnlineHudState（权威态 vs 显示投影）
           └─ NormalGameUIInputView.DispatchOnlineFlowStep
                  ├─ 硬边界? → AbortQueuedPresentation + 清 gate
                  ├─ BeginFlowStep + EnqueueCue（HideItemSlot 前捕获飞行起点）
                  ├─ ApplyOnlineSnapshotData（写权威态）
                  ├─ DecisionOpen/Close → 立即刷新决策 UI
                  ├─ events → OnlineBattleLogStore 战报
                  └─ 表现 idle → CommitDisplay → NotifyPresentationIdle
           └─ OnlineMatchPresentationPlayer（cue 队列 + hold 计时）
                  └─ PresentationCuePlayback → NormalHudPresentationFx

1
2
3
4

Hub 收到 MatchResynced
  → QueueOnlineResync（EnterOnlineMatch 前暂存）
  → PrepareOnlineResync：Abort 表现 + BattleLog.ReplaceFromFlowStep + ApplyResync
  → EnterOnlineMatch 时若有 pending：从 state.events 重建战报

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

sequenceDiagram
    participant FC as FlowController
    participant SDH as ServerDebugHost
    participant FP as FlowPublisher
    participant Hub as SignalR
    participant OS as OnlineSession
    participant OHC as OnlineHudCoordinator
    participant HUD as NormalGameUIInputView

    FC->>SDH: RequestMainActionDecision
    SDH->>FP: PublishDecisionOpen
    FP->>Hub: FlowStep rev=N boundary=DECISION_OPEN
    Hub->>OS: FlowStepReceived
    OS->>OHC: EnqueueFlowStep
    OHC->>HUD: 展示决策 UI
    HUD->>Hub: SubmitDecision
    Hub->>SDH: TrySubmitDecision
    SDH->>FP: PublishDecisionClose
    FC->>FC: ExecuteShoot
    FC->>SDH: QueuePresentationCue + PushSnapshot
    SDH->>FP: PublishActionSettle hold=2800ms
    FP->>Hub: FlowStep rev=N+1 cues+snapshot
    Hub->>OHC: EnqueueFlowStep
    OHC->>HUD: 播放开枪 + 应用权威态
    FC->>SDH: WaitActionPresentation 2.8s
    FC->>SDH: RequestMainActionDecision

1
2

cd server/tools/ProtoSmokeTest
dotnet run -- --flow-sync-unit

1
2

cd server/tools/ProtoSmokeTest
dotnet run -- --match-flow --minutes 8 http://127.0.0.1:8080 用户名 密码

1

cd server && ./scripts/generate-proto.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Flow/FlowController.cs           流程主控：五阶段、响应链、压栈
Flow/GameSession.cs              对局会话聚合
Flow/PresentationCueRelay.cs     权威表现 cue 发射
Flow/PresentationHoldCalculator.cs  表现时长估算
Flow/FlowBoundaryKind.cs         边界枚举（与 proto 对齐）
Core/GameStateStack.cs           分层状态栈
Core/GameEnums.cs                TurnPhase, FlowStateType, MainActionType
Core/GameEventBus.cs             全局事件总线
Debug/IDebugHost.cs              双端宿主接口
Debug/DebugService.cs            Unity 单机宿主
Character/PlayerEntity.cs        玩家实体
Item/ItemService.cs              道具服务
Skill/SkillExecutor.cs           技能执行
AI/AIDecisionMaker.cs            单机 AI 决策
Game/GameEntry.cs                单机/联机入口

1
2
3
4
5
6
7
8
9

Services/Game/GameLoopService.cs     对局启动、决策路由、断线重连
Services/Game/ServerDebugHost.cs     IDebugHost 服务端实现
Services/Game/FlowPublisher.cs       FlowStep 合并广播
Services/Game/CoroutineDriver.cs     无 Unity 协程驱动
Services/Game/GameProtoMapper.cs     GameSession → proto snapshot
Services/Game/GameDecisionMapper.cs  proto ↔ PlayerDecision
Services/Game/MatchModels.cs         MatchInstance、MatchStore
Services/Game/MasterModePrivacy.cs   大师模式掩码
Hubs/GameHub.cs                      SignalR 入口

1
2
3

server/proto/v1/game.proto           FlowStep、GameStateSnapshot、PlayerDecisionPayload
server/proto/v1/enums.proto          FlowBoundaryKind、HubMessageKind
server/proto/v1/room.proto           房间与座位

1
2
3
4
5
6
7
8
9
10
11
12

Network/OnlineSession.cs             Hub 连接、消息分发
Network/OnlineHudCoordinator.cs      协调 Orchestrator + HudState
Network/OnlineFlowOrchestrator.cs    revision 排序与门禁
Network/OnlineHudState.cs            权威态/显示投影双态
Network/OnlineFlowSync.cs            边界判定与延后规则
Network/OnlineFlowChannel.cs         FlowStep/legacy 通道切换
Network/OnlineBattleLogStore.cs      战报存储
Network/GameHubClient.cs             SignalR 客户端
UI/NormalGameUIInputView.Online.cs   联机 FlowStep 派发、决策 UI
UI/OnlineMatchPresentationPlayer.cs cue 队列与 hold
UI/PresentationCuePlayback.cs        cue spec → 动画协程
UI/NormalHudPresentationFx.cs        HUD 特效实现