GaCy-GO/docs/scratch/csharp_nativeaot_server_architecture.md

# รายงานการวิเคราะห์สถาปัตยกรรมและการทำงานของ Reference C# AOT Server (Deep-Dive Technical Specification)

> **เอกสารอ้างอิงทางเทคนิคระดับลึกสำหรับวิศวกรซอฟต์แวร์และโมเดลปัญญาประดิษฐ์ (AI Systems)**  
> วิเคราะห์จากซอร์สโค้ดของโครงการ: โครงสร้างสถาปัตยกรรมอ้างอิง C# .NET 10 (Reference Architecture)  
> ครอบคลุมสถาปัตยกรรม .NET 10, Roslyn Source Generators (NativeAOT), KcpSharp, SQLite/MySQL Storage Pipeline, Lua Client Injection, Calyx/FreeSR Scenario Injection, Muip GM API และโหมดเกมเวอร์ชันใหม่ (Apocalyptic Shadow, Divergent Universe, Currency War)

---

## สารบัญ (Table of Contents)
1. [ภาพรวมสถาปัตยกรรมระดับสูง (High-Level Architecture & Tech Stack)](#1-ภาพรวมสถาปัตยกรรมระดับสูง-high-level-architecture--tech-stack)
2. [การออกแบบ NativeAOT และ Roslyn Source Generators](#2-การออกแบบ-nativeaot-และ-roslyn-source-generators)
3. [เลเยอร์เครือข่ายและการเข้ารหัสขั้นสูง (Network, KcpSharp & Crypto)](#3-เลเยอร์เครือข่ายและการเข้ารหัสขั้นสูง-network-kcpsharp--crypto)
   - 3.1 KcpSharp Transport และการจัดการบัฟเฟอร์ ArrayPool
   - 3.2 Binary Packet Framing & Buffer Overflow Protection
   - 3.3 Ec2b Key Derivation และ MT19937 XOR Key Pipeline
4. [กลไกการฉีดสคริปต์เข้าไคลเอนต์ (Client Lua Script Injection Engine)](#4-กลไกการฉีดสคริปต์เข้าไคลเอนต์-client-lua-script-injection-engine)
5. [ระบบจัดเก็บข้อมูลและการจำลองฐานข้อมูล (Persistence & Database Pipeline)](#5-ระบบจัดเก็บข้อมูลและการจำลองฐานข้อมูล-persistence--database-pipeline)
   - 5.1 Dual-Engine: SQLite & MySQL
   - 5.2 In-Memory Dirty Cache & Asynchronous Periodic Flusher
6. [ระบบแคชทรัพยากรเกมความเร็วสูง (High-Speed Binary Resource Cache)](#6-ระบบแคชทรัพยากรเกมความเร็วสูง-high-speed-binary-resource-cache)
7. [ระบบการต่อสู้และการแทรกแซงสถานการณ์ (Battle & Calyx Override Engine)](#7-ระบบการต่อสู้และการแทรกแซงสถานการณ์-battle--calyx-override-engine)
   - 7.1 ลูปการต่อสู้หลัก
   - 7.2 Calyx Override & FreeSR JSON Scenario Injection
8. [ระบบโหมดการเล่นขั้นสูง (Modern End-Game Modes)](#8-ระบบโหมดการเล่นขั้นสูง-modern-end-game-modes)
   - 8.1 ChallengePeak (Apocalyptic Shadow & Anomaly Arbitration)
   - 8.2 Divergent Universe & Unknowable Domain
   - 8.3 Currency War & GridFight (Aetherium Wars)
9. [การจัดการระยะไกลและหน้าต่างควบคุม (Muip Protocol & Admin Dashboard)](#9-การจัดการระยะไกลและหน้าต่างควบคุม-muip-protocol--admin-dashboard)
   - 9.1 Muip GM Protocol (RSA-Encrypted Remote Command Execution)
   - 9.2 Built-in Embedded Web Admin & Registration Portal
   - 9.3 Cluster Deployment via ServerExchange Secret
10. [ตารางเปรียบเทียบเชิงลึก: LunarCore vs Reference C# AOT Server](#10-ตารางเปรียบเทียบเชิงลึก-lunarcore-vs-Reference C# AOT Server)
11. [คู่มือการต่อยอดเชิงวิศวกรรมสำหรับ AI (AI Implementation Guidelines)](#11-คู่มือการต่อยอดเชิงวิศวกรรมสำหรับ-ai-ai-implementation-guidelines)

---

## 1. ภาพรวมสถาปัตยกรรมระดับสูง (High-Level Architecture & Tech Stack)

**Reference C# AOT Server** เป็นโครงการ Server Reimplementation สำหรับเกม *Honkai: Star Rail* ที่เขียนขึ้นใหม่ทั้งหมดด้วยภาษา **C# บน .NET 10** โดยมุ่งเน้นที่:
1. **ประสิทธิภาพสูงสุด (Extreme Performance)**: ลด Allocation ของหน่วยความจำผ่าน `Span<T>`, `Memory<T>`, `ArrayPool<byte>`, และหลีกเลี่ยง Reflection
2. **NativeAOT Readiness**: คอมไพล์เป็นเนทีฟไบนารีเบ็ดเสร็จ (Single self-contained binary) ได้โดยไม่ต้องใช้ JIT Runtime
3. **ฟีเจอร์เวอร์ชันใหม่ (Modern Game Modes)**: รองรับคอนเทนต์เวอร์ชันใหม่ (2.x ถึง 4.x) เช่น Apocalyptic Shadow, Divergent Universe, Currency War, Penacony Clockie Dial, Critter Pick (Cat Cake Catch)
4. **ความสามารถในการปรับแต่ง (Developer & Testing Friendly)**: สามารถแทรกแซงการต่อสู้ผ่านไฟล์สคริปต์ FreeSR JSON (`CalyxOverrideManager`) และมีระบบเว็บแอดมิน Dashboard ในตัว

### โครงสร้างโมดูลย่อย (Solution Structure):
- `Program/`: จุดเริ่มต้นเซิร์ฟเวอร์ (`EntryPoint.cs`), LifeCycle Management, CLI Console, การจัดการล็อก
- `GameServer/`: บริการเกม KCP, GameSession/Connection, ตัวจัดการเกม (50+ Game Managers), ตัวถอดรหัสแพ็กเก็ต (51 หมวดหมู่)
- `WebServer/`: ASP.NET Core Kestrel (Dispatch, Gateway, Muip API, Web Admin, Registration, SDK Shop)
- `Command/`: เครื่องมือคำสั่งเซิร์ฟเวอร์แบบ Compile-time Registry
- `Common/`: ตัวแบบข้อมูลหลัก, คอนฟิก, โมเดลฐานข้อมูล, รหัสข้อผิดพลาด และเครื่องมือยูทิลิตี
- `KcpSharp/`: ไคลเอนต์/เซิร์ฟเวอร์ KCP แบบ Pure C# Zero-allocation
- `Proto/`: Google Protobuf C# Generated Classes
- `SourceGen/`: C# Roslyn Incremental Source Generators สำหรับสร้างโค้ดแบบไร้ Reflection

```mermaid
flowchart TB
    subgraph Client["HSR Game Client (PC / Android / iOS)"]
        HTTPClient["HTTP/HTTPS Requests"]
        KCPClient["KCP/UDP Traffic"]
    end

    subgraph Reference C# AOT Server[".NET 10 Server Architecture"]
        subgraph WebServerModule["WebServer (ASP.NET Core Kestrel)"]
            DispatchCtrl["DispatchRoutes (/query_dispatch)"]
            GatewayCtrl["GateServerRoutes (/query_gateway)"]
            AdminCtrl["AdminRoutes (Embedded Dashboard)"]
            MuipCtrl["MuipServerRoutes (/muip/*)"]
            ClusterCtrl["ServerExchangeRoutes (Distributed Sync)"]
        end

        subgraph KcpNetworkLayer["KCP Transport (KcpSharp)"]
            KcpListener["Reference C# AOT ServerListener"]
            Connection["Connection (ArrayPool & MT19937 Xor)"]
            HandlerMgr["HandlerManager (Generated Registry)"]
        end

        subgraph GameplayEngine["Gameplay Engine & Services"]
            PlayerInst["PlayerInstance"]
            subgraph Managers["Player Subsystem Managers"]
                AvatarMgr["AvatarManager & MultiPath"]
                InvMgr["InventoryManager & Relic Generator"]
                BattleMgr["BattleManager & FreeSR CalyxOverride"]
                EndgameMgr["ChallengePeak (Apocalyptic Shadow)"]
                RogueMgr["Divergent Universe / ChessRogue"]
            end
        end

        subgraph StorageLayer["Data & Persistence Layer"]
            ResCache["ResourceCache (MemoryPack + GZip)"]
            DbHelper["DatabaseHelper (In-Memory Dirty Cache)"]
            SQLite[("SQLite (.db)")]
            MySQL[("MySQL Server")]
        end
    end

    HTTPClient <-->|"REST / JSON"| WebServerModule
    KCPClient <-->|"KCP UDP / Ec2b Framed Packets"| KcpListener
    KcpListener --> Connection
    Connection --> HandlerMgr
    HandlerMgr --> PlayerInst
    PlayerInst --> Managers
    Managers --> DbHelper
    DbHelper --> SQLite
    DbHelper --> MySQL
    Managers --> ResCache
```

---

## 2. การออกแบบ NativeAOT และ Roslyn Source Generators

หนึ่งในปัญหาใหญ่ของเซิร์ฟเวอร์เกมที่เขียนด้วย Java หรือ C# ทั่วไปคือการพึ่งพา Reflection อย่างหนัก (เช่น การสแกนหา `@Opcodes`, การสร้าง ORM mapping) ซึ่งทำให้:
1. การบูตช้า
2. กินแรมมาก
3. **คอมไพล์ NativeAOT ไม่ได้** เพราะ Reflection รันไทม์ถูกตัดทิ้ง (Trimmed)

Reference C# AOT Server แก้ปัญหานี้โดยสร้างคอมไพลเลอร์เสริม **Roslyn Source Generator (`SourceGen/`)**:

```mermaid
flowchart LR
    SourceCode["C# Entity & Handler Classes<br/>[Handler(CmdIds.PlayerLoginCsReq)]"] --> Roslyn["Roslyn Source Generator"]
    Roslyn --> GeneratedCode["Generated C# Partial Classes<br/>- HandlerRegistry.g.cs<br/>- DatabaseStores.g.cs<br/>- CommandRegistry.g.cs"]
    GeneratedCode --> NativeCompiler[".NET 10 NativeAOT Compiler"]
    NativeCompiler --> NativeBinary["Single Native Executable<br/>(Zero Reflection / Instant Boot)"]
```

1. **`HandlerRegistryGenerator.cs`**:
   - ตรวจจับคลาสที่มีแอตทริบิวต์ `[Handler(CmdIds....)]` ในขณะคอมไพล์
   - สร้างสวิตช์เคสหรืออาร์เรย์ Lookup โดยตรง (`HandlerRegistry.g.cs`) เพื่อแมป Opcode เข้ากับ Concrete Handler Instance แบบ Zero-reflection
2. **`DatabaseStoreGenerator.cs`**:
   - สร้างคลาส `EntityStores.g.cs` เพื่อจัดการ Table Creation, Insert, Update, Select สำหรับทั้ง SQLite และ MySQL ของแต่ละ Entity โดยตรง
3. **`CommandRegistryGenerator.cs`**:
   - ตรวจจับคำสั่งในโฟลเดอร์ `Cmd/` แล้วสร้างตารางแมปชื่อคำสั่ง (Labels & Aliases) ตอนคอมไพล์
4. **`MemoryPackRegistrarGenerator.cs`**:
   - ลงทะเบียน Type Formatter ล่วงหน้าสำหรับ MemoryPack Binary Serializer

---

## 3. เลเยอร์เครือข่ายและการเข้ารหัสขั้นสูง (Network, KcpSharp & Crypto)

### 3.1 KcpSharp Transport และการจัดการบัฟเฟอร์ ArrayPool
Reference C# AOT Server ใช้ **`KcpSharp`** ซึ่งถูกปรับแต่งให้รันบน .NET 10:
- ในลูปรับข้อมูล `ReceiveLoop()` มีการใช้ `ArrayPool<byte>.Shared.Rent(result.BytesReceived)`
- ข้อมูลที่ประมวลผลเสร็จแล้วจะถูก `ArrayPool<byte>.Shared.Return(buffer)` คืนสู่พูลทันทีเพื่อป้องกันการจัดสรรแรมซ้ำซ้อน (Zero-Garbage Collection Pressure)

### 3.2 Binary Packet Framing & Buffer Overflow Protection
โครงสร้างแพ็กเก็ตอิงตามข้อกำหนดของตัวเกมจริง:

```
+-----------------------------------------------------------------------------------+
| Offset (Bytes) | Type       | Field Name        | Value / Description             |
+-----------------------------------------------------------------------------------+
| 0x00 - 0x03    | uint32 BE  | HEADER_CONST      | 0x9D74C714 (Magic 1)            |
| 0x04 - 0x05    | uint16 BE  | Opcode / CmdId    | เลขรหัสคำสั่ง (ushort)           |
| 0x06 - 0x07    | uint16 BE  | Header Length     | ขนาดส่วนหัว (ushort)            |
| 0x08 - 0x0B    | uint32 BE  | Payload Length    | ขนาด Protobuf Payload (uint)    |
| 0x0C - ...     | byte[]     | Header Bytes      | ส่วนหัวแพ็กเก็ต                 |
| ... - ...      | byte[]     | Payload Bytes     | ข้อมูล Protobuf                 |
| End - 4        | uint32 BE  | TAIL_CONST        | 0xD7A152C8 (Magic 2)            |
+-----------------------------------------------------------------------------------+
```

> [!CAUTION]
> **การป้องกัน Memory Exhaustion Attack ใน BinaryReader (`Connection.cs`):**  
> `BinaryReader.ReadBytes(n)` ใน .NET จะจัดสรร Memory ตามค่า `n` ที่อ่านได้ทันที หากไคลเอนต์ประสงค์ร้ายส่งค่า `payloadLength` สูงผิดปกติ (เช่น 2 GB) เซิร์ฟเวอร์จะเกิด Out-Of-Memory Crash ทันที  
> Reference C# AOT Server จึงเพิ่มระบบป้องกัน:
> ```csharp
> var remaining = br.BaseStream.Length - br.BaseStream.Position;
> if (headerLength + (long)payloadLength > remaining) {
>     Logger.Error("Bad Data Package: payloadLength exceeds remaining buffer");
>     return;
> }
> ```

### 3.3 Ec2b Key Derivation และ MT19937 XOR Key Pipeline
หากเปิดตัวเลือก `UsePacketEncryption = true` ในคอนฟิก:
1. เซิร์ฟเวอร์จะโหลดหรือสร้างไฟล์คีย์ `ClientSecretKey.ec2b` (`HEAD_MAGIC = 1647469381` หรือ ASCII `"Ec2b"`)
2. ตัวคีย์บรรจุ:
   - 16 ไบต์คีย์หลัก (`Key`)
   - 2048 ไบต์เวกเตอร์การถอดรหัส (`Data`)
3. ตัวสร้างสุ่ม Mersenne Twister **MT19937 (64-bit)** ถูกนำมาใช้สร้างตาราง XOR Key ขนาด 4,096 ไบต์ (`Crypto.GenerateXorKey(seed)`)
4. ทุกแพ็กเก็ตที่รับเข้าหรือส่งออกจะถูกทำการ XOR ด้วยตารางคีย์นี้

---

## 4. กลไกการฉีดสคริปต์เข้าไคลเอนต์ (Client Lua Script Injection Engine)

ฟีเจอร์เด่นของ Reference C# AOT Server คือการสื่อสารกับ Unity Client โดยตรงผ่านการส่งโค้ดภาษา Lua ผ่าน `HandshakePacket` ซึ่งไคลเอนต์เกมจะรันสคริปต์นี้บนตัวเครื่องโดยอัตโนมัติ:

### 1. ระบบ Watermark (`BuildWatermarkLua`):
เซิร์ฟเวอร์ส่งโค้ด Lua ไปค้นหา GameObject ของ Unity ในหน้าต่างเกม:
```lua
local function modify_texts()
    local vGo = CS.UnityEngine.GameObject.Find("VersionText")
    if vGo == nil then return end
    local vt = vGo:GetComponent("Text")
    vt.supportRichText = true
    vt.text = "<color=#FEC6DF>Reference C# AOT Server</color> | UID: 10001"
    vt.fontSize = 18
end
pcall(modify_texts)
```
ทำให้หน้าจอเกมแสดงชื่อเซิร์ฟเวอร์, UID, เวอร์ชัน หรือข้อความไล่เฉดสี (Color Gradient) โดยไม่ต้องแก้ไขไฟล์ตัวเกมของไคลเอนต์

### 2. ระบบจำลองสถานะเครือข่าย (`NetStatusLua`):
ส่งโค้ด Lua ไปควบคุมไอคอน Ping และแสดงค่า Latency คงที่ตามที่ตั้งไว้ในคอนฟิก

---

## 5. ระบบจัดเก็บข้อมูลและการจำลองฐานข้อมูล (Persistence & Database Pipeline)

### 5.1 Dual-Engine: SQLite & MySQL
Reference C# AOT Server รองรับทั้งฐานข้อมูลเดี่ยว (SQLite สำหรับ Local/Single-player) และฐานข้อมูลเซิร์ฟเวอร์ (MySQL สำหรับ Production):
- กำหนดใน `config.json` $\rightarrow$ `Database.DatabaseType`: `"sqlite"` หรือ `"mysql"`
- ตารางทั้งหมดถูกสร้างขึ้นอัตโนมัติเมื่อเริ่มระบบผ่าน `EntityStores.Map.Values.EnsureTable(conn)`

### 5.2 In-Memory Dirty Cache & Asynchronous Periodic Flusher
เพื่อลด I/O คอขวด Reference C# AOT Server ไม่เขียนข้อมูลลงดิสก์ทุกครั้งที่มีการเปลี่ยนไอเทม แต่ใช้สถาปัตยกรรม **In-Memory Cache ร่วมกับ Dirty Tracking**:

```mermaid
sequenceDiagram
    autonumber
    participant GameAction as Game Action (e.g. Add Item)
    participant MemoryMap as UidInstanceMap (In-Memory)
    participant DirtySet as DirtyUids (HashSet)
    participant Flusher as SaveThread (Background Task)
    participant Disk as SQLite / MySQL Database

    GameAction->>MemoryMap: Update Entity Object in Memory
    GameAction->>DirtySet: DatabaseHelper.MarkDirty(playerUid)
    Note over MemoryMap,DirtySet: ผู้เล่นเล่นเกมต่อได้ทันที โดยไม่มี I/O Latency

    loop ทุกๆ 1 วินาที (CalcSaveDatabase)
        Flusher->>DirtySet: ดึงรายการ UIDs ที่มีการแก้ไข (DirtyLock)
        Flusher->>MemoryMap: อ่าน Snapshot ข้อมูลของ UID นั้นๆ
        Flusher->>Disk: ทำ Batch Transaction บันทึกลงฐานข้อมูล
        Flusher->>DirtySet: ลบ UID ออกจาก DirtySet
    end
```

> [!TIP]
> **NativeAOT Thread Safepoint Fix (`DatabaseHelper.cs`):**  
> ใน .NET 10 โค้ดที่รันวนลูปแน่น (Tight Loop) ภายใต้ NativeAOT จะไม่มีจุด Safepoint สำหรับ Garbage Collector ทำให้เกิดสภาวะ Deadlock  
> Reference C# AOT Server จึงใส่ `Thread.Sleep(1000)` ใน `SaveThread` เพื่อเปิดช่อง Safepoint ให้ GC ทำงานได้อย่างสมบูรณ์

---

## 6. ระบบแคชทรัพยากรเกมความเร็วสูง (High-Speed Binary Resource Cache)

โดยทั่วไป เซิร์ฟเวอร์เกมต้องอ่านไฟล์ JSON นับร้อยไฟล์จาก `ExcelOutput/` ซึ่งใช้เวลา 30 ถึง 60 วินาทีในทุกครั้งที่เปิดเครื่อง  
Reference C# AOT Server แก้ปัญหานี้ด้วย **`ResourceCache.cs`**:

1. **First Boot (สร้างแคชครั้งแรก)**:
   - อ่าน JSON จาก `Resources/ExcelOutput/` และ `Resources/ExcelOutputGameCore/`
   - รวบรวมข้อมูลลงใน `GameDataSnapshot`
   - ทำ Serialization ด้วย **`MemoryPack`** ซึ่งเป็น Zero-allocation Binary Serializer
   - บีบอัดข้อมูลด้วย **`GZipStream(CompressionLevel.Optimal)`** บันทึกเป็นไฟล์ `Config/Resource.bin` (ขนาดประมาณ 20-30 MB)
2. **Subsequent Boots (การบูตครั้งถัดไป)**:
   - ตรวจสอบความถูกต้องของ Magic Header GZip (`0x1F 0x8B`)
   - คลายการบีบอัดและคืนค่าเข้า `GameData` ภายใน **ไม่เกิน 1 วินาที**
3. **Operator Hot-Reload สำหรับ Banners**:
   - ไฟล์ `Banners.json` (ตู้กาชาที่ผู้ดูแลปรับแต่งได้เอง) จะไม่ถูกรวมเข้า `Resource.bin` แต่จะถูกอ่านแยกสด เพื่อให้แก้ไขและเปิด/ปิดตู้กาชาได้ทันทีโดยไม่ต้องล้างแคชเกมใหม่

---

## 7. ระบบการต่อสู้และการแทรกแซงสถานการณ์ (Battle & Calyx Override Engine)

### 7.1 ลูปการต่อสู้หลัก
- เริ่มต้นจาก `BattleManager.StartBattle()` เมื่อมี Technique Cast หรือมอนสเตอร์โจมตี
- สร้าง `BattleInstance` ซึ่งรวบรวม Wave มอนสเตอร์, เลเวลตัวละคร, MazeBuff (บัฟจุดอ่อนของธาตุที่โจมตี)
- รองรับด่านหลากหลายรูปแบบ: Mainline, Cocoon (ฟาร์มของ), FarmElement, BattleCollege (บทเรียนการต่อสู้)

### 7.2 Calyx Override & FreeSR JSON Scenario Injection
ฟีเจอร์ระดับสูงที่สำคัญที่สุดใน Reference C# AOT Server คือ **`CalyxOverrideManager.cs`** และ **`FreesrShared.cs`**:
- ผู้พัฒนาสามารถใส่ไฟล์สถานการณ์จำลองในรูปแบบ **FreeSR JSON** ไว้ในไดเรกทอรี `Config/Json/*.json`
- เมื่อเปิดใช้งานผ่านคำสั่ง `/calyx` หรือ `CalyxOverrideManager.Enable()`:
  - เซิร์ฟเวอร์จะดักจับการเข้าด่าน Calyx (ดอกไม้ฟาร์มเงิน/EXP) ในโลกเปิด
  - แทนที่มอนสเตอร์และด่านเดิมของ Calyx ด้วยการต่อสู้ที่ระบุในไฟล์ FreeSR JSON ทันที
  - สามารถสลับทีมตัวละคร (`TrySetLineupOverride`), ปรับแต่งเลือดมอนสเตอร์เป็นรายตัวและรายเวฟ (`TrySetMonsterHp`)
  - ทำให้สามารถทดสอบบอสใหม่, มอนสเตอร์จากแพตช์ล่วงหน้า หรือจัด Challenge พิเศษได้โดยไม่ต้องแก้เกม

---

## 8. ระบบโหมดการเล่นขั้นสูง (Modern End-Game Modes)

Reference C# AOT Server เป็นหนึ่งในเซิร์ฟเวอร์ไม่กี่แห่งที่รองรับโหมดการเล่นระดับ Endgame ยุคใหม่ของ Honkai: Star Rail:

### 8.1 ChallengePeak (Apocalyptic Shadow & Anomaly Arbitration)
- ควบคุมผ่าน `ChallengePeakManager.cs`
- รองรับโหมด **Apocalyptic Shadow (เงามายาแห่งกลียุค)** และ **Anomaly Arbitration**
- จัดการบอสที่มีหลายเฟสและกลไกพิเศษ (เช่น บอสมีเกจ Toughness พิเศษ)
- รองรับการจัดทีมแบบ Tierce (ด่าน 3 เฟส/ทีมย่อย)

### 8.2 Divergent Universe & Unknowable Domain
- ควบคุมผ่าน `ChessRogue` และ `RogueTourn` (TournRoomGenerator)
- จัดการระบบสมการ (Equations), ถ่วงน้ำหนักพร, Curio พิเศษ และวงล้อโชคชะตา
- รองรับห้องบันทึกการสังเคราะห์ (Archive Repository)

### 8.3 Currency War & GridFight (Aetherium Wars)
- **`GridFightManager`**: จำลองระบบมินิเกมกระดานและการแข่งขันมอนสเตอร์ (Aetherium Wars)
- **`Currency War`**: จำลองเกมสงครามการเงิน มีระบบกระดาน, ซื้อ/ขายไอเทม และร้านค้าในมินิเกม

---

## 9. การจัดการระยะไกลและหน้าต่างควบคุม (Muip Protocol & Admin Dashboard)

### 9.1 Muip GM Protocol (RSA-Encrypted Remote Command Execution)
Reference C# AOT Server พัฒนาระบบ Muip (Management User Interface Protocol) เพื่อให้แอปพลิเคชันภายนอก, Bot Discord หรือเว็บแอดมิน ติดต่อสั่งการเซิร์ฟเวอร์ได้อย่างปลอดภัยผ่านการเข้ารหัส **RSA Public/Private Key (PKCS#1)**:

1. `POST /muip/create_session`:
   - เซิร์ฟเวอร์สร้าง RSA Keypair และส่ง `rsaPublicKey` พร้อม `sessionId` กลับมา (มีอายุจำกัด)
2. `POST /muip/auth_admin`:
   - ไคลเอนต์ส่ง `admin_key` ที่ถูกเข้ารหัสด้วย `rsaPublicKey` เพื่อยืนยันสิทธิ์ผู้ดูแล
3. `POST /muip/exec_cmd`:
   - ส่งคำสั่งเกม (เช่น `/give 1001 x1`) ที่เข้ารหัสด้วย RSA พร้อมระบุ `TargetUid` เซิร์ฟเวอร์ถอดรหัสและรันคำสั่งทันที
4. `GET /muip/server_information` & `/muip/player_information`:
   - ขอข้อมูลสถิติเซิร์ฟเวอร์ (RAM, ผู้เล่นออนไลน์) และข้อมูลไอดีผู้เล่น

### 9.2 Built-in Embedded Web Admin & Registration Portal
- ไม่จำเป็นต้องเปิด Web Server แยกต่างหาก เพราะ WebServer ของ Reference C# AOT Server มีเว็บ Dashboard ในตัว
- เขียนด้วย Embedded HTML/CSS/JS (`AdminPageRenderer.cs`, `AdminPageScripts.cs`)
- มีหน้าระบบลงทะเบียนผู้เล่น (`RegistrationPage.cs`), หน้ารีเซ็ตรหัสผ่านผ่านอีเมล (`PasswordForgotPage.cs`, `AccountEmailSender.cs`), และหน้าจัดการไอดี

### 9.3 Cluster Deployment via ServerExchange Secret
- รองรับการแยกรัน Dispatch Server และ Game Server บนเครื่องเซิร์ฟเวอร์คนละเครื่อง
- สื่อสารระหว่างโหนดผ่าน `/get_account_info` และ `/validate_account_token` โดยยืนยันความปลอดภัยผ่าน HTTP Header `X-Reference C# AOT Server-Server-Secret` ตรวจสอบความเท่ากันแบบคงเวลา (`FixedTimeEquals`) เพื่อป้องกัน Timing Attack

---

## 10. ตารางเปรียบเทียบเชิงลึก: LunarCore vs Reference C# AOT Server

| มิติการเปรียบเทียบ | LunarCore (Melledy) | Reference C# AOT Server (Reference Author) |
|---|---|---|
| **ภาษาและรันไทม์** | Java 17+ (Gradle / JVM) | C# (.NET 10 SDK) |
| **สถาปัตยกรรมประสิทธิภาพ** | Reflection รันไทม์, Quickbuf Proto | Roslyn Source Generators, **NativeAOT**, MemoryPack |
| **เครือข่าย UDP/KCP** | Java KCP (Netty UDP Channel) | **KcpSharp** (Pure C# Zero-alloc + ArrayPool) |
| **การเข้ารหัสทราฟฟิก** | XOR แบบธรรมดา (ปิดไว้เป็นค่าตั้งต้น) | รองรับ **Ec2b** Key Derivation + MT19937 XOR 4KB |
| **การเก็บข้อมูล (Storage)** | MongoDB (ภายนอก) หรือ H2 Mongo (ภายใน) | **SQLite** และ **MySQL** (In-Memory Dirty Flusher) |
| **การแคชทรัพยากรเกม** | โหลดไฟล์ JSON สดทุกครั้งที่เปิด (~15-30 วิ) | **Resource.bin** (MemoryPack + GZip) บูต < 1 วินาที |
| **การฉีดโค้ดสู่ไคลเอนต์** | ไม่มี | **Server-Pushed Lua Injection** (Watermark, Ping UI) |
| **เครื่องมือทดสอบการต่อสู้** | ผ่านคำสั่ง `/spawn` และ Stage IDs ปกติ | **Calyx Override + FreeSR JSON Scenario Injection** |
| **โหมดเกมที่รองรับ** | พื้นฐาน: MoC, Pure Fiction, SU ปกติ | ขั้นสูง: **Apocalyptic Shadow**, **Divergent Universe**, **Currency War**, Aetherium Wars |
| **ระบบบริหารจัดการ (GM/Web)**| คอนโซล และ แชตในเกมผ่านบอท UID 99 | **Muip RSA API**, Web Admin Dashboard, Web Registration |

---

## 11. คู่มือการต่อยอดเชิงวิศวกรรมสำหรับ AI (AI Implementation Guidelines)

หากโมเดล AI อื่นต้องการสร้างส่วนต่อขยาย, แก้บั๊ก หรือเขียนตัวแปลงโปรโตคอลสำหรับ Reference C# AOT Server:

1. **อย่าใช้ Reflection สำหรับ Handler และ Database Store**:  
   ต้องใช้ระบบ Source Generator เสมอ หากเพิ่ม Entity ใหม่ ให้สร้างคลาสที่สืบทอดจาก `BaseDatabaseDataHelper` เพื่อให้ `DatabaseStoreGenerator` สร้างโค้ด SQL ตารางและการแมปให้อัตโนมัติ เพื่อรักษาคุณสมบัติ NativeAOT
2. **การจัดการ Entity ในหน่วยความจำ**:  
   เมื่อแก้ไขข้อมูล Entity ของผู้เล่น ต้องเรียก `DatabaseHelper.MarkDirty(player.Uid)` เสมอ เพื่อให้ Background Flusher รับรู้และนำไปบันทึกลง SQLite/MySQL
3. **การทดสอบฉากต่อสู้แบบกำหนดเอง**:  
   ใช้โครงสร้าง FreeSR JSON ในโฟลเดอร์ `Config/Json/` ร่วมกับ `CalyxOverrideManager` จะช่วยให้จำลองการต่อสู้กับบอสใดๆ ได้ทันทีโดยไม่ต้องรื้อ Resource Excel
4. **ความปลอดภัยของ Buffer**:  
   ในส่วนการอ่าน Binary Packets ให้คงการตรวจสอบ `remaining buffer` ไว้เสมอ เพื่อป้องกันช่องโหว่ Buffer Overflow และการจัดสรรหน่วยความจำเกินขนาด