Add doc describing server-side work for Shardok status indicator

Hand-off note for the Scala worktree: client wiring on shardok-status-client is complete, but the indicator only ever shows "Connected" in battle because the server attaches a ShardokServerStatus proto with status left at the default UNKNOWN value. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-28 21:35:42 +00:00 · 2026-05-05 15:24:59 -07:00
parent b0639dc8d0
commit e71055cd57
1 changed files with 103 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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.