# HANDOFF REPORT: FREEEXILE SKILLS, VFX & ANIMATION SURVEY

- **Agent**: `explorer_survey_1`
- **Tác vụ**: Điều tra toàn diện 12 Kỹ năng Võ Học chủ động, 5 Thần Biến Phù hỗ trợ, cơ chế render VFX cũ/mới, thông số chuỗi khung hình và cấu trúc hoạt ảnh mở rộng cho Quái Vật và Nhân Vật.
- **Thời gian lập**: 2026-10-04T12:18:00Z
- **Thư mục làm việc**: `c:\Projects\FreeExile\.agents\teamwork\explorer_survey_1`
- **Báo cáo chi tiết**: `c:\Projects\FreeExile\.agents\teamwork\explorer_survey_1\analysis.md`

---

## 1. OBSERVATION

1. **12 Kỹ Năng Võ Học Chủ Động (Active Skills)**:
   - Được định nghĩa tại `server/world/martial_catalog.py:22-266` và `client/cocos/assets/scripts/data/skill_catalog.ts:6-344`.
   - Lưu trữ trực tiếp trong CSDL SQLite:
     - `data/martial_database.db`: Bảng `skills` chứa 12 bản ghi (ID 1001 đến 1012).
     - `data/game_design_matrix.db`: Bảng `skills` chứa 12 bản ghi (ID 1001 đến 1012).
   - Danh sách định danh verbatim:
     - 1001: `Cửu Tiêu Lôi Kiếm` (Kim/Lôi, `SWORD`, Cast: 650ms, CD: 1800ms)
     - 1002: `Thanh Phong Vạn Kiếm Vũ` (Kim/Lôi, `SWORD`, Cast: 300ms, CD: 500ms)
     - 1003: `U Minh Huyết Độc Châm` (Mộc/Độc, `PROJECTILE_WEAPON`, Cast: 350ms, CD: 800ms)
     - 1004: `Thiên Ma Bộc Độc Kình` (Mộc/Độc, `ANY`, Cast: 450ms, CD: 3500ms)
     - 1005: `Băng Phách Hàn Quang Trận` (Thủy/Hàn, `STAFF`, Cast: 600ms, CD: 10000ms)
     - 1006: `Băng Tiễn Xuyên Tâm` (Thủy/Hàn, `STAFF`, Cast: 400ms, CD: 1500ms)
     - 1007: `Liệt Hỏa Toàn Phong Trảm` (Hỏa/Diễm, `BLADE`, Cast: 200ms, CD: 0ms Channeling)
     - 1008: `Liệt Diễm Bộc Khí Trảm` (Hỏa/Diễm, `BLADE`, Cast: 750ms, CD: 4000ms)
     - 1009: `Kim Cang Trụy Địa Chấn` (Thổ/Kim Cang, `STAFF`, Cast: 800ms, CD: 4500ms)
     - 1010: `Kim Cang Bất Hoại Thể` (Thổ/Kim Cang, `UNARMED`, Cast: 300ms, CD: 14000ms)
     - 1011: `Huyết Ma Khấp Huyết Kình` (Mộc/Chaos Hỗn Mang, `ANY`, Cast: 500ms, CD: 6000ms)
     - 1012: `Man Cốt Triệu Hồn Đồ` (Thổ/Man Cốt, `ANY`, Cast: 1200ms, CD: 15000ms)
     - *(Kỹ năng né tránh cơ bản: 1099 `Huyễn Ảnh Bộ`, i-frame 0.25s, CD: 3000ms)*.

2. **Hệ Thống Thần Biến Phù (Support Sigils)**:
   - Được định nghĩa tại `server/world/martial_catalog.py:269-412`, `data/martial_database.db` (bảng `support_gems`, 10 bản ghi), và `client/cocos/assets/scripts/data/support_skill_catalog.ts:4-130`.
   - 5 Thần Biến Phù cốt lõi thay đổi hình thái đồ họa VFX:
     - 2001: `Phân Quang Đa Hóa Phù` (Multi-Projectile, +3 tia đạn, x0.65 dmg)
     - 2002: `Bộc Phá Khuếch Đại Phù` (Area of Effect, +50% AoE radius, x0.80 dmg)
     - 2004: `Huyết Khí Quy Tông Phù` (Blood Magic, chuyển cost thành Máu, Ward = 0, x1.25 dmg)
     - 2005: `Lôi Đình Xâu Chuỗi Phù` (Chain Lightning, nảy chuỗi 3 mục tiêu bán kính 6m, x0.85 dmg)
     - 2006: `Hàn Khí Cực Lãnh Phù` (Freeze Affliction, 100% Đóng Băng, khống chế cứng)
   - Trong `client/cocos/assets/scripts/combat/CombatController.ts:64-68` và `171-188`:
     - Loadout Q sử dụng 1001 link với [2001, 2002]
     - Loadout W sử dụng 1007 link với [2005]
     - Loadout E sử dụng 1011 link với [2004]

