From e71055cd57e1f5fbec74f663c0ebccaad1011be0 Mon Sep 17 00:00:00 2001 From: Dan Crosby Date: Tue, 5 May 2026 15:24:59 -0700 Subject: [PATCH] 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 --- docs/SHARDOK_SERVER_STATUS_SERVER_WORK.md | 103 ++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/SHARDOK_SERVER_STATUS_SERVER_WORK.md diff --git a/docs/SHARDOK_SERVER_STATUS_SERVER_WORK.md b/docs/SHARDOK_SERVER_STATUS_SERVER_WORK.md new file mode 100644 index 0000000000..4cd4672dd1 --- /dev/null +++ b/docs/SHARDOK_SERVER_STATUS_SERVER_WORK.md @@ -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.