added documentation and decompiled client

2026-03-12 00:27:00 +03:00
parent 669b8d7455
commit d7352b818d
6 changed files with 259 additions and 149 deletions
@@ -0,0 +1,189 @@
+# Protocol Notes
+
+## Opcode Decoder Map (Client)
+
+Source: `hs-client/Assembly-CSharp/ConnectAPI.cs`.
+
+- `116` → `PongPacketDecoder`
+- `169` → `Deadend`
+- `167` → `DeadendUtil`
+- `123` → `DebugConsoleCommand`
+- `124` → `DebugConsoleResponse`
+- `14` → `AllOptions`
+- `5` → `DebugMessage`
+- `17` → `EntityChoices`
+- `13` → `EntitiesChosen`
+- `16` → `GameSetup`
+- `19` → `PowerHistory`
+- `15` → `UserUI`
+- `9` → `TurnTimer`
+- `10` → `NAckOption`
+- `12` → `GameCanceled`
+- `23` → `ServerResult`
+- `24` → `SpectatorNotify`
+- `289` → `Disconnected`
+- `202` → `DeckList`
+- `207` → `Collection`
+- `215` → `GetDeckContentsResponse`
+- `216` → `DBAction`
+- `217` → `DeckCreated`
+- `218` → `DeckDeleted`
+- `219` → `DeckRenamed`
+- `212` → `ProfileNotices`
+- `224` → `BoosterList`
+- `226` → `BoosterContent`
+- `208` → `GamesInfo`
+- `231` → `ProfileDeckLimit`
+- `262` → `ArcaneDustBalance`
+- `278` → `GoldBalance`
+- `233` → `ProfileProgress`
+- `270` → `PlayerRecords`
+- `271` → `RewardProgress`
+- `232` → `MedalInfo`
+- `241` → `ClientOptions`
+- `246` → `DraftBeginning`
+- `247` → `DraftRetired`
+- `248` → `DraftChoicesAndContents`
+- `249` → `DraftChosen`
+- `288` → `DraftRewardsAcked`
+- `251` → `DraftError`
+- `252` → `Achieves`
+- `285` → `ValidateAchieveResponse`
+- `282` → `CancelQuestResponse`
+- `264` → `GuardianVars`
+- `260` → `CardValues`
+- `258` → `BoughtSoldCard`
+- `269` → `MassDisenchantResponse`
+- `265` → `BattlePayStatusResponse`
+- `295` → `ThirdPartyPurchaseStatusResponse`
+- `272` → `PurchaseMethod`
+- `275` → `CancelPurchaseResponse`
+- `256` → `PurchaseResponse`
+- `238` → `BattlePayConfigResponse`
+- `280` → `PurchaseWithGoldResponse`
+- `283` → `HeroXP`
+- `254` → `NoOpPacketDecoder`
+- `286` → `PlayQueue`
+- `330` → `CheckAccountLicensesResponse`
+- `331` → `CheckGameLicensesResponse`
+- `236` → `CardBacks`
+- `292` → `SetCardBackResponse`
+- `296` → `SetProgressResponse`
+- `299` → `TriggerEventResponse`
+- `300` → `NotSoMassiveLoginReply`
+- `304` → `AssetsVersionResponse`
+- `306` → `AdventureProgressResponse`
+- `307` → `UpdateLoginComplete`
+- `311` → `AccountLicenseAchieveResponse`
+- `315` → `SubscribeResponse`
+- `316` → `TavernBrawlInfo`
+- `317` → `TavernBrawlPlayerRecordResponse`
+- `318` → `FavoriteHeroesResponse`
+- `320` → `SetFavoriteHeroResponse`
+- `324` → `DebugCommandResponse`
+- `325` → `AccountLicensesInfoResponse`
+- `326` → `GenericResponse`
+- `328` → `ClientRequestResponse`
+- `322` → `GetAssetResponse`
+
+## Opcode Encoder Map (Client → Server)
+
+Game server outbound (QueueGamePacket):
+
+- `22` → `SpectatorHandshake`
+- `168` → `Handshake`
+- `1` → `GetGameState`
+- `115` → `Ping`
+- `11` → `Concede`
+- `3` → `ChooseEntities`
+- `2` → `ChooseOption`
+- `15` → `UserUI` (emote + mouse)
+- `25` → `InviteToSpectate`
+- `26` → `RemoveSpectators`
+- `123` → `DebugConsoleCommand`
+
+Debug console outbound (QueueDebugPacket):
+
+- `124` → `DebugConsoleResponse`
+
+Util server outbound (ClientRequestManager/UtilOutbound):
+
+- `319` → `SetFavoriteHero`
+- `279` → `PurchaseWithGold`
+- `312` → `StartThirdPartyPurchase`
+- `293` → `SubmitThirdPartyReceipt`
+- `294` → `GetThirdPartyPurchaseStatus`
+- `250` → `GetPurchaseMethod`
+- `273` → `DoPurchase`
+- `274` → `CancelPurchase`
+- `237` → `GetBattlePayConfig`
+- `255` → `GetBattlePayStatus`
+- `268` → `MassDisenchantRequest`
+- `235` → `DraftBegin`
+- `242` → `DraftRetire`
+- `287` → `DraftAckRewards`
+- `244` → `DraftGetPicksAndContents`
+- `245` → `DraftMakePick`
+- `201` → `GetAccountInfo`
+- `327` → `GenericRequestList`
+- `205` → `UpdateLogin`
+- `214` → `GetDeckContents`
+- `209` → `CreateDeck`
+- `210` → `DeleteDeck`
+- `211` → `RenameDeck`
+- `332` → `DeckSetTemplateSource`
+- `222` → `DeckSetData`
+- `213` → `AckNotice`
+- `225` → `OpenBooster`
+- `230` → `SetProgress`
+- `298` → `TriggerLaunchDayEvent`
+- `303` → `GetAssetsVersion`
+- `308` → `AckWingProgress`
+- `309` → `AcknowledgeBanner`
+- `310` → `SetAdventureOptions`
+- `223` → `AckCardSeen`
+- `240` → `GetOptions`
+- `239` → `SetOptions`
+- `253` → `GetAchieves`
+- `284` → `ValidateAchieve`
+- `281` → `CancelQuest`
+- `243` → `AckAchieveProgress`
+- `297` → `CheckAccountLicenseAchieve`
+- `305` → `GetAdventureProgress`
+- `257` → `BuySellCard`
+- `267` → `CheckAccountLicenses`
+- `276` → `CheckGameLicenses`
+- `291` → `SetCardBack`
+- `321` → `GetAssetRequest`
+- `329` → `Unsubscribe`
+- `322` → `DebugCommandRequest`
+
+## Learnings
+
+- Client maintains deferred response maps for async requests in `Network.cs`.
+- Opcode map is a key compatibility anchor for the Go gateway.
+
+## Protobuf Definitions (Source)
+
+The repo does not contain the protobuf class definitions for most message
+types. They live in the client assemblies that were not decompiled here.
+To generate Go structs, extract `.proto` from the client install:
+
+- `PegasusGame.dll` (game server packets)
+- `PegasusUtil.dll` (utility/account/collection packets)
+- `SpectatorProto.dll` (spectator packets)
+- `BobNetProto.dll` (misc/legacy)
+- `PegasusShared.dll` (shared types: `CardDef`, `BnetId`, enums)
+
+Suggested mapping (verify by decompiling those DLLs):
+
+- `PegasusGame`: `GameSetup`, `PowerHistory`, `EntityChoices`, `EntitiesChosen`,
+  `UserUI`, `TurnTimer`, `NAckOption`, `GameCanceled`, `ServerResult`,
+  `Disconnected`, `Handshake`, `GetGameState`, `Ping`, `Concede`,
+  `ChooseEntities`, `ChooseOption`.
+- `SpectatorProto`: `SpectatorHandshake`, `SpectatorNotify`, `InviteToSpectate`,
+  `RemoveSpectators`.
+- `PegasusUtil`: everything in the decoder/encoder maps that relates to
+  collection, login, decks, purchases, achievements, and assets (most of the
+  `UtilOutbound` messages).
+- `BobNetProto`: `Deadend`, `DeadendUtil` (verify).