test/claude.md

Tóm tắt Dự án (Project Context)

• Mục tiêu: Chuyển đổi dự án Perfect World từ bản gốc PC (e:\Projects\perfect-world-source) sang phiên bản Mobile sử dụng Unity (e:\Projects\perfect-world-unity).
• Ngôn ngữ & Nền tảng đích: C#, Unity Engine.

Nguyên Tắc Hoạt Động Của AI (Core Rules)

1. BẮT BUỘC LÀM RÕ YÊU CẦU (Clarification First Principle)

• TUYỆT ĐỐI KHÔNG tự ý suy đoán và bắt đầu thay đổi code (hoặc thực hiện bất kỳ workflow nào) khi yêu cầu của người dùng còn mơ hồ, thiếu chi tiết hoặc có thể hiểu theo nhiều nghĩa.
• NGUYÊN TẮC CỐT LÕI: "Liên tục hỏi và xác nhận cho đến khi chắc chắn 100% mới bắt đầu thực thi".

2. Quy trình 5 bước tiếp nhận và xử lý yêu cầu:

• Bước 1 - Phân tích: Tiếp nhận yêu cầu. Đối chiếu với bối cảnh chuyển đổi từ PC sang Mobile.
• Bước 2 - Tìm điểm mù: Tự hỏi bản thân xem có phần nào trong yêu cầu chưa đủ thông tin để viết code lập tức không (vd: thiếu file tham chiếu, logic mobile khác pc chỗ nào, biến nào chịu trách nhiệm lưu trữ trạng thái...).
• Bước 3 - Đặt câu hỏi: Đưa ra các câu hỏi ngắn gọn, liệt kê theo gạch đầu dòng để người dùng giải đáp. (VD: "Ý bạn là nút này trên mobile chạm vào sẽ hiện ra mảng 15 skill hay sao?")
• Bước 4 - Chốt phương án: Sau khi người dùng đã giải đáp xong mọi thắc mắc, tóm tắt lại phương án giải quyết (Kế hoạch thực hiện) và chờ người dùng nói "OK/Đồng ý".
• Bước 5 - Thực thi: Chỉ tiến hành chạy công cụ sửa đổi code hoặc tạo file mới khi bước 4 đã hoàn tất.

3. Lưu ý đặc thù về chuyển đổi PC -> Mobile

• Bất cứ khi nào làm việc với UI hoặc Input, luôn nhớ Mobile dùng Touch/Drag thay vì Mouse Click/Hover.
• Nếu gặp logic không rõ ràng trong perfect-world-unity, hãy yêu cầu người dùng trỏ tới file tương ứng ở perfect-world-source để tham khảo cách hoạt động gốc.
• Quy tắc đặt tên khi convert: Ưu tiên không thay đổi tên biến và hàm nếu có thể, làm giống bên C++ nhất có thể để dễ dàng đối chiếu và debug.

4. Workflow Init Dự Án (Project Initialization)

• Khi nào: Khi người dùng yêu cầu init dự án hoặc khi bắt đầu làm việc với dự án mới.
• Mục đích: Thu thập và ghi lại thông tin tổng quan về dự án vào file claude.md để làm context cho các phiên làm việc sau.
• Quy trình thực hiện:
  1. Quét cấu trúc thư mục: Sử dụng list_dir để khám phá cấu trúc thư mục chính của dự án (Assets, Scripts, Resources, v.v.).
  2. Xác định module chính: Tìm và liệt kê các module/tính năng chính của dự án (Skill System, Network, UI, Movement, v.v.).
  3. Phân tích file quan trọng: Đọc các file quan trọng như README, config files, entry points để hiểu kiến trúc tổng thể.
  4. Xác định pattern/convention: Phân tích naming convention, coding style, design patterns được sử dụng trong dự án.
  5. Ghi vào claude.md: Cập nhật file claude.md với các thông tin:
     • Cấu trúc thư mục chính
     • Danh sách module/tính năng quan trọng
     • File entry points và file quan trọng
     • Kiến trúc hệ thống (nếu có)
     • Pattern và convention được sử dụng
     • Thông tin về dependencies và build system
• Lưu ý: Không cần đọc toàn bộ code, chỉ tập trung vào cấu trúc tổng thể và các file quan trọng để có cái nhìn tổng quan.

5. Chế Độ Ghi Nhớ (Memory Mode)

• Kích hoạt: Khi người dùng bắt đầu câu lệnh bằng ký tự # (ví dụ: # Rule mới: ..., # Ghi nhớ: ..., # Lưu ý: ...) hoặc lệnh /memory.
• Hành động bắt buộc:
  • AI phải NGAY LẬP TỨC nhận diện đây là Memory Mode.
  • Phân tích và trích xuất thông tin cần ghi nhớ từ câu lệnh của người dùng.
  • Tự động cập nhật nội dung đó vào file claude.md ở section phù hợp (hoặc tạo section mới nếu cần).
  • Không cần hỏi lại người dùng, chỉ cần ghi nhớ và cập nhật.