3. **Cơ Chế Render Cũ vs Hệ Thống Mới**:
   - WebApp cũ: `client/webapp/js/engine/vfx_renderer.js` render 100% procedural bằng Canvas 2D:
     - `vfx_slashes` (dòng 5–71): `ctx.arc()`, `ctx.stroke()`, `ctx.shadowBlur = 18`
     - `vfx_spikes` (dòng 74–140): `ctx.moveTo()`, `ctx.lineTo()`, `ctx.fill()`
     - `vfx_lightnings` (dòng 143–219): `ctx.lineTo()` nối 7 đoạn ziczac, `ctx.ellipse()`
     - `particles` (dòng 224–236): vòng tròn điểm chấm `ctx.arc(pt.x, pt.y, pt.radius...)`
   - Cocos Creator 3.8.x mới:
     - `client/cocos/assets/scripts/animation/SpriteAtlasRenderer.ts`: Quản lý lưới 8 cột (cols=8), pivot `[0.5, 0.90]`, tính toán UV coordinates theo manifest JSON.
     - `client/cocos/assets/resources/shaders/sprite_pbr.effect`: Shader PBR hỗ trợ Tangent-Space Normal Map, Specular Blinn-Phong và Emissive channel.
     - `tools/asset_pipeline/produce_all_missing_skills_vfx.py`: Sinh atlas PoT 1024x1024 (`savage_primal_skills_vfx_atlas.png`), normal map Sobel (`savage_primal_skills_vfx_atlas_normal.png`) và manifest JSON (`savage_primal_skills_vfx_atlas.json`).

4. **Quái Vật & Cặp Song Binh Nhân Vật**:
   - `data/game_design_matrix.db` (bảng `monster_archetypes`): 100 quái vật thuộc 10 Chi (`RISEN_SKELETON`, `FERAL_HELLHOUND`, `BLOOD_CRAWLER`, `BRAMBLE_TREANT`, `CORRUPTED_RAPTOR`, `FLESH_ABOMINATION`, `IRONHIDE_BEHEMOTH`, `PRIMAL_CANNIBAL`, `SHADOW_WRAITH`, `TOMB_LORD`).
   - 8 hướng: `S`, `SW`, `W`, `NW`, `N`, `NE`, `E`, `SE` (ánh xạ row 0 đến 7 theo `Math25D.ts` và `SpriteAtlasRenderer.ts`).
   - Nhân vật: 6 class (`char_sword_master`, `char_sword_maiden`, `char_feral_berserker`, `char_wild_archer`, `char_glacial_lancer`, `char_shadow_assassin`) sở hữu cặp Song Binh hoán đổi trong 0ms (`WEAPON_SWAP_PAIRS`).

---

## 2. LOGIC CHAIN

1. Từ **Observation 1 & 2**: Toàn bộ hệ thống kỹ năng của FreeExile đã được chuẩn hóa thành 12 Active Skills (ID 1001 - 1012) và 10 Support Sigils (trong đó 5 Sigils 2001, 2002, 2004, 2005, 2006 tác động trực tiếp lên hình thái VFX).
2. Từ **Observation 3**: WebApp hiện tại vẫn đang vẽ hình học thô sơ bằng `vfx_renderer.js` (`ctx.arc`, `ctx.lineTo`, `ctx.shadowBlur`), không có Normal map, không thể bắt sáng PBR 2.5D và tiêu tốn CPU lớn trên thiết bị di động.
3. Từ **Observation 3 & 4**: Để đạt mục tiêu 120 FPS ProMotion trên iOS Metal và Cocos Creator 3.8.x, toàn bộ các kỹ năng cần được chuyển đổi sang định dạng Texture Atlas nhị phân chuẩn PoT ($1024\times 1024$ / $2048\times 2048$), đi kèm Tangent-Space Sobel Normal Maps (kênh Blue $\ge 128$) và UV JSON Manifest tương thích với `SpriteAtlasRenderer.ts`.
4. Điểm neo đáy `pivot: [0.5, 0.90]` là bắt buộc để triệt tiêu hiện tượng trôi trượt chân khi nhân vật di chuyển và thi triển hoạt ảnh trên lưới isometric 2:1.
5. Do đó, việc sản xuất đồ họa và đóng gói tài nguyên mới sẽ thay thế hoàn toàn chuỗi procedural canvas shader cũ bằng Sprite Sheet PBR chuẩn mực.

