--- doc_id: "STD-ART-ANIM-VFX-2026" title: "Quy Chuẩn Điều Phối Animation, VFX & Tích Hợp Cocos Engine" category: "standards" diataxis_type: "standard" status: "canonical" version: "2026.1" owner_role: "vfx_tech_artist" last_updated: "2026-10-04" tags: ["animation", "vfx", "cocos-engine", "banana-ai", "procedural", "pbr-shaders", "zero-budget"] related_code: - "tools/asset_pipeline/savage_vfx_factory.py" - "tools/asset_pipeline/process_banana_assets_oct2026.py" - "client/cocos/assets/scripts/animation/SpriteAtlasRenderer.ts" - "client/cocos/assets/resources/shaders/sprite_pbr.effect" related_docs: - "docs/client/SAVAGE_PRIMAL_ART_AND_VFX_BIBLE.md" - "docs/standards/DESIGN_PIPELINE_AND_CROSS_DEPT_WORKFLOW.md" summary: "Quy trình chuẩn hóa phân loại, điều phối công cụ tự hành miễn phí (Banana AI + Python Procedural + Blender Headless) và khai thác tối đa Cocos Engine 3.8.x." --- # FREEEXILE: QUY CHUẨN ĐIỀU PHỐI ANIMATION, VFX & TÍCH HỢP COCOS ENGINE > **Định vị & Tôn chỉ**: Studio Indie $0$ ngân sách phần mềm, $0$ nhân lực vẽ tay thủ công. Toàn bộ quy trình Animation & VFX phải được **Agent tự động hóa $100\%$ khép kín (Zero-Touch)**, phối hợp giữa **Banana AI** (sinh chất liệu/khái niệm) và **Bộ công cụ mã nguồn mở FOSS / Headless Python** trước khi nạp vào **Cocos Engine 3.8.x** đạt chuẩn 120Hz. --- ## 1. MA TRẬN PHÂN LOẠI & ĐIỀU PHỐI TỰ HÀNH (DISPATCHING MATRIX) Mỗi khi tiếp nhận yêu cầu liên quan đến **Animation** hoặc **VFX**, Agent BẮT BUỘC tra cứu ma trận sau để kích hoạt đúng công cụ, tuyệt đối không suy đoán hay sinh ảnh ngẫu nhiên: | Phân Loại Nghiệp Vụ | Vai Trò Của Banana AI | Công Cụ Xử Lý Tự Hành (Agent FOSS) | Thành Phần Khai Thác Trên Cocos Engine | | :--- | :--- | :--- | :--- | | **Loại 1: Entity Skeletal & Movement**
*(Quái vật, Nhân vật, Boss: Idle, Run, Attack, Hurt, Death)* | Sinh 1 ảnh phối cảnh Isometric chuẩn 8 hướng trên nền tối (`#000000`). | - `rembg` / OpenCV bóc nền mềm.
- Auto-segmentation khớp xương hoặc `Blender Headless` xoay 8 hướng nướng chuỗi sprite. | - `SpriteAtlasRenderer.ts` (Pivot `[0.5, 0.90]`, lưới 8 cột).
- `AnimationFSM.ts` chuyển đổi trạng thái mượt mà. | | **Loại 2: Melee Slash & Trail VFX**
*(Vệt đao, Kiếm khí trăng khuyết, Cào xé, Thân pháp)* | Sinh dải texture năng lượng/máu nguyên bản (Seamless Crimson/Gore Texture). | - `savage_vfx_factory.py`: Quét góc cung elip Bezier Isometric.
- Tính hạt văng tiếp tuyến và tạo Normal Map Sobel. | - `MotionStreak` (vệt đuôi thân pháp lướt né i-frame).
- `Custom Material` (`sprite_pbr.effect` Additive/Blend). | | **Loại 3: Projectile & Trajectory**
*(Cầu lửa, Đạn đạo, Phi tiêu, Chưởng pháp bay)* | Sinh Sprite đạn đạo đầu mũi (Projectile Head) và vệt năng lượng xoắn. | - Python nén Flipbook 4-8 frame xoay góc bay.
- Sinh bounding box hitbox va chạm tự động. | - `RigidBody2D` + `Collider2D` xác định va chạm.
- Node Tween / Action di chuyển mượt 120Hz. | | **Loại 4: AoE, Ground Decals & Shockwaves**
*(Huyết lôi giáng thế, Nứt đất, Đầm lầy độc, Ma trận)* | Sinh hoa văn cổ ngữ man tộc (Rune Circle), vân rạn nứt đất đá (Earth Cracks). | - Python Fractal L-System (sinh sấm sét ziczac tức thì).
- Sinh Decal dẹt góc nghiêng Isometric $30^\circ$. | - Decal Quad trên mặt sàn (Z-Index sàn).
- Camera Shake Component (rung chấn 3-5px). | | **Loại 5: Realtime Particle Bursts**
*(Tia lửa toé, Hạt máu văng, Bụi đất dã ngoại, Tro tàn)* | **KHÔNG DÙNG BANANA** (để tránh phình dung lượng texture). | - Agent cấu hình thông số JSON phát hạt (Velocity, Spread, Life, Color Range). | - `ParticleSystem2D` nguyên bản của Cocos Creator.
- GPU instancing, $0\text{ MB}$ texture tải thêm, $120\text{ FPS}$ tuyệt đối. | --- ## 2. QUY TRÌNH THỰC THI 5 BƯỚC KHÉP KÍN (THE 5-STEP PROTOCOL) ``` [Bước 1: Tiếp nhận & Phân loại] │ Tra cứu Ma trận Điều phối (Loại 1 -> 5) ▼ [Bước 2: Banana Concept / Texture Ingestion] │ Prompt Banana sinh ảnh nền tối, chuẩn phong cách Savage Primal ▼ [Bước 3: Headless FOSS Processing & Synthesizer] │ OpenCV/NumPy tách nền Alpha, sinh chuyển động toán học, nướng Sobel Normal Map ▼ [Bước 4: Power-of-Two Packing & Manifest Generation] │ Đóng gói Texture Atlas (512x512 / 1024x1024) + Xuất JSON clip/frames ▼ [Bước 5: Cocos Engine Binding & 120Hz Verification] │ Gán SpriteAtlasRenderer / sprite_pbr.effect / ParticleSystem2D và chạy test ``` ### Bước 1: Tiếp Nhận & Xác Định Mục Tiêu Agent xác định rõ: - Tên kỹ năng / Entity (ví dụ: `blood_cleave`, `primal_lightning`). - Góc nhìn: Bắt buộc chuẩn Isometric 2.5D ($30^\circ$ mặt phẳng chiếu, 8 hướng di chuyển). - Yêu cầu ánh sáng: Có cần bắt sáng PBR thời gian thực không? (Mặc định: CÓ, cần Normal Map). ### Bước 2: Khai Thác Banana AI Đúng Phương Pháp - **CẤM**: Yêu cầu Banana vẽ chuỗi 16 frame animation (tránh biến dạng hình học và lệch frame). - **ĐÚNG**: Yêu cầu Banana vẽ **Texture nguyên liệu đơn lẻ** hoặc **Sprite nhân vật đơn góc** trên nền đen thuần túy (`#000000`). - **Prompt mẫu chuẩn**: ```text isometric dark fantasy blood slash texture, glowing crimson gore energy, pure solid black background, crisp edges, 2d game asset --no blur, text, watermark ``` ### Bước 3: Xử Lý Headless FOSS (Không Cần Con Người) Agent tự động chạy các script Python đã có sẵn trong dự án: 1. **Khử nền đen mềm**: `clean_black_background()` trong [process_banana_assets_oct2026.py](file:///c:/Projects/FreeExile/tools/asset_pipeline/process_banana_assets_oct2026.py). 2. **Sinh vệt quét hoặc sấm sét**: Sử dụng [savage_vfx_factory.py](file:///c:/Projects/FreeExile/tools/asset_pipeline/savage_vfx_factory.py) để tính toán hình học Bezier Arc và L-System. 3. **Sinh Tangent-Space Normal Map**: Dùng toán tử Sobel qua [m4_normal_utils.py](file:///c:/Projects/FreeExile/tools/asset_pipeline/m4_normal_utils.py) để ánh sáng đuốc/lửa trong Cocos chiếu vào thấy gồ ghề nổi khối. ### Bước 4: Đóng Gói Atlas Chuẩn Power-of-Two (PoT) - Ghép toàn bộ chuỗi frame thành lưới $4\times 4$ hoặc $8\times 8$ kích thước lũy thừa $2$ ($512\times 512$ hoặc $1024\times 1024$). - Sinh file JSON Manifest đồng bộ cấu trúc với [SpriteAtlasRenderer.ts](file:///c:/Projects/FreeExile/client/cocos/assets/scripts/animation/SpriteAtlasRenderer.ts): ```json { "name": "savage_blood_cleave_atlas", "frame_width": 128, "frame_height": 128, "cols": 4, "pivot": [0.5, 0.90], "clips": { "attack": { "frames": ["cleave_0", "cleave_1", "cleave_2", "cleave_3"], "fps": 16 } } } ``` ### Bước 5: Tích Hợp Vào Cocos Engine 3.8.x - Nạp Sprite Sheet vào Sprite Frame Cache của Cocos. - Gán Material sử dụng shader [sprite_pbr.effect](file:///c:/Projects/FreeExile/client/cocos/assets/resources/shaders/sprite_pbr.effect) (truyền `mainTexture` và `normalMap`). - Với các đòn đánh chém: Gắn thêm `ParticleSystem2D` phát sinh $8 - 12$ tia máu bắn toé khi trúng mục tiêu. - Thêm Camera Shake: Rung chấn $3.5\text{px}$ trong $0.1\text{s}$ để tạo uy lực chấn động. --- ## 3. TỐI ƯU HÓA HIỆU NĂNG COCOS ENGINE (PROMOTION 120HZ COMPLIANT) Để đảm bảo game chạy mượt mà trên cả trình duyệt WebGL và thiết bị di động (iPhone ProMotion 120Hz): 1. **Dynamic DrawCall Batching**: Mọi Sprite VFX dùng chung một tấm Atlas sẽ tự động được Cocos gom thành $1$ DrawCall duy nhất. 2. **Particle Pool Reuse**: Không `instantiate` và `destroy` particle emitter liên tục; sử dụng Object Pool để tái sử dụng node hạt đã tắt. 3. **PBR Normal Map Memory Budget**: Texture Normal Map được nén WebP với chất lượng $85\%$, giảm $70\%$ dung lượng RAM so với PNG thuần. --- ## 4. BẢO CHỨNG TỰ ĐỘNG (VERIFICATION CHECKLIST CHO AGENT) Trước khi Agent báo cáo hoàn thành bất kỳ tác vụ Animation hay VFX nào, BẮT BUỘC kiểm tra: - [ ] Ảnh Sprite Sheet tuân thủ kích thước lũy thừa 2 ($256, 512, 1024$). - [ ] Kênh Alpha không bị viền đen xỉn màu (halo artifact). - [ ] File Normal Map có kênh Blue $> 128.0$ (pháp tuyến hướng về phía camera). - [ ] Pivot point đặt đúng gốc chân quái/nhân vật `[0.5, 0.90]` (chống trôi trượt chân). - [ ] Có file manifest JSON tương thích với `SpriteAtlasRenderer.ts`.