109 lines
6.6 KiB
Markdown
109 lines
6.6 KiB
Markdown
# Honkai: Star Rail Protocol & Emulation Knowledge Base
|
|
> **Comprehensive Architectural Deep-Dive Collection**
|
|
> *Prepared for engineers, reverse engineers, and autonomous AI agents.*
|
|
|
|
This directory contains complete, code-level architectural specifications and cryptographic reverse-engineering documentation for the core open-source projects in the *Honkai: Star Rail* emulation, protocol de-obfuscation, and metadata analysis ecosystem.
|
|
|
|
---
|
|
|
|
## 🗺️ Master Index & Technical Specifications
|
|
|
|
| File | Target Project & Stack | Core Capabilities & Focus Area |
|
|
| :--- | :--- | :--- |
|
|
| **[lunarcore_architecture_deep_dive.md](./lunarcore_architecture_deep_dive.md)** | **LunarCore**<br>*(Java 17 / Netty / KCP)* | Full game server architecture: 16-byte framing, MT19937 stream cipher, KCP networking, scene/world entities, PVE battle orchestration, Morphia MongoDB ODM. |
|
|
| **[march7thhoney_architecture_deep_dive.md](./march7thhoney_architecture_deep_dive.md)** | **March7thHoney**<br>*(.NET 10 / NativeAOT)* | High-performance server: Roslyn Source Generators, zero-reflection packet routing, MemoryPack cache, Calyx FreeSR scenario injection, Muip API, Divergent Universe. |
|
|
| **[firefly_protoc_deep_dive.md](./firefly_protoc_deep_dive.md)** | **FireflyProtoc**<br>*(C# .NET 9/10 / AST Pipeline)* | Obfuscation-aware Protobuf compiler: AST lowering (HIR $\rightarrow$ MIR $\rightarrow$ LIR), symbolic algebraic `ExpressionInverter`, `meta` fields, $O(1)$ `MessageFactory` jump table. |
|
|
| **[honkai_dumper_deep_dive.md](./honkai_dumper_deep_dive.md)** | **honkai-dumper**<br>*(Rust cdylib / In-Process)* | In-process IL2CPP dumper: non-blocking DLL injection, pattern scanning in `UnityPlayer.dll` (`48 8B 05 ...`), RIP-relative math, ECMA-335 bitmask decompiler, `methods.json`. |
|
|
| **[firefly_static_parser_deep_dive.md](./firefly_static_parser_deep_dive.md)** | **Firefly-Static-Parser**<br>*(Rust CLI / Offline)* | Pure offline static parser: reverse-engineers `b"MHY\0"` container, PE layout discovery, Dynamic Semantic Key Derivation via `<Module>`/`ValueType`, QWORD stream cipher. |
|
|
| **[static_cmdid_dumper_deep_dive.md](./static_cmdid_dumper_deep_dive.md)** | **StaticCmdIdDumper**<br>*(C# .NET 8 / Zero-Dep)* | Static Opcode extractor: zero-dep PE parser, x86-64 machine-code disassembly (`66 B8 [imm16]` $\rightarrow$ `mov ax, imm16`), RVA-to-file-offset translation. |
|
|
| **[dumpcs2protobuf_deep_dive.md](./dumpcs2protobuf_deep_dive.md)** | **Dumpcs2Protobuf**<br>*(C# .NET 8 / Regex AST)* | Schema reverse-engineering: inverts Google.Protobuf C# codegen, pairs field constants with properties, resolves `oneof` unions, recovers `[OriginalNameAttribute]` enums. |
|
|
|
|
---
|
|
|
|
## 🔄 The End-to-End Reverse-Engineering Toolchain
|
|
|
|
The following diagram illustrates how all 7 tools connect to form an automated protocol extraction and server emulation pipeline:
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
subgraph S1["1. Binary & Metadata Extraction"]
|
|
GA["GameAssembly.dll + Metadata"]
|
|
GA -->|Offline Analysis| FSP["Firefly-Static-Parser<br/>(Rust CLI)"]
|
|
GA -->|In-Process Injection| HD["honkai-dumper<br/>(Rust DLL)"]
|
|
FSP --> DUMP_CS["dump.cs<br/>(C# Class Definitions)"]
|
|
FSP --> METHODS_JSON["methods.json<br/>(Method RVAs)"]
|
|
HD --> DUMP_CS
|
|
HD --> METHODS_JSON
|
|
end
|
|
|
|
subgraph S2["2. Protocol Schema Recovery"]
|
|
DUMP_CS --> D2P["Dumpcs2Protobuf<br/>(C# Engine)"]
|
|
D2P --> RAW_PROTO[".proto Schemas<br/>(Messages, Enums, OneOfs)"]
|
|
end
|
|
|
|
subgraph S3["3. Opcode & CmdId Resolution"]
|
|
METHODS_JSON --> SCD["StaticCmdIdDumper<br/>(C# Micro-Disassembler)"]
|
|
EXE["Target Game Binary"] --> SCD
|
|
SCD --> PACKET_IDS["PacketIds.json<br/>(PacketName -> CmdId)"]
|
|
end
|
|
|
|
subgraph S4["4. Schema Annotation & De-obfuscation"]
|
|
RAW_PROTO & PACKET_IDS --> ANNOTATED_PROTO[".proto with Metadata & Wire Masks<br/>- meta uint32 cmd_id = 143;<br/>- uint32 id = 1 [get: (id ^ 1) + 2];"]
|
|
end
|
|
|
|
subgraph S5["5. High-Performance Compilation"]
|
|
ANNOTATED_PROTO --> FP["FireflyProtoc<br/>(Symbolic Inversion Compiler)"]
|
|
FP --> STUBS["Compiled Protocol Stubs<br/>(Zero-Allocation Deserializers)"]
|
|
end
|
|
|
|
subgraph S6["6. Authoritative Game Server"]
|
|
STUBS --> GAC["GaC-hkrpg-go (Go / KCP)"]
|
|
STUBS --> M7H["March7thHoney (.NET 10)"]
|
|
STUBS --> LC["LunarCore (Java 17)"]
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## 📌 Summary of Core Technical Invariants
|
|
|
|
### 1. Binary Envelope Framing (16-Byte Envelope)
|
|
All network traffic between client and server follows this standard framing:
|
|
- **Header Magic**: `0x9D74C714` (4 bytes, Big-Endian uint32)
|
|
- **CmdID (Opcode)**: 2 bytes (uint16 BE)
|
|
- **Head Length**: 2 bytes (uint16 BE, typically `0x0000`)
|
|
- **Payload Length**: 4 bytes (uint32 BE)
|
|
- **Payload**: Serialized Protobuf message payload
|
|
- **Tail Magic**: `0xD7A152C8` (4 bytes, Big-Endian uint32)
|
|
|
|
### 2. Network Encryption
|
|
- Initial handshake exchanges an `Ec2b` packet (`HEAD_MAGIC = 1647469381` / ASCII `"Ec2b"`).
|
|
- Contains 16-byte key and 2048-byte data, generating a 64-bit seed.
|
|
- **MT19937 (Mersenne Twister)** expands this seed into a 4,096-byte keystream used for repeating XOR stream encryption.
|
|
|
|
### 3. Machine Code Opcode Getters
|
|
In compiled x86-64 IL2CPP binaries, packet opcode getter methods compile to:
|
|
```nasm
|
|
66 B8 xx xx ; mov ax, imm16 (Opcode)
|
|
C3 ; ret
|
|
```
|
|
- `0x66`: 16-bit operand size override prefix.
|
|
- `0xB8`: `mov ax` opcode.
|
|
- `xx xx`: 16-bit Little-Endian Command ID.
|
|
|
|
### 4. Dynamic Semantic Key Derivation
|
|
To decrypt custom `b"MHY\0"` metadata without hardcoding version-specific keys, analyze CLR invariants:
|
|
- TypeDef 0 is always `<Module>` $\rightarrow$ gives `type_base_none` and `type_attribute_key`.
|
|
- `System.ValueType` inherits from `System.Object` $\rightarrow$ gives `type_base_object`.
|
|
- `System.Enum` inherits from `System.ValueType` $\rightarrow$ gives `type_base_value_type`.
|
|
- Parent key: $\text{type\_parent\_key} = \text{type\_base\_object} - 1$.
|
|
|
|
---
|
|
|
|
## 🚀 Application to `GaC-hkrpg-go`
|
|
|
|
When building or updating the Go server implementation in this repository:
|
|
1. **Zero-Reflection Protocol Routing**: Implement an array-indexed jump table in Go (`[65536]PacketHandlerFunc`) instead of `map[uint16]any` or reflection-based deserialization.
|
|
2. **Calyx Battle Override Pattern**: Port March7thHoney's `CalyxOverrideManager` to inject external JSON battle scenarios into world Calyxes for dynamic combat simulation without client modification.
|
|
3. **Configuration Compliance (`AGENTS.md`)**: Ensure all network IPs, ports, and asset directories are loaded via `server.json` and overridable via `server.local.json` or environment variables without hardcoded machine paths.
|