---

## 3. CAVEATS

- **Phạm vi khảo sát**: Hoàn toàn ở chế độ Read-Only, không trực tiếp sửa đổi mã nguồn hay ghi đè các tệp tài nguyên hiện có của dự án.
- **Support Sigils**: Mặc dù codebase chứa 10 Support Sigils, hệ thống VFX thực tế chỉ cần chuỗi hoạt ảnh chuyên biệt cho 5 Sigils thay đổi trực quan (Đa Hóa Đạn Đạo, Khuếch Đại AoE, Huyết Kế Ma Pháp, Lôi Đình Xâu Chuỗi, Hàn Khí Cực Lãnh), các Sigil còn lại chủ yếu tác động thông số số học (Damage/Cooldown/Cast speed).
- **Hệ thống WebApp vs Cocos**: WebApp sử dụng canvas 2D truyền thống; Cocos Creator 3.8.x sử dụng WebGL/Metal shader pipeline. Cần duy trì tính tương thích ngược của file manifest JSON giữa cả hai nền tảng.

---

## 4. CONCLUSION

- **12 Active Skills**: Khảo sát hoàn tất 100% ID (1001 đến 1012), tên gọi, ngũ hành, tông môn, căn cốt, vũ khí, thông số cast/cooldown/lock, cơ chế combo PoE2 và phong cách thị giác hoang dã hắc ám.
- **5 Support Sigils**: Khảo sát hoàn tất ID 2001, 2002, 2004, 2005, 2006 cùng quy chuẩn trigger và hình thái đồ họa.
- **VFX Rendering Pipeline**: Xác định chính xác 4 vị trí procedural drawing trong `vfx_renderer.js` cần thay thế bằng Texture Atlas PoT và shader `sprite_pbr.effect` trong Cocos.
- **Quy chuẩn Hoạt ảnh**: Đã chuẩn hóa cấu trúc 8 hướng cho 10 Chi Quái Vật (100 archetypes) và 6 Lớp Nhân Vật Lưu Đày kèm cặp Song Binh.
- Toàn bộ kết quả điều tra đã được văn bản hóa chi tiết tại `c:\Projects\FreeExile\.agents\teamwork\explorer_survey_1\analysis.md`.

---

## 5. VERIFICATION METHOD

1. **Kiểm tra tính toàn vẹn của CSDL Kỹ Năng & Quan Sát Test**:
   - Chạy lệnh: `python -m unittest tests/unit/test_skill_database_and_tags.py`
   - *Ghi nhận thực tế*: 17/18 tests PASS. Riêng `test_database_initialization_and_seeding` tại dòng 38 assert `count == 10` trong khi catalog hiện tại đã mở rộng lên **12 Active Skills** (`AssertionError: 12 != 10`), chứng minh trực tiếp rằng catalog đã nâng cấp từ 10 lên 12 kỹ năng chuẩn mực.

2. **Kiểm tra chuỗi hoạt ảnh và VFX kỹ năng**:
   - Chạy lệnh: `python -m unittest tests/unit/test_character_animation_and_skills_vfx.py`
   - *Kết quả*: 100% test cases PASS (xác thực state machine, 8 hướng, 3 hệ VFX đạn đạo và sprite atlas).

3. **Kiểm tra ma trận Game Design**:
   - Chạy lệnh: `python tools/lint/verify_game_design_matrix.py`
   - *Kết quả*: `[PASS]` 100% IN SYNC (xác nhận Active Skills: 12, Monster Archetypes: 100, Base Weapons: 30).

4. **Đối soát tệp báo cáo**:
   - Mở `c:\Projects\FreeExile\.agents\teamwork\explorer_survey_1\analysis.md` để kiểm tra bảng chi tiết 12 skills, 5 support sigils và cấu trúc monster/character conventions.