4.9 KiB
Text Client Operator Guide
This guide covers operating the Eagle text client against a running Eagle server. It does not cover game strategy.
Authentication And Startup
The current bearer-token file is:
/private/tmp/eagle0-text-client-token.txt
If that file is absent or authentication fails, stop and ask the user for a current bearer token. Do not invent a token or use another user's credentials.
Start the production client with:
bazel run //src/main/scala/net/eagle0/eagle/text_client:eagle_text_client -- --tls --host prod.eagle0.net --port 443 --bearer-token-file /private/tmp/eagle0-text-client-token.txt
At the eagle0> prompt, use lobby to list running games and available new-game leaders. To resume a game, use:
stream <game-id>
Wait for subscription: success=true before posting a command.
Inspecting State
Use these commands before acting:
status
state
commands
commands-json
state is the concise map and owned-province view. state-json prints the complete view. commands-json includes the exact fields, IDs, resource amounts, and command choices currently accepted by the server.
Generated text is stored locally during the client process. Use text <text-id> for a text ID without spaces, such as text hn_105. Province leaders in state are resolved through this store when their names have been received.
Posting Eagle Commands
Use the available-command data from commands-json to select a command, then post a matching selected command:
post-json <province-id> <SelectedCommandType> <JSON>
For example:
post-json 13 ImproveSelectedCommand {"improvementType":"ECONOMY","actingHeroId":105,"lockType":true}
post-rest 13
post-feast 13
The client has shortcuts for post-rest, post-return, post-feast, riot decisions, and battle aftermath. Other selected-command JSON schemas are defined in:
src/main/protobuf/net/eagle0/eagle/api/selected_command.proto
Only post a selected command that is currently listed as available. A successful request prints post-command: SUCCESS; do not assume a command was accepted until that response or a later game update arrives.
Some actions enter a temporary subcommand state. For example, trading is operated as:
post-json <province-id> TravelSelectedCommand {}
post-json <province-id> TradeSelectedCommand {"tradeType":"BUY_FOOD","amount":<amount>}
post-return <province-id>
After each step, run commands-json again. The server will reject a nested command, such as TradeSelectedCommand, if its parent state has not been entered.
March Warnings
Marches may produce a warning before being sent. Review it, then resubmit only when intentional:
post-json --force <province-id> MarchSelectedCommand <JSON>
MarchSelectedCommand.marchingUnits contains combat units. Each selected battalion is paired with a distinct hero in the same combat-unit entry; do not submit battalion-only entries.
Shardok Battles
When a battle is active, inspect it with:
shardok-units
shardok-commands
Post one of the currently listed command indices with:
post-shardok <index>
Omit the optional roll value during normal play. The server then generates any roll required by the selected command. To override that roll for deterministic testing, append an integer value:
post-shardok <index> <integer-roll>
roll is a placeholder in command usage, not a literal argument. Only an
integer is accepted, and the override has an effect only for Shardok commands
that support a client-supplied roll.
For a specific active battle:
post-shardok <shardok-game-id> <index>
post-shardok <shardok-game-id> <index> <integer-roll>
The battle ID may be omitted only when exactly one outstanding battle currently
has postable commands. If multiple battles have commands, the client refuses the
ambiguous shorthand; use the battle ID printed by shardok-commands. Battles
removed from Eagle's outstanding-battle list are no longer postable, and a
Shardok update with no available commands clears the previous command list.
Use shardok-commands-json or shardok-units-json when the concise output omits a needed field.
Reconnects And Shutdown
The client automatically recreates a failed gRPC stream and re-subscribes to the active game. It retains its in-process ClientTextStore, so a reconnect should announce:
Reconnecting to game <game-id> with saved text state.
Followed by a successful subscription without replaying the full generated-text catalog. Do not start a second client merely because a stream reports GOAWAY, UNAVAILABLE, or RST_STREAM; wait for the automatic reconnect and subscription acknowledgment.
The text store is in memory. A newly launched process performs an initial text sync once, then retains byte offsets for reconnects during that process.
Use quit to close the client cleanly. Use drop <game-id> only when intentionally abandoning that game.