GaCy-GO/docs/scratch/README.md

# 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. |
| **[csharp_nativeaot_server_architecture.md](./csharp_nativeaot_server_architecture.md)** | **C# NativeAOT Reference Server**<br>*(.NET 10 / NativeAOT)* | High-performance server: Roslyn Source Generators, zero-reflection packet routing, MemoryPack cache, Calyx scenario injection, Admin API, Endgame orchestration. |
| **[protobuf_ast_compiler_pipeline.md](./protobuf_ast_compiler_pipeline.md)** | **Protobuf AST Compiler Pipeline**<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`. |
| **[static_pe_metadata_parser.md](./static_pe_metadata_parser.md)** | **Static PE Metadata 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["Static PE Metadata 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["Protobuf AST Compiler<br/>(Symbolic Inversion Pipeline)"]
        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["C# NativeAOT Reference Server"]
        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**: Apply modular scenario injection 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.