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 (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 (.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	FireflyProtoc (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 (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 (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	StaticCmdIdDumper (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 (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:

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:

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:

Zero-Reflection Protocol Routing: Implement an array-indexed jump table in Go ([65536]PacketHandlerFunc) instead of map[uint16]any or reflection-based deserialization.
Calyx Battle Override Pattern: Port March7thHoney's CalyxOverrideManager to inject external JSON battle scenarios into world Calyxes for dynamic combat simulation without client modification.
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.

README.md

Honkai: Star Rail Protocol & Emulation Knowledge Base