docs: sanitize documentation and generalize upstream reference server citations

2026-10-31 23:27:27 +07:00
1 parent 7f106dbe46
commit d1f8beac6f
@@ -0,0 +1,101 @@
+# Currency Wars Reference Protocol & Schema Inspection — 2026-10-26
+
+## Artifact identity and scope
+
+The explicitly selected updated reference baseline binary was inspected as a local,
+read-only reference. It was not started, connected to the game, or allowed to
+modify a player save.
+
+- SHA-256: `235f5c3567f281cc99613ed84694ef23f492c15298dc868a8e78e6529f0cda86`.
+- Embedded revision: `440df54730ba64935e9ad7ecae9147e55ad279a9`.
+- Embedded build time: `2026-10-26T02:49:04Z`; Go build metadata: `go1.27.3`.
+- Embedded metadata is reference evidence, not proof of official Client data
+  or runtime feature completeness.
+
+## Reproducible extractions
+
+All paths below are relative to the repository. Machine-specific installation
+paths are supplied to tools as arguments and are not built into source.
+
+`battle_diagnostics/reference-20261026/` contains:
+
+| Artifact | Contents |
+|---|---|
+| `cmdids.json` | 2,860 named command enum entries extracted from the complete embedded protocol descriptor |
+| `starrail.descriptor.pb` / `.json` | 4,939 top-level messages and 472 enums, including field numbers, types and oneofs |
+| `gridfight_excel.descriptor.pb` / `.json` | 75 generated Excel schema messages |
+| `functions.json` | 78,891 compiled Go function names, addresses and sizes recovered from pclntab |
+| `gridfight-workflow.json` | Selected compiled functions, disassembly and direct-call references; includes generated protobuf/resource functions |
+| `cw-handlers.json` | 37 named CW entry handlers and their direct calls; the service contains 1,469 compiled functions |
+| `cw-command-comparison.json` | 109 CW commands compared with the repository command-name table and compiled message schemas |
+| `cw-message-mapping.json` | Exact recursive wire-shape matches, with explicit limitations |
+| `gridfight-excel-data.json` | Complete extracted CW tables; reward pools, basic bonuses, bonfire events/options, routes and Orbs |
+| `gridfight-custom-data.json` | reference-authored declarative rules; these are implementation recipes, not original Client JSON |
+| `resource-manifest.json` | Embedded blob offsets, compressed/uncompressed hashes and extraction provenance |
+| `challenge_peak_extra_data.json` | Explicit adventure NPC/entrance/group mappings for 44 AA stages |
+
+Tools:
+
+```powershell
+python tools/dump_go_workflow.py --binary <reference-exe> --output <dump-directory>
+python tools/dump_embedded_proto.py --binary <reference-exe> --descriptor proto/starrail.proto --output <dump-directory>
+python tools/dump_embedded_proto.py --binary <reference-exe> --descriptor proto/gridfight_excel.proto --output <dump-directory>
+python tools/export_reference_embedded_resources.py --binary <reference-exe> --output <dump-directory>
+protoc --proto_path=. --descriptor_set_out=<current-descriptors.pb> protocol/proto/StarRail.proto protocol/proto/current_handlers.proto
+python tools/compare_cw_reference_protocol.py --reference <starrail.descriptor.pb> --current <current-descriptors.pb> --commands protocol/proto/upstream_cmdids.go --output <dump-directory>
+```
+
+## Protocol compatibility
+
+Of the 109 CW command entries, 60 have the same current name. The remaining
+49 include renamed and obfuscated messages; numerical agreement alone does
+not establish compatibility. Recursive comparison finds 83 exact message
+wire shapes and 26 differences. In particular, large GetData, PendingAction,
+SyncUpdate and battle messages must not be copied wholesale from reference implementations.
+
+Matching checks field numbers, scalar/message types, repeated cardinality and
+oneof partitions recursively. It does not establish enum meanings, business
+semantics or Client success. No numeric aliases or extra response IDs are
+registered by these dump tools.
+
+Confirmed Orb comparison leads:
+
+- Reference `GridFightUseOrbCsReq` corresponds to current `IKMOCJBMGOJ`, with
+  repeated UID field 4 and `is_get_all` field 9.
+- Reference `GridFightUseOrbScRsp` corresponds to current `PNHDGCBLPGD`, uint32
+  retcode field 3.
+- The notification's nested drop structure differs. Do not forward raw reference
+  notification bytes to the current Client without translating that structure.
+
+## Workflow findings
+
+The updated reference contains real EnterBonfire implementation, unlike the
+previously inspected reference. `OnGridFightEnterBonfireCsReq` at RVA
+`0xc697e0` calls `gfBonfireEnter` (`0xc69940`), sends the state update before
+acknowledgement, and saves the changed state. The pending queue can resend an
+existing bonfire action or construct a type-11 action from the node's event
+list. Event options, reward resolution and subsequent selection are separate
+operations; retcode-only success cannot create the menu by itself.
+
+Current route 2801's event `10200601` has an upstream reference custom option involving the
+`PetPalStarDown` rule. A working implementation must retain and apply the
+effect; consuming the choice as a no-op would be incorrect.
+
+The extracted reference player is on route 1800. Its node list, positions,
+inventory and progress are not imported into this server's route-2801 save.
+
+## AA recovery
+
+The embedded mapping identifies Peak 204 as NPC `4015010`, entrance `3013701`,
+maze group `10`. Our old configuration used NPC `4015011`, entrance `3013501`,
+group `8`, and the actual Client rejected that NPC during scene creation.
+The explicit mapping is now preserved in an editable resource with reference
+provenance. See `aa-scene-npc-recovery.md` for validation and Client acceptance
+status. Battle wave IDs and buffs are not replaced with adventure NPC IDs.
+
+## Completion boundary
+
+Extraction and source compilation do not prove CW, AA or a newly ported rule
+works in the Client. The reference baseline itself declares partial/unimplemented/battle-only
+recipes. Newly extracted schemas and recipes are leads to implement and
+verify, not a claim that all modes are now complete.