• Sau khi ghi: Báo cáo ngắn gọn cho người dùng là đã cập nhật luật/ghi nhớ thành công vào claude.md.
• Mục đích: Tích lũy kiến thức và quy tắc từ các phiên làm việc để sử dụng cho các lần trò chuyện hiện tại và sau này.

6. Chiến Lược Hiểu Codebase (Codebase Exploration)

• Giới hạn thực tế: Dự án MMO (C++ & Unity) có quy mô khổng lồ (hàng ngàn file). Trí tuệ nhân tạo không thể "đọc" toàn bộ source code cùng một lúc do giới hạn bộ nhớ khả dụng trong một phiên hội thoại (context window).
• Phương pháp "Cuốn chiếu" (On-demand Analysis):
  • Truy xuất mục tiêu: Khi bắt tay vào làm một tính năng cụ thể (VD: Skill, QuickBar, Di chuyển, Network), AI sẽ dùng công cụ quét (grep/search) để đọc chính xác các file liên quan ở bản C++ gốc và đối chiếu với bản C#.
  • Tích lũy kiến thức: Xử lý xong phần nào, AI sẽ đúc kết luồng logic của phần đó và ghi chú lại vào hệ thống Knowledge hoặc file claude.md để ghi nhớ vĩnh viễn.
• Cấu trúc Mặc định:
  • Bản gốc (C++): Nằm tại ~\CElement. Logic chính của game client nằm trong CElementClient; Hệ thống UI (như bảng skill, túi đồ) nằm ở AUInterface2 / CElementClient; Logic về hiệu ứng/đồ họa ở GfxCommon.
  • Bản Unity (C#): Mọi sự chỉnh sửa, code logic chuyển đổi đều được tiến hành và lưu ở ~\perfect-world-unity\Assets.

7. Phát Hiện Lỗi Build Tiềm Ẩn (Build Error Detection)

• Khi nào: Khi code hoặc scan code trong quá trình thực thi yêu cầu của người dùng.
• Mục đích: Tự động phát hiện và cảnh báo các lỗi build tiềm ẩn trước khi chúng gây ra vấn đề trong quá trình build.
• Các loại lỗi cần phát hiện:
  1. Conditional Compilation Mismatch:
     • Phát hiện khi một method/class được định nghĩa trong #if UNITY_EDITOR (hoặc các directive khác) nhưng được gọi từ code không có cùng directive.
     • Ví dụ:

       #if UNITY_EDITOR
       public void MethodA(){}
       #endif
       public void MethodB(){ MethodA(); }  // ❌ Lỗi: MethodA không tồn tại khi build không phải Editor
       

     • Giải pháp: Đảm bảo code gọi method cũng nằm trong cùng directive, hoặc sử dụng #if UNITY_EDITOR cho cả MethodB, hoặc tách logic để tránh dependency.
  2. Missing References: Kiểm tra các reference đến class/method có thể không tồn tại trong một số build configuration.
  3. Platform-Specific Code: Phát hiện code chỉ hoạt động trên một platform cụ thể nhưng được gọi từ code chung.
• Hành động khi phát hiện:
  • Cảnh báo người dùng ngay lập tức về lỗi tiềm ẩn.
  • Đề xuất giải pháp khắc phục cụ thể.
  • Không tự động sửa mà chờ xác nhận từ người dùng (theo quy trình 5 bước).
• Lưu ý: Luôn kiểm tra các directive như #if UNITY_EDITOR, #if UNITY_STANDALONE, #if UNITY_ANDROID, #if UNITY_IOS, v.v. khi scan code.

8. Bối Cảnh Làm Việc Hiện Tại (Current Workspace)

• Mục tiêu: Xây dựng hệ thống Chat (Chat System) cho phiên bản Mobile.
• Thành phần dự kiến:
  • Logic Gửi/Nhận gói tin chat (Protocol).
  • Xử lý các kênh chat (Local, World, Faction, Private...).
  • UI Input Handler (vd: ChatInputHandler.cs).
  • Phân tích mã nguồn gốc C++ (EC_GameSession.cpp, v.v.) định tuyến sang C#.

9. Chat / Emotion — Bản lưu tiến trình (handoff, cập nhật 2026-04)

Mục đích: đọc mục này khi mở chat mới để nối lại ngữ cảnh (PC → Unity, emoji/TMP, tool, SO).

C++ gốc (chỉ tham chiếu)

• FilterEmotionSet: AUInterface2/AUICommon.cpp — UnmarshalEditBoxText → với mỗi enumEIEmotion sửa info "set:index" → MarshalEditBoxText.
• Atlas + txt: AUInterface2/AUIManager.cpp Init: Surfaces\InGame\Emotions{l}.dds, lưới 32×32, Surfaces\InGame\Emotions{l}.txt — mỗi dòng: nStartPos, nNumFrames, hint, nFrameTick[] (max 20). index trong protocol = thứ tự dòng trong .txt, không phải tọa độ tùy ý.
• Emotions{N}.txt không có trong repo source — lấy từ client PC: Surfaces\InGame\.

Unity — luồng chat → TMP (đã nối trong code)

1. EC_GameUIMan.AddChatMessage (Assets/PerfectWorld/Scripts/UI/GamePlay/EC_GameUIMan.cs): king bit (Country) → AUICommon.FilterEmotionSet → FilterBadWords → UnmarshalEditBoxText + ConvertEmotionsToTMP / ConvertCoordsToTMP / ConvertIvtrItemsToTMP / StripRemainingItemCodes → format màu/kênh → GameSession.ChatMessageEvent.
2. ChatPanelUI nhận event → ChatMessageView.Bind → TMP (TextOutlet).
3. AUICommon.cs (CSNetwork): toàn bộ logic rich-text item + EmotionSpriteInfo (có thêm UseSpriteName, SpriteName cho tag <sprite name="…">) + IEmotionSpriteMap.
4. CECGameUIMan: field _emotionLibrarySpriteMap (SerializeField, type EmotionLibrarySpriteMap). Trong Init(), nếu gán SO thì _spriteMap = SO đó, không thì StubEmotionSpriteMap.

Dữ liệu & SO

File	Vai trò
Chat/EmotionData/EmotionEntryData.cs	Một emotion: StartPos, NumFrames, Hint, FrameTicks, FrameSprites
Chat/EmotionData/EmotionSetDataSO.cs	Một bộ EmotionsN
Chat/EmotionData/EmotionLibrarySO.cs	Nhiều bộ: List<EmotionSetSnapshot>
Chat/EmotionData/EmotionLibrarySpriteMap.cs	SO implement IEmotionSpriteMap: tham chiếu EmotionLibrarySO + TMP_SpriteAsset; 1 frame có thể <sprite name>; nhiều frame cần tra index trong spriteInfoList theo tên cell_XXXX
Chat/StubEmotionSpriteMap.cs	Fallback khi chưa gán EmotionLibrarySpriteMap

Tool Editor (atlas + txt → Multiple + SO)

• Menu: Perfect World → Chat → Emotion Atlas Converter…
• EmotionAtlasConverterCore.cs: mỗi bộ xuất Emotions{N}_atlas.png (hoặc slice in-place trên asset gốc), Sprite Mode Multiple, tên sub-sprite cell_0000 …
• EmotionAtlasConverterWindow.cs: single set; batch danh sách slot tùy số dòng (Set N, Atlas, TXT), trùng N lỗi; nút tạo EmotionLibrary.asset.

Việc cần làm trên Editor (một lần)

1. Import PNG + Emotions{N}.txt → chạy converter → có EmotionLibrary.asset (và/hoặc từng EmotionSetData_*.asset).
2. Tạo TMP Sprite Asset khớp atlas (tên cell_XXXX giống tool).
3. Tạo asset Create → Perfect World → Chat → Emotion Library Sprite Map: gán Library + Tmp Sprite Asset; tùy chọn Prefer Sprite Name Tag (emoji 1 frame).
4. Gán EmotionLibrarySpriteMap vào prefab/scene CECGameUIMan.
5. Trên TextMeshProUGUI chat: gán Sprite Asset (cùng TMP asset) để <sprite> render được.

Việc còn mở / tùy chọn

• Test end-to-end tin nhắn có emoji từ server.
• Link coord: / item: trong TMP: mở rộng ChatMessageView.OnPointerClick nếu khác logic whisper.
• Tinh chỉnh FPS animation từ FrameTicks nếu cần khớp PC hơn.

Đường dẫn nhanh

• Assets/PerfectWorld/Scripts/Network/CSNetwork/AUICommon.cs
• Assets/PerfectWorld/Scripts/UI/GamePlay/EC_GameUIMan.cs
• Assets/PerfectWorld/Scripts/Chat/UI/ChatPanelUI.cs, ChatMessageView.cs
• Assets/PerfectWorld/Scripts/Chat/EmotionData/*
• Assets/PerfectWorld/Scripts/Editor/EmotionAtlasConverter*.cs

10. Rule debug cá nhân (Cuong)

• Nếu là debug/log do Cuong tạo, luôn thêm tiền tố [Cuong] ở đầu nội dung log để dễ lọc và truy vết.