eagle0/docs/SHARDOK_SERVER_STATUS_SERVER_WORK.md

Shardok server-status indicator: server-side wiring needed

Background

The unity-client branch shardok-status-client adds wiring so the connection-status indicator in the top-right of the Unity UI shows tactical battle state ("Your turn", "Waiting for AI", etc.) while a Shardok battle is on screen, instead of the strategic "Your turn / Waiting for other players" status.

The client side is complete:

• Assets/Eagle/ConnectionStatusUI.cs — adds IShardokGameStateProvider and GetShardokConnectedStatusText() (lines 21-29, 187-200).
• Assets/Shardok/ShardokGameModel.cs — implements IShardokGameStateProvider, exposes ShardokServerStatus and a HandleServerStatus() setter.
• Assets/Eagle/EagleGameModel.cs — calls shardokGameModel.HandleServerStatus(...) inside the ShardokActionResultResponse handler when oneResponse.ShardokServerStatus != null (lines 444-446).
• Assets/Eagle/EagleGameController.cs — sets the provider on GoToBattle and Assets/Shardok/ShardokGameController.cs clears it when the battle ends.

Symptom

In a live Shardok battle the indicator always reads "Connected". The other branches of the switch (Your turn, Waiting for AI, …) never fire.

Diagnosis

ConnectionStatusUI.GetShardokConnectedStatusText() distinguishes three cases:

1. ShardokServerStatus == null → "Waiting for server..."
2. ShardokServerStatus.Status matches one of the listed enum values → the matching text.
3. Otherwise → "Connected" (default arm of the switch).

We see "Connected", not "Waiting for server...", so the server is sending a ShardokServerStatus proto inside OneShardokResponse — but its status enum is arriving as UNKNOWN = 0, the proto3 default for a field that was never assigned. That hits the default arm.

The client wiring is forwarding what it receives correctly. The server simply isn't populating the status field.

What needs to change (Scala server)

Wherever the Eagle server constructs SingleShardokGameResultResponse (in the path that handles Shardok action results / produces ShardokActionResultResponse):

• Build a ShardokServerStatus whose status reflects the actual battle state:
  • YOUR_TURN — it's the recipient's turn and they have available commands.
  • WAITING_FOR_AI — waiting on AI computation in Shardok.
  • WAITING_FOR_HUMAN_PLAYER — waiting on another human player to act.
  • PROCESSING — the server is actively processing an action.
• Optionally populate waiting_for_faction_ids (repeated int32) when relevant — the field exists on the proto but the client doesn't currently render it; safe to leave empty for now.

Currently the field is being attached but the enum is never set, which is why we see UNKNOWN on the wire.

Proto reference

// src/main/protobuf/net/eagle0/eagle/api/eagle.proto
message ShardokServerStatus {
    enum Status {
        UNKNOWN = 0;
        YOUR_TURN = 1;
        WAITING_FOR_AI = 2;
        WAITING_FOR_HUMAN_PLAYER = 3;
        PROCESSING = 4;
    }
    Status status = 1;
    repeated int32 waiting_for_faction_ids = 2;
}

// SingleShardokGameResultResponse.shardok_server_status field number = 5

(Verified against generated C# in Assets/GeneratedProtos/net/eagle0/eagle/api/Eagle.cs lines 339-341, 12044-12278.)

How to verify the fix

1. Rebuild the Eagle server, run the Unity client on the shardok-status-client branch.
2. Enter a battle.
3. Observe the indicator (top-right). It should change between "Your turn", "Waiting for AI", "Waiting for other player", and "Processing..." instead of sitting on "Connected".
4. Leaving the battle should restore the strategic status text ("Your turn" / "Waiting for other players" / etc.).

Notes for the Scala worktree Claude

• The field name on the parent message is shardok_server_status on SingleShardokGameResultResponse (field 5 — already wired, just unset).
• Per project memory: prefer parallel definitions over reusing protos across Eagle and Shardok systems. ShardokServerStatus is the Shardok-side counterpart to the existing ServerGameStatus; do not consolidate them.
• The indicator is updated client-side at 0.5 s cadence, so the server doesn't need to send a status on every wire message — but every OneShardokResponse is a fine place to attach the current status, since that's the path the client already listens on.