# Original User Request ## 2026-10-01T08:26:39Z This is a single self-contained fix; keep it small and focused. Sửa hai nhóm lỗi animation cụ thể trong client WebApp FreeExile: (1) bounding box / atlas frame mapping sai khiến sprite bị lệch hoặc vẽ sai frame, (2) nhân vật bị quán tính thị giác thừa khi nhả điều khiển do turn-inertia lerp không đồng bộ với trạng thái chuyển động thực tế. Working directory: `c:/Projects/FreeExile` Integrity mode: development --- ## Context kỹ thuật (đọc trước khi bắt đầu) ### Các file liên quan | File | Vai trò | |------|---------| | `client/webapp/js/engine/animation_engine.js` | Core animation runtime (309 dòng) | | `client/webapp/js/engine/canvas_renderer.js` | Game render loop + movement + animation dispatch | | `client/webapp/js/engine/entity_renderer.js` | Depth-sort + sprite draw | | `client/webapp/assets/animations/char_*_anim_manifest.json` | Atlas manifest (frame_width=160, frame_height=192, cols=8) | ### Kiến trúc animation atlas - Atlas chia thành grid 8 cột (cols = `Math.min(8, textureWidth / frameWidth)`). - Mỗi clip trong manifest có `frames[]` (string keys) và một số clip có `atlas_clip` (alias trỏ sang clip khác để dùng chung sprite row). - `globalIndex` được tính bằng cách duyệt `allClips`, cộng dồn `frames.length` — **clip có `atlas_clip` bị `continue` skip** nhưng vẫn làm lệch index nếu logic không đồng nhất. - Pivot cố định: `dy = -dh * 0.90` (bottom-center pivot). ### Cơ chế movement - `canvas_renderer.js` renderLoop: lấy `player.dirX/Y` (joystick) + `keyX/Y` (keyboard) → `mx/my` → normalize → apply `player.speed * dt` trực tiếp vào `player.wx/wy`. - **Không có velocity buffer**: movement là digital on/off, không có acceleration/deceleration. - `AnimationEngine.updateAnimation(player.anim, velocity, dt, {x: screenDirX, y: screenDirY})` — `smoothAngle` lerp vẫn tiếp tục chạy ngay cả khi `mag = 0` vì `facingDir` được truyền từ `screenDirX` (giữ nguyên giá trị cuối khi đứng im). --- ## Requirements ### R1. Sửa lỗi bounding box / atlas frame mapping sai Hàm `drawEntityFrame` trong `animation_engine.js` phải vẽ đúng frame từ atlas theo manifest. Hiện tại, khi một clip có `atlas_clip` (alias), vòng lặp tính `globalIndex` có thể bị lệch do thiếu tính nhất quán trong cách đếm frame. Ngoài ra, pivot `dy = -dh * 0.90` phải đọc từ manifest frame's `pivot[1]` nếu có, thay vì hardcode. Sau khi sửa: sprite idle/run/attack/dodge phải render đúng row/column trong atlas; không còn hiện tượng "nhảy frame" sai (ví dụ: attack frame 0 render thành run frame). ### R2. Sửa lỗi quán tính thị giác thừa khi nhả điều khiển Khi `mag = 0` (joystick/keyboard nhả), `AnimationEngine.updateAnimation` không nên tiếp tục lerp `smoothAngle` sang `targetAngle` vì gây nhân vật tiếp tục "xoay" thị giác sau khi đứng im. Cụ thể: chỉ cập nhật `smoothAngle` khi `actualVel > 0.01` (hoặc khi `facingDir` đang thay đổi tích cực). Khi dừng, `smoothAngle` phải giữ nguyên vị trí cuối (snap freeze). Bổ sung: khi transition từ `run → idle`, nếu `player.animState = 'idle'` được set nhưng `anim.smoothAngle` vẫn lerp → thêm guard `if (mag < 0.05) return` trước bước lerp turn inertia trong `updateAnimation`. ### R3. Debug overlay tạm thời (auto-remove sau khi fix xong) Trong quá trình sửa, thêm một debug overlay nhỏ (toggle bằng `Ctrl+Shift+D` hoặc query param `?debug=1`) vẽ: - Bounding box của sprite hiện tại (rectangle tại dx/dy/dw/dh). - Số frame đang render (`clip:frameIndex`) và `smoothAngle` hiện tại. Overlay phải được xóa sạch (hoặc ẩn mặc định `display:none`) trong code cuối cùng — không được commit debug UI trong trạng thái bật. --- ## Acceptance Criteria ### Atlas Frame Mapping - [ ] Tất cả 6 character class (`char_sword_master`, `char_sword_maiden`, `char_feral_berserker`, `char_wild_archer`, `char_glacial_lancer`, `char_shadow_assassin`) render đúng frame ở animation `idle`, `run`, `attack_slash`, `dodge` — kiểm chứng bằng cách so sánh `(sx, sy)` tính toán với tọa độ atlas grid thực tế từ manifest. - [ ] Clip alias `attack_thrust`, `attack_slam`, `attack_bolt` (có `atlas_clip: 'attack_slash'`) không làm lệch `globalIndex` của các clip phía sau. - [ ] Không còn hiện tượng sprite "nhảy" sang row/col sai khi chuyển giữa các animation state. ### Turn Inertia / Movement Feel - [ ] Khi nhả joystick/keyboard (`mag = 0`), `smoothAngle` dừng lerp ngay lập tức trong frame đó — `smoothAngle` không thay đổi trong các frame tiếp theo khi `mag = 0`. - [ ] Transition `run → idle` xảy ra trong vòng `<= 1 frame` kể từ khi `mag < 0.05`. - [ ] Không còn hiện tượng nhân vật tiếp tục "quay đầu" sau khi đứng im. - [ ] Click-to-move vẫn hoạt động đúng (nhân vật quay đúng hướng khi đang di chuyển đến `player.destination`). ### Code Quality - [ ] Không có `console.error` mới trong DevTools khi chạy game bình thường. - [ ] `animation_engine.js` vẫn ≤ 350 dòng (soft cap theo GEMINI.md). - [ ] Debug overlay mặc định ẩn (`display:none` hoặc bị `if (false)` guard) — không visible khi mở game bình thường. --- *Expecting this to run as a small focused team (2 self-contained bug fixes) rather than a full project.* ## 2026-10-01T11:33:27Z Nâng cấp 3 tính năng gameplay cốt lõi cho FreeExile WebApp: (1) Mở rộng diện tích bản đồ wilderness, (2) Thêm vùng bất tử Safe Radius quanh waypoint/checkpoint theo chuẩn PoE2, (3) Implement cơ chế pause game khi nhấn ESC hoặc mở Settings trên cả desktop và mobile. **Working directory:** `c:\Projects\FreeExile` **Integrity mode:** development --- ## Context & Background Codebase FreeExile là WebApp game ARPG 2.5D isometric. Các file liên quan: - **Zone catalog** (server + client data): `server/world/zone_catalog.py` — định nghĩa `bounds_width`, `bounds_height`, `waypoints` cho từng zone - **Zone engine** (server): `server/world/zone_engine.py` — `can_spawn_hostile_monsters()`, `validate_monster_spawn()`, `spawn_player()` - **Monster system** (client): `client/webapp/js/engine/monster_system.js` — `initZoneMonsters()`, `isSafeHavenZone()`, pack quái spawn tại toạ độ cố định gần player - **Game render loop** (client): `client/webapp/js/engine/canvas_renderer.js` — `renderLoop()` không có pause flag, không bắt ESC - **World renderer** (client): `client/webapp/js/engine/world_renderer.js` - **Main HUD HTML**: `client/webapp/index.html` — có `#btn-open-settings` (hotkey O), không có ESC handler, không có pause overlay - **Monster init**: Zone đầu `zone_tang_kiem_nhai` có pack quái spawn tại `wx: 2.2, wy: -0.8` — rất gần điểm spawn player mặc định `(0,0)` → bị vây ngay khi vào game --- ## Requirements ### R1. Mở rộng diện tích bản đồ Tăng `bounds_width` và `bounds_height` của tất cả các zone wilderness (không phải hideout/sanctuary) trong `zone_catalog.py` lên ít nhất **gấp đôi** kích thước hiện tại. Zone đầu tiên `zone_tang_kiem_nhai` (hiện 800×800) phải được nâng lên tối thiểu **1600×1600**. Cập nhật đồng thời mọi hệ thống client-side sử dụng bounds để camera, minimap, và boundary clamp vẫn hoạt động đúng sau khi mở rộng. ### R2. Vùng bất tử Safe Radius quanh Waypoint/Checkpoint (PoE2 Standard) Triển khai cơ chế **Immortal Safe Zone** bán kính `safe_radius` (mặc định **8.0 world units**) quanh mỗi waypoint trong tất cả zone wilderness: - **Server** (`zone_engine.py`): Thêm kiểm tra `validate_monster_spawn()` từ chối spawn quái trong safe radius của bất kỳ waypoint nào của zone. - **Client** (`monster_system.js`): Hàm `initZoneMonsters()` phải đảm bảo mọi quái được spawn ban đầu nằm ngoài safe radius của waypoint. Hàm `isSafeHavenZone()` hoặc hàm mới `isInWaypointSafeRadius(wx, wy)` trả về `true` nếu toạ độ nằm trong vùng bất tử. - **Client** (`monster_system.js`): Trong tick update quái, quái **không được phép aggro hoặc tấn công** player khi player đứng trong safe radius của waypoint. Quái đang chase player phải leash về (stop pursuing) khi player bước vào safe radius. - **Client** (`world_renderer.js`): Vẽ visual indicator nhẹ nhàng (vòng tròn mờ màu vàng/xanh lá hoặc glowing floor rune) cho thấy vùng an toàn xung quanh waypoint — chỉ hiện khi player ở gần, fade out khi ra xa. - **Client** (player mechanics): Trong vùng safe radius waypoint, player nhận **hồi máu tự động** mỗi giây (ví dụ 2% maxHp/giây) — tương tự PoE2 checkpoint healing. - **Server** (`zone_catalog.py`): Mỗi `Waypoint` object bổ sung field `safe_radius: float = 8.0` nếu chưa có. ### R3. Pause Game khi nhấn ESC hoặc mở Settings Implement cơ chế **pause game** hoàn chỉnh: - **Pause trigger**: - Desktop: nhấn phím `Escape` → toggle pause - Mobile/Desktop: nhấn nút `#btn-open-settings` (⚙️) trong HUD → tự động pause khi modal settings mở, tự động unpause khi modal settings đóng - **Pause state**: Tạo biến `window.isGamePaused = false`. Khi `isGamePaused === true`: - Render loop (`renderLoop` trong `canvas_renderer.js`) vẫn chạy để vẽ hình tĩnh (không bị màn đen), nhưng **bỏ qua** tất cả logic cập nhật: movement, monster AI tick, combat, skill cooldowns, timers - Monster AI không tick, combat damage không xảy ra - Player movement không xử lý (joystick/keyboard input bị ignore) - **Pause overlay** (`index.html`): Hiển thị overlay nhẹ (semi-transparent backdrop) với chữ "TẠM DỪNG / PAUSED" ở giữa màn hình khi paused. Overlay tự ẩn khi unpause. Không che HUD settings modal. - **Unpause**: Nhấn ESC lần nữa (nếu không có modal nào đang mở), hoặc đóng modal settings → game tiếp tục. - Logic này phải hoạt động nhất quán trên cả desktop (keyboard ESC) và mobile (tap settings button). --- ## Acceptance Criteria ### Map Size - [ ] `zone_tang_kiem_nhai` có `bounds_width >= 1600` và `bounds_height >= 1600` trong `zone_catalog.py` - [ ] Tất cả zone wilderness khác có `bounds_width` và `bounds_height` tăng ít nhất gấp đôi so với giá trị cũ - [ ] Camera boundary clamp và minimap (nếu có) vẫn hoạt động sau khi tăng bounds ### Safe Zone - [ ] Player spawn tại zone `zone_tang_kiem_nhai` không bị quái tấn công trong vòng 8 giây đầu (vì nằm trong safe radius của waypoint) - [ ] `isInWaypointSafeRadius(0, 0)` (hoặc hàm tương đương) trả về `true` cho spawn point mặc định của `zone_tang_kiem_nhai` - [ ] Quái đang chase player phải dừng và leash khi player bước vào safe radius — không thể tấn công - [ ] Visual safe zone indicator hiển thị xung quanh waypoint (vòng tròn mờ hoặc rune glowing) - [ ] Player nhận hồi máu khi đứng trong safe radius (có thể verify qua console log hoặc HP bar tăng) - [ ] `validate_monster_spawn` server-side từ chối spawn quái trong safe radius của waypoint ### Pause Game - [ ] Nhấn `Escape` trên desktop → game dừng (monster AI không cập nhật, player không di chuyển) - [ ] Nhấn `#btn-open-settings` → game tự động dừng khi settings modal mở - [ ] Đóng settings modal → game tự động tiếp tục - [ ] Pause overlay hiển thị khi paused, ẩn khi unpaused - [ ] Nhấn `Escape` lần nữa (khi không có modal nào mở) → game tiếp tục - [ ] Không có combat damage hoặc monster movement xảy ra trong khi paused ## 2026-10-01T19:19:13Z Thiết kế lại toàn bộ hệ thống map của FreeExile theo tư tưởng PoE2: bản đồ rộng lớn dạng tile-based procedural (sinh tự động từ seed + biome config), địa hình thực sự với đường đi, vật cản, vùng quái dày/thưa, boss gate, POI nhiệm vụ, Fog of War, minimap HUD, và rendering tối ưu cho mobile không tốn RAM. Mỗi lần vào zone là một layout khác nhau — trải nghiệm khám phá thực sự thay vì bãi chiến đấu phẳng. **Working directory:** `c:\Projects\FreeExile` **Integrity mode:** development --- ## Context & Kiến Trúc Hiện Tại (Đọc Kỹ Trước Khi Thay Đổi) Hệ thống map hiện tại **chưa có tile map thực sự**: - **`client/webapp/js/engine/world_renderer.js`** (461 lines) — Render tile theo công thức toán học hardcode (`Math.abs(x-y) <= 1` → stone, `Math.hypot(x-5, y-(-3)) < 3.2` → water). Không có tile map data. Kích thước tile: `TILE_W=64, TILE_H=32` (isometric 2:1). - **`client/webapp/js/engine/collision_engine.js`** (218 lines) — Chỉ có boundary clamp cho 10 zones trong `ZONE_BOUNDS`. Không có tile-level collision. - **`client/webapp/js/engine/iso_math.js`** — `worldToIso(wx, wy)` → `{x, y}` screen coords; `isoToWorld(sx, sy)` → `{wx, wy}`. Camera exponential lerp. 1 world unit = 1 tile isometric. - **`server/world/procedural_map_engine.py`** (18KB) — Server-side procedural dungeon generator (BSP rooms, corridors, boss room, A* pathfinding, anti-bot obstacles) **đã có** nhưng client chưa nhận/render tile grid từ server. Đây là nền tảng cần tận dụng. - **`server/world/map_data_types.py`** — Đã có: `TileType` (VOID/FLOOR/WALL/BOSS_GATE/BOSS_ALTAR/...), `TileCell`, `MapRoom`, `ObstacleInstance`, `FogState` (UNEXPLORED/EXPLORED_FOGGED/VISIBLE). - **`server/world/map_biome_catalog.py`** — Đã có biome definitions. - **`client/webapp/js/data/wilderness_zone_packs.js`** (254 lines) — Pack quái tọa độ float `(wx, wy)`. Cần refactor để gắn với encounter zones. - **`mapProps`** — Array prop tĩnh với footprint collision — cơ chế đã hoạt động, giữ nguyên. - **10 canonical zones**: `zone_tang_kiem_nhai` (Lv1-10) → `zone_boundless_celestial_palace` (Lv85-100). Mỗi zone có biome khác nhau. - **Tile coordinates vs World coordinates**: 1 world unit = 1 tile. `worldToIso(tx, ty)` dùng được trực tiếp cho tile rendering. **Yêu cầu kiến trúc (Architecture Decision — User Approved):** Procedural tile map — Server sinh tile map từ `(zone_id, seed, biome_config)`, gửi xuống client khi player enter zone. Mỗi lần vào zone có thể có layout mới (replayability). Server-side engine `ProceduralMapEngine` đã có sẵn cần được mở rộng và wire vào pipeline. --- ## Requirements ### R1. Procedural Tile Map Pipeline — Server to Client Server-side `ProceduralMapEngine` phải được mở rộng để sinh tile map đủ phong phú cho open-world wilderness (không chỉ dungeon), và client phải nhận + lưu tile grid để render: - **Server (`server/world/procedural_map_engine.py` + zone_engine)**: Khi player enter zone, server sinh tile map từ `(zone_id, seed=session_seed, biome_id)` và gửi compact representation xuống client qua WebSocket. Tile map mỗi zone wilderness có kích thước tối thiểu `60×45` tiles (zone đầu) đến `120×90` tiles (zone cuối). Format gửi: compact `Uint8Array` (1 byte/tile) thay vì JSON object array để tiết kiệm bandwidth. - **Tile layout requirements** mỗi zone: - Ít nhất **1 main path** rõ ràng từ spawn point đến boss gate — không phải đường thẳng (có khúc cua, ngã ba lựa chọn) - Ít nhất **2-3 encounter zones** (vùng quái dày đặc) nằm dọc hoặc nhánh của main path - Ít nhất **1-2 dead ends** có phần thưởng (loot cache / mini event) - **1 boss gate tile** cuối map (phải đi qua một số encounter zones mới đến được) - **1-3 POI tiles** (checkpoint, NPC merchant, quest giver) - Vùng quanh spawn point (8 tiles radius) phải là FLOOR — không có WALL chắn thoát - **Tile types** cần được sinh: `FLOOR`, `WALL` (impassable terrain), `PATH` (tốc độ +20%), `DENSE_TERRAIN` (tốc độ -30%), `WATER/CHASM` (impassable), `BOSS_GATE` (locked until condition met), `POI`, `ENCOUNTER_HIGH`, `ENCOUNTER_MEDIUM`, `ENCOUNTER_LOW` - **Client (`client/webapp/js/engine/`)**: Nhận tile grid, lưu vào `window.currentMapGrid` (`Uint8Array`, row-major), expose `getTileAt(tx, ty)` → `TileType`. ### R2. Tile-Based Rendering Tối Ưu Mobile (Viewport Culling + Chunk Caching) Client rendering phải được viết lại để xử lý tile map lớn không làm chậm mobile: - **Viewport Culling**: Tính `tileMinX, tileMaxX, tileMinY, tileMaxY` từ camera position và viewport size. Chỉ loop và `drawImage` các tile nằm trong viewport + 2 tile padding. Số draw calls mỗi frame ≤ `(viewport_width/TILE_W + 5) × (viewport_height/TILE_H + 5)`. - **Chunk Pre-rendering**: Chia tile map thành chunks `16×16` tiles. Mỗi chunk được render vào một `OffscreenCanvas` (hoặc `ImageBitmap`) một lần khi load. Khi render frame, chỉ `drawImage` các chunk bitmap đang trong viewport — không vẽ lại từng tile. - **Dirty flag**: Chunk chỉ được re-render vào OffscreenCanvas khi có tile nào trong chunk thay đổi state (ví dụ boss gate mở, obstacle bị phá). Không re-render chunk sạch mỗi frame. - **Tile Sprite Sheet**: Tất cả tile types dùng chung 1 sprite sheet atlas (hoặc solid color fallback nếu chưa có asset), không load image riêng lẻ mỗi tile type. - **RAM Budget**: `Uint8Array` tile data + OffscreenCanvas chunk cache tổng cộng ≤ 8 MB cho zone lớn nhất (`120×90`). - **Thay thế** đoạn code hardcode công thức toán trong `world_renderer.js` bằng hệ thống tile-based mới. ### R3. Tile-Level Collision & Boss Gate Logic Nâng cấp hệ thống collision từ boundary-only sang tile lookup: - **`isPositionBlocked(wx, wy, radius)`**: Tính tile coordinates `(tx, ty) = (floor(wx), floor(wy))`, tra cứu `getTileAt(tx, ty)`. Trả về `true` nếu tile là `WALL`, `WATER`, `CHASM`, hoặc `BOSS_GATE` chưa mở. Giữ nguyên boundary clamp. - **Smooth wall-sliding**: Giữ nguyên cơ chế wall-sliding hiện có trong `collision_engine.js`, chỉ cập nhật `isPositionBlocked`. - **Monster AI pathfinding**: `monster_system.js` khi quái chase player phải tôn trọng tile collision — không đi xuyên WALL. Dùng simple grid pathfinding (BFS hoặc A*) trong encounter zone bounds. - **Boss Gate**: Tile `BOSS_GATE` → `isPositionBlocked = true` cho đến khi điều kiện mở cửa được thỏa mãn (player đã kill đủ số pack quái quy định trong zone). Khi điều kiện thỏa → `BOSS_GATE` chuyển thành `FLOOR`, chunk dirty-flagged → re-render. Visual indicator: glowing seal rune xoay quanh boss gate tile. - **Server-side validate**: `zone_engine.py` `validate_monster_spawn` cũng phải kiểm tra tile tại vị trí spawn. ### R4. Fog of War (Client-Side) & Minimap HUD - **Fog of War array**: `window.fogGrid` là `Uint8Array` cùng kích thước tile map, giá trị `0=UNEXPLORED, 1=EXPLORED_FOGGED, 2=VISIBLE`. Persist trong `localStorage` theo `zone_id+seed` để fog không reset mỗi lần teleport về zone. - **Fog reveal**: Mỗi frame, tất cả tiles trong radius **8 tiles** quanh player chuyển sang `VISIBLE`. Tiles từng thấy (trước đó `VISIBLE`) khi player đi xa chuyển sang `EXPLORED_FOGGED`. - **Fog rendering**: Tile `UNEXPLORED` → phủ solid black rectangle. Tile `EXPLORED_FOGGED` → phủ `rgba(0,0,0,0.55)` overlay. Tile `VISIBLE` → không phủ gì. - **Fog dirty flag**: Fog overlay chỉ re-render vào OffscreenCanvas khi fog state thay đổi, không vẽ lại mỗi frame. - **Minimap** (`index.html` + JS): Thêm minimap element trong HUD góc trên phải, kích thước `120×80px`, canvas 2D riêng. Minimap hiển thị: - Tile đã explore: màu biome (ví dụ stone gray / sand yellow) - Tile chưa explore: đen - Player: chấm trắng - Waypoints đã active: chấm xanh lá - Boss gate: chấm đỏ - POI: chấm vàng - Minimap chỉ re-render khi fog state thay đổi hoặc player di chuyển qua tile mới. ### R5. Encounter Zone Architecture — Monster Spawn Gắn Địa Hình Refactor monster spawn để gắn với tile map encounter zones: - **Encounter Zones** được định nghĩa trong tile map (region của các tile `ENCOUNTER_HIGH/MEDIUM/LOW`). Pack quái chỉ spawn trong các tiles thuộc encounter zones tương ứng. - **Spawn position**: Thay vì `wx, wy` cứng trong `wilderness_zone_packs.js`, pack quái được spawn tại random tiles trong encounter zone bounds tương ứng của pack đó. - **POI scripted encounter**: Khi player bước vào tile `POI`, trigger scripted encounter (wave spawn) nếu POI chưa được clear. Sau khi clear, POI tile visual thay đổi (glow tắt) và có thể xuất hiện loot cache hoặc NPC. - **Boss Gate encounter popup**: Khi player đến trong 3 tiles của `BOSS_GATE` tile, hiển thị popup lore ngắn + điều kiện mở cửa còn lại (ví dụ "Còn 2 pack chưa bị diệt"). Popup dùng modal hoặc floating HUD element. - **Encounter progress tracker**: `window.zoneEncounterProgress[zone_id]` lưu số pack đã kill, cập nhật sau mỗi kill. Khi đạt threshold → auto-unlock boss gate. --- ## Acceptance Criteria ### R1 — Tile Map Pipeline - [ ] Server sinh tile map cho `zone_tang_kiem_nhai` với grid `>= 60×45`, có main path, boss gate, POI, encounter zones - [ ] Client nhận tile grid và lưu vào `window.currentMapGrid` (`Uint8Array`) - [ ] `getTileAt(tx, ty)` hoạt động đúng — trả về tile type tại tọa độ tile - [ ] Tile map thay đổi giữa các lần enter zone khác seed (procedural verified) ### R2 — Rendering Performance - [ ] Số lần `drawImage` mỗi frame ≤ `(viewport_W / TILE_W + 5) × (viewport_H / TILE_H + 5)` (đo bằng counter) - [ ] Chunk OffscreenCanvas không bị re-render mỗi frame (chỉ re-render khi dirty) - [ ] RAM usage tile data + chunk cache ≤ 8 MB cho zone `120×90` (kiểm tra `performance.memory`) - [ ] Script benchmark `tools/perf/map_render_benchmark.js` chạy được, output avg FPS >= 30 ### R3 — Tile Collision - [ ] `isPositionBlocked(wx, wy)` tại WALL tile → `true`; tại FLOOR tile → `false` - [ ] Player không đi xuyên WALL tile - [ ] Boss gate tile: blocked khi chưa đủ kills, walkable sau khi đủ kills - [ ] Unit test `tests/unit/test_tile_collision.py` — ít nhất 10 test cases, tất cả pass ### R4 — Fog of War & Minimap - [ ] Tiles chưa đến hiển thị solid black - [ ] Sau khi player đi qua, tiles chuyển `EXPLORED_FOGGED` (overlay mờ, không có quái) - [ ] Minimap hiển thị trong HUD với player dot, waypoint dots, boss gate dot - [ ] Fog state persist sau khi player teleport về và quay lại zone ### R5 — Encounter Architecture - [ ] Pack quái không spawn tại tọa độ cứng mà spawn trong encounter zone bounds tương ứng - [ ] POI scripted encounter trigger khi player đến tile POI - [ ] Boss gate popup lore hiển thị khi player trong 3 tiles của boss gate - [ ] `zoneEncounterProgress` tracking hoạt động — boss gate mở khi đủ kills ### Regression - [ ] Toàn bộ test suite >= 894 unit tests vẫn pass sau mọi thay đổi - [ ] Safe zone waypoint radius (từ feature trước) vẫn hoạt động đúng - [ ] Pause game ESC/Settings vẫn hoạt động đúng --- ## Verification Resources - Server engine tham khảo: `server/world/procedural_map_engine.py` - Map data types: `server/world/map_data_types.py` - Tile math: `TILE_W=64, TILE_H=32`, `worldToIso(wx,wy)` trong `iso_math.js` - Existing tests: `tests/unit/` — toàn bộ phải tiếp tục pass --- *Expecting this to run as a full team project — major multi-module overhaul spanning server pipeline, client tile rendering, collision, fog-of-war, minimap, and encounter architecture.* ## 2026-10-01T22:03:34Z FreeExile — Chiến Dịch Bổ Sung Kho Asset Toàn Diện & Nghiên Cứu Pipeline Tối Ưu Hóa Đồ Họa 2026 Dự án ARPG 2.5D FreeExile (Cổ Võ Hoang Dã, PoE2 spirit, iOS 120Hz ProMotion target) đang thiếu hụt nghiêm trọng asset và animation cho nhiều hệ thống gameplay cốt lõi. Nhiệm vụ này huy động toàn bộ phòng ban — Thiết kế Hệ thống, Kịch bản, Kinh tế, Bảo mật, Client, Server — gửi yêu cầu thiết kế (DRQ) còn tồn đọng vào inbox, đồng thời R&D nghiên cứu và triển khai các kỹ thuật rendering tiết kiệm phần cứng cho cả client lẫn server, và Phòng Thiết Kế thực thi sản xuất toàn bộ asset/animation đến khi đạt nghiệm thu 2 cấp (QA kỹ thuật + CEO thẩm mỹ). Working directory: c:/Projects/FreeExile Integrity mode: development --- ## Asset Gap Analysis (Kiểm kê thiếu hụt hiện tại) Kho asset hiện có (`client/webapp/assets/`) bao gồm: - **animations/**: 7 nhân vật hero + 2 monster (Hellhound, Skeleton Warrior) — thiếu 10+ monster, boss, NPC - **monsters/**: 12 mob + 2 boss sprite tĩnh — không có animation atlas cho hầu hết monster - **characters/**: 6 class + 5 NPC — thiếu paperdoll Skeletal, biến thể trang phục, paperdoll vũ khí equip - **skills/**: 1 atlas duy nhất — thiếu hoàn toàn animation chiêu thức riêng biệt theo class và Ngũ Hành - **map/**: 8 tile + 3 prop + portal — thiếu dungeon tiles, safe haven assets, boss arena, loot particle - **ui/**: combat HUD, guild stash, quest scroll — thiếu: Hideout UI, Meridian/Passive Tree interactive, trade/bazaar UI, inventory equip slots - **savage_vfx/**: particle VFX — thiếu hit impact VFX, death VFX, status effect icons animated - **currencies/**, **shop/**, **portraits/** — cần mở rộng đáng kể --- ## Requirements ### R1. Kiểm Kê & Tạo Design Request (DRQ) Từ Các Phòng Ban Tất cả các phòng ban sau phải thực hiện Post-Documentation Visual Audit và tạo file DRQ chuẩn theo template `docs/design_requests/templates/DESIGN_REQUEST_TEMPLATE.md` vào thư mục `docs/design_requests/inbox/`: - **Phòng Thiết kế Hệ thống** (`lead_systems_designer`): DRQ cho mọi hệ thống gameplay còn thiếu asset (Passive Tree/Meridian interactive nodes, Crafting Station UI, Map Device, Boss Arena, Hideout props, Safe Haven props) - **Phòng Kịch bản & NPC** (`quest_narrative_designer`): DRQ cho NPC còn thiếu avatar/standee/dialogue portrait, Quest scroll variants, Cutscene assets - **Phòng Kinh tế** (`poe2_game_designer` / `economy`): DRQ cho currency icons (Bloodstones, Bone Relics, Dust, crafting orbs), Trade/Bazaar UI panels, Loot drop particles - **Phòng Bảo mật** (`ciso_agent`): DRQ cho Security shield animation, alert badges, UI forensic elements - **Phòng Client** (`web_client_engineer` / `ios_client_engineer`): DRQ cho loading screen assets, login screen visual, game world background layers, parallax elements - **Phòng Server/Agent** (`server_engineer`): DRQ cho Agent Orb activation VFX, harvest report UI overlays Mỗi DRQ phải bao gồm: mã định danh `DRQ-YYYYMMDD-[FEATURE]`, mô tả nghiệp vụ chi tiết, kích thước yêu cầu, loại asset (sprite/atlas/UI/VFX/shader), mức ưu tiên (CRITICAL/HIGH/MEDIUM/LOW), và animation states cần thiết. Mỗi DRQ là một file .md riêng biệt trong `docs/design_requests/inbox/`. ### R2. Nghiên Cứu & Triển Khai Kỹ Thuật Rendering Tiết Kiệm Chi Phí (R&D) Phòng R&D phải nghiên cứu và triển khai (code + tài liệu) tối thiểu các kỹ thuật sau vào pipeline FreeExile: **Phía Client (iOS/WebApp)**: - **LOD (Level of Detail) for Sprites**: Script Python tạo 3 mức LOD (100%, 50%, 25%) cho mỗi character spritesheet bằng Pillow/Lanczos — lưu tại `tools/asset_pipeline/lod_generator.py` - **ASTC/WebP Batch Texture Compression**: Script Python nén tất cả PNG sang WebP (web) — target giảm ≥ 50% VRAM footprint — lưu tại `tools/asset_pipeline/texture_compressor.py` - **Viewport Culling Utility**: Module Python tính toán frustum AABB intersection để xác định entity nào cần draw — lưu tại `tools/asset_pipeline/viewport_culling_utils.py` - **Sprite Mipmap Generation**: Tự động tạo mipmap chain chuẩn 2^n bằng Pillow trong pipeline Python, tích hợp vào `tools/asset_pipeline/animation_pipeline.py` - **GPU Instancing guidance**: Tài liệu kỹ thuật mở rộng `monster_palette_instancing.metal` để render 200+ monster instances cùng 1 draw call **Phía Server**: - **AoI Animation State Filtering**: Tài liệu và pseudocode/implementation cho server chỉ broadcast animation state update cho các client có entity trong vùng AoI - **Delta Compression for Animation State**: Tài liệu kỹ thuật chỉ gửi delta (changed fields) giữa 2 tick thay vì full state - **Asset Manifest ETag Caching**: Tài liệu thiết kế HTTP caching layer cho asset manifests (JSON) với ETag/304 Tất cả kỹ thuật phải được tổng hợp thành báo cáo kỹ thuật tại `docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md` với benchmark số liệu thực tế đo được. ### R3. Sản Xuất Asset & Animation Theo DRQ (Phòng Thiết Kế Thực Thi) Sau khi nhận DRQ từ các phòng ban (R1) và kỹ thuật tối ưu từ R&D (R2), Phòng Thiết Kế thực hiện sản xuất theo ưu tiên: **CRITICAL Priority (Blocking core gameplay)**: - Animation atlases (idle, walk, attack, cast, stun, die — 8 hướng) cho tất cả 12 mob + 2 boss hiện có trong `assets/monsters/` — mỗi package gồm: `[name]_anim_atlas.png` + `[name]_anim_atlas_normal.png` + `[name]_anim_manifest.json` - Skill animation atlases riêng biệt: 5 class × 3 skills = 15 atlases, màu sắc theo 5 hành Ngũ Hành (Kim=Bạc, Mộc=Xanh lục, Thủy=Lam/Hắc, Hỏa=Đỏ cam, Thổ=Hoàng thổ) - Combat VFX: hit impact particle, death dissolve VFX, damage number particle **HIGH Priority (Core systems)**: - Passive Tree/Meridian (Huyết Cốt Ma Đồ): 5 loại node sprites (Passive small, Notable medium, Keystone large, Socket gem, Connector line), background constellation texture - Map tile bổ sung: dungeon stone wall (4 variants), dungeon floor (4 variants), Boss Arena floor (lava theme + bone theme) - NPC mới: ≥ 5 NPC với avatar + standee + portrait mỗi NPC, phong cách Cổ Võ Hoang Dã **MEDIUM Priority**: - Currency icons: Primal Bloodstones (5 tiers), Bone Relics, Salvage Dust, 6 crafting orb types - Trade/Bazaar UI panels, Item tooltip frame, inventory equip slot UI - Status effect icons (animated PNG frames): Burn, Freeze, Stun, Poison, Bleed, Shock (≥ 6) **LOW Priority**: - Loading screen art (isometric Cổ Võ scene, full-bleed 1024×1024) - Login screen background parallax layers (3 layers) - Agent Orb activation VFX (3 tiers: Sơ Cấp/Trung Cấp/Vô Song) Tất cả asset phải sử dụng `tools/asset_pipeline/animation_pipeline.py` và xuất bộ 3: albedo + normal + manifest. Kích thước lũy thừa 2^n bắt buộc. Lưu vào đúng thư mục category trong `client/webapp/assets/`. ### R4. Nghiệm Thu Kỹ Thuật Tự Động (QA Gate) Sau khi sản xuất, chạy nghiệm thu kỹ thuật: - `python tools/asset_pipeline/design_pipeline_manager.py report` — xác nhận DRQ status - Kiểm tra 2^n: tất cả texture width/height phải là lũy thừa 2 - Kiểm tra dung lượng ngân sách: character spritesheet ≤ 2 MB, UI icon ≤ 150 KB, map tile ≤ 50 KB - Normal map tangent-space: kênh B mean > 128 trên tất cả `*_normal.png` - Chạy LOD generator và texture compressor trên tập mẫu, đo kết quả giảm kích thước thực tế --- ## Acceptance Criteria ### AC1 — DRQ Coverage - [ ] Mỗi phòng ban được liệt kê trong R1 đã tạo ít nhất 3 DRQ vào `docs/design_requests/inbox/` - [ ] Tổng số DRQ mới ≥ 20, mỗi file là một DRQ riêng biệt theo định dạng `DRQ-YYYYMMDD-[FEATURE].md` - [ ] Mỗi DRQ có đầy đủ: mã định danh, mô tả nghiệp vụ, kích thước, loại asset, mức ưu tiên, animation states cần thiết ### AC2 — R&D Technical Deliverables - [ ] `tools/asset_pipeline/lod_generator.py` hoạt động: nhận input PNG, xuất 3 mức LOD, LOD-2 ≤ 40% kích thước gốc - [ ] `tools/asset_pipeline/texture_compressor.py` hoạt động: batch convert PNG→WebP, output ≤ 50% kích thước PNG gốc - [ ] `tools/asset_pipeline/viewport_culling_utils.py` có unit test pass (pytest) - [ ] `docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md` tồn tại, ≥ 300 dòng, có benchmark số liệu thực đo - [ ] Tài liệu AoI animation delta compression trong `docs/research/` ### AC3 — Asset Production CRITICAL & HIGH - [ ] Animation atlases (6 states × 8 hướng) cho tất cả 12 mob + 2 boss — mỗi package có đủ albedo + normal + manifest - [ ] 15 skill animation atlases (5 class × 3 skills) với Ngũ Hành color palette đúng hành - [ ] Passive Tree node sprites: 5 loại node + background constellation - [ ] Dungeon tile set ≥ 8 variants + Boss Arena floor ≥ 2 themes - [ ] ≥ 5 NPC mới mỗi NPC có avatar + standee + portrait ### AC4 — Asset Production MEDIUM & LOW - [ ] ≥ 12 currency type icons trong `client/webapp/assets/currencies/` - [ ] ≥ 6 animated status effect icons trong `client/webapp/assets/ui/status_effects/` - [ ] Trade/Bazaar UI panels + item tooltip frame hoàn thành - [ ] Loading screen art + login background parallax layers hoàn thành ### AC5 — Technical Quality - [ ] 100% asset mới có kích thước width/height lũy thừa 2^n - [ ] 0 asset vượt ngân sách dung lượng tiêu chuẩn - [ ] 100% file `*_normal.png` có kênh B mean > 128 (kiểm tra bằng Pillow) - [ ] Draw call budget: với 50 entity on-screen, số draw calls < 30 (theo tài liệu kỹ thuật batching) ### AC6 — Pipeline & Documentation - [ ] `python tools/asset_pipeline/design_pipeline_manager.py report` hiển thị ≥ 20 DRQ status - [ ] Tất cả asset mới được lưu vào đúng thư mục category trong `client/webapp/assets/` - [ ] `docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md` và tài liệu kỹ thuật liên quan cập nhật đầy đủ - [ ] GEMINI.md và AGENTS.md được cập nhật với các kỹ thuật rendering mới nếu có thay đổi chuẩn mực ## 2026-10-02T01:42:06Z Rà soát toàn diện và khắc phục dứt điểm lỗi không nhận diện cài đặt ngôn ngữ hệ thống trên giao diện (đặc biệt ở tính năng Chat và các module phát triển sau), đồng thời thiết lập tiêu chuẩn kiến trúc bắt buộc để toàn bộ tính năng cũ và mới tương thích 100% đa ngôn ngữ (i18n) và đa nền tảng (Web PWA, Mobile, Desktop). Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Rà soát & Khắc phục triệt để lỗi ngôn ngữ Chat và các module mở rộng Toàn bộ giao diện Chat (tabs kênh, placeholder, thông báo hệ thống, cooldown, item link tooltip, thông báo quyền hạn) và các thành phần UI liên quan phải nhận diện và phản hồi tức thời (reactive) khi người dùng thay đổi ngôn ngữ trong cài đặt mà không cần tải lại trang. ### R2. Chuẩn hóa kiến trúc Đa ngôn ngữ (i18n) & Đa nền tảng toàn diện Thiết lập cơ chế phân phối sự kiện thay đổi ngôn ngữ (language change event bus / observer) thống nhất cho toàn bộ client. Loại bỏ triệt để mọi chuỗi văn bản hardcoded trong mã nguồn giao diện, bảo đảm mọi tính năng (cũ và mới) tuân thủ 100% quy chuẩn i18n, tương thích liền mạch trên cả Web PWA, iOS Metal / Mobile và Desktop. ### R3. Hệ thống Kiểm thử Tự động & Phòng chống Hồi quy (Multi-Tiered Anti-Regression) Xây dựng bộ kiểm thử và kiểm toán tự động độc lập gồm: công cụ linter quét phát hiện chuỗi hardcoded tiếng Việt trong mã UI, bộ unit test kiểm tra tính toàn vẹn của sự kiện đổi ngôn ngữ, và kịch bản E2E kiểm chứng trực tiếp sự thay đổi hiển thị của giao diện khi chuyển đổi ngôn ngữ. ### R4. Văn bản hóa Quy chuẩn Kỹ thuật Toàn dự án Cập nhật đầy đủ bài học kinh nghiệm, quy định bắt buộc và checklist phát triển tính năng mới vào các tài liệu chỉ thị cốt lõi của dự án (AGENTS.md, GEMINI.md, ENGINEERING_STANDARDS_2026.md) để ngăn ngừa tái diễn lỗi trên tất cả các tác vụ phát triển trong tương lai. ## Acceptance Criteria ### Chat & Dynamic UI Localization - [ ] Khi chuyển đổi cài đặt ngôn ngữ (Việt, Anh, v.v.), giao diện Chat (kênh chat, placeholder, nút bấm, nhãn trạng thái, thông báo) và các modal tự động chuyển đổi ngôn ngữ ngay lập tức mà không cần F5/reload trang. - [ ] Không còn bất kỳ chuỗi tiếng Việt hardcoded nào trong client/webapp/js/ui/chat_ui.js và các thành phần UI liên quan. ### Cross-Platform Architecture & Event Propagation - [ ] Hệ thống sở hữu cơ chế lắng nghe/phát sự kiện ngôn ngữ tập trung, mọi module UI đăng ký nhận sự kiện đều cập nhật lại nội dung đồng bộ. - [ ] Kiến trúc đảm bảo tính tương thích đa nền tảng, không phụ thuộc vào các API đặc thù của riêng một trình duyệt hay thiết bị. ### Automated Verification & Anti-Regression Gate - [ ] Công cụ kiểm tra tĩnh (linter / hygiene checker) phát hiện và chặn đứng mã nguồn mới đưa thêm chuỗi hardcoded ngôn ngữ. - [ ] Bộ test tự động (unit tests và/hoặc E2E) chạy thành công và xác nhận tính năng đổi ngôn ngữ hoạt động chính xác 100%. ### Documentation & Standards Compliance - [ ] Toàn bộ quy chuẩn phát triển i18n và đa nền tảng được ghi nhận vào AGENTS.md, GEMINI.md và docs/standards/. ## 2026-10-02T02:00:04Z Hệ thống hóa toàn diện đồ họa bản đồ FreeExile: Xóa bỏ triệt để giao diện lưới tile hình khối phẳng vô hồn; R&D nghiên cứu và đặc tả 30 phong cách map (biomes/themes) đậm chất Cổ Võ Hoang Vực PoE2; Phòng Thiết kế sản xuất bộ asset đồ họa textures/spritesheets và xây dựng Database Phong Cách Map; Phòng Kỹ thuật nâng cấp TileMapRenderer render hình ảnh chân thực với chunk caching 60-120 FPS; Phòng QA kiểm chứng hiển thị 30 map trên trình duyệt thực và tự động hóa test suite. **Working directory:** `c:\Projects\FreeExile` **Integrity mode:** `development` --- ## 1. Phân Tích & Phối Hợp Liên Phòng Ban (Cross-Department Mission) ### 1.1. Phòng Kỹ Thuật (Engine & Client Pipeline) - **Chẩn đoán nguyên nhân gốc rễ**: - Trong `client/webapp/js/engine/tile_map_renderer.js`, hàm `_drawTile()` hiện tại chỉ tô màu hình học đa giác phẳng (`ctx.fillStyle = baseCol`, `ctx.beginPath()`, `ctx.moveTo()`, `ctx.lineTo()`) bằng mã màu HEX thay vì vẽ hình ảnh / texture sprite thật (`ctx.drawImage` hoặc `CanvasPattern`). - Thiếu hệ thống quản lý và liên kết sprite atlas / pattern texture giữa mã ô (TileType), mã phong cách bản đồ (BiomeCode) và tệp ảnh tài nguyên. - **Nhiệm vụ kỹ thuật**: - Tái cấu trúc `TileMapRenderer`: Tích hợp bộ nạp và quản lý texture/pattern theo Biome (`BiomeTextureManager`). - Khi nướng (bake) chunk `16x16` vào `OffscreenCanvas`, sử dụng texture ảnh thực tế (đất nứt, đá sỏi, rêu mục, xương khô, đầm lầy, nham thạch, phế tích ma thần, rễ cây đước,...) kèm lớp bóng đổ (isometric depth/elevation extrusion) và decal ngẫu nhiên. - Đảm bảo cơ chế fallback an toàn: Nếu ảnh chưa tải xong hoặc mạng chậm, tự động render màu bóng đổ procedural tương ứng của biome mà không vỡ hình hay trắng màn hình. - Tối ưu hóa bộ nhớ: Giữ nguyên ngân sách RAM <= 16.5 MB cho chunk cache và duy trì 60-120 FPS trên mobile. ### 1.2. Phòng R&D (Nghiên Cứu Phong Cách & Lore Bản Đồ) - Nghiên cứu và xây dựng danh mục tối thiểu **30 phong cách map (Biomes / Map Styles)** độc đáo, chuẩn tinh thần Dark Fantasy / Cổ Võ Hoang Dã (PoE2 Exile Spirit), không lai căng tiên hiệp màu mè. - Mỗi phong cách bản đồ có đầy đủ: - `style_id` & `name`: Tên tiếng Việt và định danh chuẩn (ví dụ: `STY_01_HOANG_MANG_CO_LO`, `STY_02_HUYET_SAT_LAM`, `STY_03_VAN_KIEP_MIEU_DIA`,...). - `theme_category`: Phân nhóm (Hoang Dã Dã Ngoại, Đầm Lầy Độc Chướng, Hẻm Núi Cốt Mạc, Hầm Mỏ Tà Quái, Thần Điện Phế Tích, Hư Không Dị Biến,...). - `palette`: Bảng mã màu chủ đạo (nền đất, vách đá, đường mòn, chất lỏng, ánh sáng môi trường). - `terrain_types`: Đất chính (Primary floor), vách đá (Wall), đường mòn (Path), hiểm địa (Hazard/Liquid). - `prop_decorations`: Danh sách vật thể trang trí (xương thú cổ, bia mộ rỉ sét, rễ gai hút máu, vò rượu vỡ, cọc gỗ cắm cờ rách,...). - `ambient_lighting`: Màu sắc ánh sáng và sương mù khí quyển. - Chuyển giao toàn bộ bản đặc tả chi tiết sang Phòng Thiết Kế và Trưởng Phòng Tổng Hợp. ### 1.3. Phòng Thiết Kế (Art Direction, Asset Pipeline & Database) - **Kiểm tra & Rà soát Asset**: Đánh giá toàn bộ tài nguyên trong `client/webapp/assets/map/` và các thư mục asset liên quan. - **Sản xuất & Bổ sung Asset**: - Tạo lập và đóng gói bộ hình ảnh textures/sprites đầy đủ cho tối thiểu **30 phong cách map**. - Định dạng chuẩn Isometric (64x32 px cơ sở, tile texture seamless hoặc sprite tileset 128x64 px và decal props). - Tích hợp asset test và asset chính thức đầy đủ, đồng bộ vào `client/webapp/assets/map/styles/` hoặc sprite atlas tương ứng. - **Xây dựng Database Phong Cách Map (`MapStylesDatabase`)**: - Trưởng phòng thiết kế tổng hợp và kiến trúc cơ sở dữ liệu `data/map_styles.db` (SQLite) kết hợp danh mục chuẩn mã nguồn `server/world/map_style_catalog.py` và `client/webapp/js/data/map_style_catalog.js`. - Schema CSDL: `map_styles` (30 records), `map_style_tiles` (texture mappings cho từng TileType), `map_style_props` (props trang trí ngẫu nhiên theo tỷ lệ xuất hiện). ### 1.4. Phòng QA (Kiểm Thử Khép Kín & Thẩm Định Trực Quan) - **Nguyên tắc cổng phủ quyết**: CHỈ CHO PHÉP PASS khi và chỉ khi: - 100% (tối thiểu 30 phong cách map) được nạp thành công vào database và code catalogs. - Toàn bộ 30 map có đầy đủ asset đồ họa hình ảnh, không thiếu bất kỳ texture chủ đạo nào. - Trình duyệt thực tế (kiểm chứng qua Chrome DevTools MCP / Playwright) hiển thị đồ họa chân thực, sinh động, có đường nét vân đất/đá/rêu rực rỡ thay vì các ô màu đơn sắc. - Tốc độ khung hình mượt mà >= 60 FPS, không có hiện tượng rò rỉ bộ nhớ (leak OffscreenCanvas) hoặc đơ lag khung hình khi nhân vật di chuyển qua các chunk mới. - Toàn bộ test suite tự động (`pytest`, lint hygiene) đạt 100% Green. --- ## 2. Requirements Cốt Lõi ### R1. Danh Mục & Cơ Sở Dữ Liệu 30 Phong Cách Map - R&D thiết kế và Trưởng phòng thiết kế xây dựng hoàn chỉnh CSDL SQLite `data/map_styles.db` cùng code catalog Python/JS chứa đúng tối thiểu **30 phong cách map** chuẩn Cổ Võ Hoang Vực. - Mỗi phong cách ánh xạ đầy đủ `biome_code` (1 đến 30+), bảng màu, hệ số di chuyển, loại quái vật và metadata đồ họa. ### R2. Kho Asset Đồ Họa 30 Phong Cách Bản Đồ - Tạo và cấu trúc thư mục tài nguyên `client/webapp/assets/map/styles/` (hoặc atlas tương ứng) cung cấp đầy đủ hình ảnh texture cho cả 30 phong cách (Floor texture, Wall texture, Path texture, Water/Liquid texture, Decal props). - Toàn bộ asset có kích thước tối ưu cho web/mobile, định dạng PNG nén nhẹ, đảm bảo tính thẩm mỹ hoang dã hắc ám. ### R3. Nâng Cấp Engine Texture Rendering (Client TileMapRenderer) - Nâng cấp `TileMapRenderer.js` hỗ trợ render bằng texture hình ảnh thực (`CanvasPattern` hoặc `drawImage` sprite): - Ánh xạ trực tiếp texture theo phong cách map hiện tại (`biomeCode` từ 1 đến 30). - Giữ lại hiệu ứng độ cao 2.5D extrusion cho tường vách và chướng ngại vật kết hợp cùng texture vách đá/gỗ rỉ. - Thêm cơ chế rải decal/props trang trí ngẫu nhiên dựa theo hash tọa độ ô để địa hình biến hóa, không bị lặp ô cơ học. - Cơ chế Graceful Fallback: nếu hình ảnh đang tải hoặc lỗi, tự động hiển thị bảng màu procedural tương ứng mà không crash game. ### R4. Tích Hợp Server Pipeline & API Cung Cấp Map Style - Cập nhật `server/world/map_biome_catalog.py`, `server/world/map_binary_serializer.py` và `WildernessMapGenerator` để hỗ trợ trọn vẹn dải mã biome từ 1 đến 30+. - Client WebApp cho phép chuyển đổi hoặc nạp bất kỳ phong cách nào trong 30 phong cách thông qua API hoặc tham số kiểm thử (`?biome=...` hoặc UI Debug switcher). ### R5. Kiểm Thử Khép Kín QA & Nghiệm Thu Trực Quan - Viết test suite chuyên trách kiểm toán cơ sở dữ liệu `data/map_styles.db`, kiểm tra tính toàn vẹn 30 styles, và kiểm tra sự hiện diện của 100% file asset trên đĩa. - Khởi động server WebApp và dùng Chrome DevTools kiểm chứng hiển thị trực tiếp trên trình duyệt thực, chụp ảnh màn hình nghiệm thu đồ họa sinh động chân thực. - Đảm bảo 100% bài test hiện có (1,240+ unit tests) và bài test mới đều PASS tuyệt đối. --- ## 3. Acceptance Criteria - [ ] `data/map_styles.db` được khởi tạo với ít nhất 30 phong cách map, có đầy đủ bảng `map_styles`, `map_style_tiles`, `map_style_props`. - [ ] `server/world/map_biome_catalog.py` và `client/webapp/js/data/map_style_catalog.js` đồng bộ đầy đủ 30 phong cách map. - [ ] Thư mục asset có đầy đủ tệp ảnh textures/sprites cho toàn bộ 30 phong cách map (tối thiểu 30 bộ textures hợp lệ). - [ ] `TileMapRenderer.js` thực hiện vẽ texture ảnh thật khi bake chunk `16x16`, loại bỏ hoàn toàn tình trạng chỉ có các ô màu phẳng. - [ ] Chuyển đổi giữa các phong cách bản đồ khác nhau hiển thị đúng bộ texture và màu sắc đặc trưng của phong cách đó. - [ ] RAM tiêu thụ của renderer <= 16.5 MB, FPS trung bình >= 60 FPS trong quá trình di chuyển camera. - [ ] Kiểm chứng thực tế qua Chrome DevTools: Chụp ảnh màn hình nghiệm thu bản đồ có vân đá, đất nứt, rêu mục và chi tiết sống động. - [ ] Toàn bộ unit tests mới và cũ đạt 100% pass; script kiểm tra vệ sinh mã nguồn `python tools/lint/check_code_and_doc_hygiene.py --strict` không có vi phạm Hard Cap. ## 2026-10-02T02:12:28Z Use a full team of agents. Xây dựng toàn diện hệ thống Tổ Đội 6 người với cơ chế nhân thưởng EXP/Currency theo PoE2, Quản lý Bạn Bè và Bang Hội, Dịch Chuyển Tức Thời an toàn, và Cổng Dịch Chuyển Sào Huyệt (Hideout Town Portal) với cơ chế khoá chống exploit phòng Boss và nhiệm vụ cho FreeExile. Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Hệ Thống Tổ Đội (Party System) & Nhân Thưởng Theo Quy Mô (Reward & Difficulty Scaling) - Hỗ trợ đầy đủ vòng đời tổ đội tối đa 6 người chơi: Tạo nhóm, mời đồng đội, chấp nhận/từ chối, chuyển quyền Đội Trưởng (Party Leader), rời nhóm và giải tán nhóm. - Cơ chế khuếch đại phần thưởng theo chuẩn mực Path of Exile 2: Tăng tỷ lệ và số lượng rơi đồ (Item/Currency Quantity & Rarity) và tăng kinh nghiệm (EXP bonus) theo số lượng thành viên cùng hiện diện trong phạm vi chia sẻ (Nearby Radius). - Hỗ trợ 3 chế độ phân bổ vật phẩm rớt (Loot Allocation) cấu hình bởi Đội Trưởng: 1. Permanent Allocation: Khóa đồ giá trị riêng cho từng người chơi. 2. Short Allocation: Khóa tạm thời 5 giây cho người được chỉ định, sau 5 giây chuyển sang tự do nhặt. 3. Free-For-All: Bất kỳ ai trong đội cũng có thể nhặt ngay lập tức. - Tự động điều chỉnh độ khó của quái vật (Dynamic Monster Scaling) tương ứng với số lượng thành viên trong phụ bản (tăng máu tối đa và kháng tính để bảo toàn tính cân bằng). ### R2. Hệ Thống Quản Lý Bạn Bè & Tương Tác Xã Hội (Friend List & Social Engine) - Quản lý danh sách bạn bè hoàn chỉnh: Gửi yêu cầu kết bạn, chấp thuận, từ chối, xóa bạn bè và chặn người chơi (Block list). - Cập nhật và truy vấn trạng thái thời gian thực của bạn bè: Online/Offline, cấp độ, khu vực/bản đồ đang hiện diện, ghi chú bạn bè (Friend Note). - Tích hợp liên kết danh sách thành viên Bang Hội (Guild Roster) phục vụ việc tương tác và dịch chuyển. ### R3. Hệ Thống Dịch Chuyển Tức Thời Hỗ Trợ Đồng Đội (Safe Teleportation) - Cho phép người chơi kích hoạt dịch chuyển nhanh đến vị trí của thành viên trong Tổ Đội, Bạn Bè hoặc Thành viên Bang Hội. - Quy chuẩn an toàn và chống lạm dụng: - Thời gian niệm chú (Cast time 3-4 giây), bị ngắt quãng lập tức nếu nhân vật di chuyển hoặc nhận sát thương từ bất kỳ nguồn nào. - Kiểm tra điều kiện đích đến: Từ chối dịch chuyển nếu khu vực đích đã đạt giới hạn người chơi, khu vực đã đóng/hết hạn, hoặc khu vực cấm người ngoài xâm nhập. ### R4. Hệ Thống Cổng Dịch Chuyển Sào Huyệt (POE2-Style Hideout Town Portal Engine) - Cho phép nhân vật mở Cổng Dịch Chuyển (Town Portal) từ vị trí bất kỳ ở dã ngoại hoặc ngục tối để quay về Sào Huyệt Cá Nhân (`zone_player_hideout`) hoặc Doanh Trại Hub (`zone_boundless_sanctuary`). - Quản lý vòng đời và số lượt của cổng dịch chuyển: Cho phép người chơi (và đồng đội trong party) di chuyển qua lại 2 chiều; ghi nhận và khấu trừ số lượt vào đối với các bản đồ giới hạn số cổng. - Cơ chế Khóa Khai Thác Tuyệt Đối (Anti-Exploit Quarantine): - Khóa hoàn toàn tính năng mở cổng hoặc dịch chuyển về Hideout khi đang trong giao tranh Boss (`boss_encounter_in_progress`). Cấm triệt để trick mở cổng trốn chết giữa trận đấu boss. - Khóa mở cổng trong các buồng mật thất giải đố/thử thách đếm ngược (`secret_chamber_active`) hoặc các phòng nhiệm vụ đặc thù nhằm ngăn chặn bug kẹt tiến trình hay nhân bản vật phẩm nhiệm vụ. - Xử lý trạng thái tử vong: Nhân vật chết trong phụ bản sẽ làm đóng cổng cá nhân hoặc tiêu hao 1 charge cổng của bản đồ theo quy chuẩn PoE2. ### R5. Đồng Bộ Ma Trận Thiết Kế & Cơ Sở Tri Thức (Game Design Matrix & Knowledge Base) - Khởi tạo bảng dữ liệu và tham số cân bằng vào CSDL Ma Trận Thiết Kế Game (`data/game_design_matrix.db`) hoặc schema liên quan. - Biên soạn tài liệu đặc tả kiến trúc chuẩn Diátaxis vào `docs/systems/` và lưu trữ các quy ước/tri thức dài hạn vào hệ thống bộ nhớ. ## Acceptance Criteria ### Kiểm Thử Tổ Đội & Công Thức Cân Bằng - [ ] Kiểm thử tự động (Unit Test) xác nhận nhóm từ 1 đến 6 người chơi: Công thức tăng thưởng EXP và Currency/Item Quantity tính đúng chuẩn xác theo từng thành viên trong bán kính lân cận. - [ ] Kiểm thử phạm vi chia sẻ (Nearby Radius): Thành viên đứng ngoài bán kính chia sẻ không được cộng dồn thưởng và không làm thay đổi hệ số rơi đồ của quái vật. - [ ] Kiểm thử 3 chế độ Loot Allocation: Xác nhận quyền nhặt đồ của từng thành viên tuân thủ nghiêm ngặt theo chế độ Permanent (độc quyền), Short (hết hạn 5s), và Free-For-All. ### Kiểm Thử Quản Lý Bạn Bè & Bang Hội - [ ] Kiểm thử toàn diện quy trình kết bạn, đồng ý, từ chối, chặn và cập nhật trạng thái Online/Zone tức thời. - [ ] Kiểm thử truy xuất danh sách bạn bè và hội viên bang hội với đầy đủ metadata trạng thái. ### Kiểm Thử Dịch Chuyển An Toàn & Chống Lạm Dụng - [ ] Kiểm thử thời gian niệm chú dịch chuyển: Bị hủy bỏ ngay khi nhân vật nhận sát thương hoặc bắt đầu di chuyển. - [ ] Kiểm thử từ chối dịch chuyển khi đích đến không hợp lệ (instance đầy, khu vực bị khóa tiến trình). ### Kiểm Thử Cổng Portal & Cơ Chế Khóa Phòng Boss - [ ] Kiểm thử mở Cổng Portal từ dã ngoại/phụ bản về Hideout thành công và tương tác di chuyển 2 chiều. - [ ] Kiểm thử kịch bản phòng Boss: Trong khi Boss đang giao tranh, lệnh mở Portal bị từ chối dứt khoát với thông báo lỗi bảo mật; sau khi Boss bị tiêu diệt hoàn toàn, cổng Portal được phép mở bình thường. - [ ] Kiểm thử buồng mật thất đếm ngược: Không thể mở portal trốn ra ngoài làm hỏng trạng thái phòng bí cảnh. - [ ] Kiểm thử tiêu hao số lượt cổng khi người chơi tử vong hoặc ra vào bản đồ. ## 2026-10-02T05:17:43Z # Teamwork Project Prompt Xây dựng phiên bản Web Client toàn màn hình (Full Screen) dành riêng cho PC Desktop tại `client/web_pc/`, tối ưu hóa trải nghiệm điều khiển chuột & phím chuẩn ARPG cổ điển (Path of Exile / Diablo style), tách biệt hoàn toàn khỏi khung mô phỏng di động nhưng tái sử dụng các engine dùng chung của FreeExile. Working directory: c:/Projects/FreeExile/client/web_pc Integrity mode: development ## Requirements ### R1. PC Full-Screen Layout & Canvas Architecture Xây dựng giao diện hiển thị web PC toàn màn hình chiếm trọn 100% chiều rộng và chiều cao màn hình (100vw, 100vh), tự động co giãn theo độ phân giải (hỗ trợ 16:9, 16:10, 21:9 Ultrawide). Loại bỏ hoàn toàn khung viền điện thoại (.iphone-frame), Dynamic Island, thanh dock mô phỏng, và joystick cảm ứng ảo. ### R2. Classic ARPG PC Input & Control System Triển khai hệ thống điều khiển chuột và bàn phím chuẩn ARPG: - Click chuột trái để di chuyển hoặc tấn công cơ bản (Click-to-Move & Move-to-Target). - Click chuột phải để thi triển chiêu thức chính. - Bàn phím số 1-5 và QWER thi triển các chiêu thức võ học và dược tề sinh tồn. - Phím Spacebar kích hoạt Huyễn Ảnh Bộ (trườn né né đòn với 0.25s i-frame). - Phím tắt mở nhanh giao diện: Tab/M (Bản đồ thu nhỏ / Đại đồ), I (Hành trang & Túi đồ), C (Bản đồ Căn cốt & Nhân vật), Esc (Tạm dừng / Trình đơn Cài đặt). ### R3. PC Grimdark Action HUD & Floating UI Thiết kế giao diện HUD đặc trưng của thể loại Dark Fantasy ARPG: - Cụm cầu sinh lực / chân khí (Health & Mana Globes / Bars) đặt đối xứng dưới đáy màn hình. - Thanh kỹ năng trung tâm (Action Bar) hiển thị rõ nhãn phím tắt (Q, W, E, R, 1, 2, 3, 4, 5, Space, Chuột Trái, Chuột Phải) kèm thời gian hồi chiêu (Cooldown Overlay). - Bản đồ con (Minimap) góc trên bên phải có chỉ báo phương hướng và tọa độ. - Khung tán gẫu (Chat Box) góc dưới bên trái có thể thu gọn/mở rộng. - Hỗ trợ tooltip chi tiết khi rê chuột (Hover) qua biểu tượng chiêu thức, trang bị hoặc thanh trạng thái. ### R4. Core Engine Integration & Zero Mobile Regression Tích hợp đồng bộ và mượt mà với các hệ thống sẵn có của FreeExile (Bộ dịch đa ngữ FreeExileI18n 9 ngôn ngữ, Cơ sở dữ liệu Võ học SkillDatabase, Hệ thống âm thanh Sound FX, Bộ quản lý Biome/Zone và Kết nối mạng WebSocket/Network Engine). Toàn bộ thay đổi phải nằm trọn trong `client/web_pc/` và không gây bất kỳ tác động hay lỗi hồi quy nào cho bản mobile web app tại `client/webapp/`. ## Acceptance Criteria ### Visual & Layout Checks - [ ] Truy cập trang web PC client hiển thị ở chế độ 100vw x 100vh mà không xuất hiện thanh cuộn trang bất thường (no scrollbars, no overflow). - [ ] Không tồn tại bất kỳ phần tử nào thuộc giao diện di động (`#simulator-bar`, `.iphone-frame`, nút joystick ảo cảm ứng). ### Control & Gameplay Checks - [ ] Nhấp chuột trái lên bề mặt bản đồ làm nhân vật di chuyển chính xác đến tọa độ mục tiêu. - [ ] Nhấn phím Space kích hoạt hoạt ảnh Huyễn Ảnh Bộ và trạng thái lướt né. - [ ] Nhấn các phím Q, W, E, R, 1, 2, 3, 4, 5 kích hoạt chiêu thức tương ứng trên Action Bar và kích hoạt bộ đếm thời gian hồi chiêu trực quan. - [ ] Nhấn phím `I`, `C`, `Esc` kích hoạt đóng/mở đúng các bảng tương ứng trên màn hình PC. ### Stability & Integration Checks - [ ] Tải trang không xuất hiện lỗi JavaScript (0 console errors) trên trình duyệt. - [ ] Chuyển đổi ngôn ngữ qua hệ thống `FreeExileI18n` cập nhật tức thì toàn bộ chuỗi hiển thị trên HUD PC mà không cần reload trang. - [ ] Bản mobile simulator tại `client/webapp/index.html` tiếp tục vận hành bình thường, không suy giảm tính năng. ## 2026-10-02T06:36:44Z Hoàn thiện toàn bộ 21 gói tài nguyên đồ họa còn tồn đọng trong `docs/design_requests/inbox/` của dự án FreeExile thông qua quy trình kết hợp AI Visual Generation, xử lý kỹ thuật đồ họa PBR 2.5D (Tangent-Space Sobel Normal Maps, Emissive Masks, Metal Compute Shaders), và quy trình thẩm định 2 cấp để đồng bộ vào Game Client WebApp. Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Kết Xuất Toàn Bộ Albedo Textures, Artworks & UI Atlas Tạo ra toàn bộ tài nguyên đồ họa gốc (Albedo/Diffuse) được chỉ định trong danh mục deliverables của 21 phiếu DRQ trong `docs/design_requests/inbox/`, bao gồm: - Màn hình chờ Full-bleed Artwork (`DRQ-20261001-CLI-LOADING-SCREEN-ART`) - Bộ 3 lớp nền Parallax màn hình đăng nhập (`DRQ-20261001-CLI-LOGIN-PARALLAX-LAYERS`) - Bộ nút điều khiển cảm ứng ProMotion Touch HUD (`DRQ-20261001-CLI-TOUCH-CONTROLS-PROMOTION`) - Lớp sương mù mây khí thế giới mở (`DRQ-20261001-CLI-WORLD-BACKGROUND-LAYERS`) - Giao diện bảng Hắc Thị Chợ Đen (`DRQ-20261001-ECO-BAZAAR-TRADE-PANELS`) - Bộ 6 pháp bảo tẩy luyện chế tác (`DRQ-20261001-ECO-CRAFTING-ORBS-CATALOG`) - Biểu tượng Cổ Cốt Huyết Thạch 5 bậc & Bụi Huyết Cốt (`DRQ-20261001-ECO-CURRENCY-BLOODSTONES`) - Cột sáng và tia sáng rơi đồ theo độ hiếm (`DRQ-20261001-ECO-LOOT-DROP-PARTICLES`) - 3 khung cảnh cốt truyện Prologue Cutscene (`DRQ-20261001-NPC-CUTSCENE-STORYBOARD`) - Chân dung đối thoại & Standee 5 Trưởng Lão Cổ Võ (`DRQ-20261001-NPC-FERAL-ELDERS-AVATARS`) - Biến thể cuộn giấy nhiệm vụ & mật lệnh (`DRQ-20261001-NPC-QUEST-SCROLL-VARIANTS`) - Huy hiệu cảnh báo an ninh & băng rôn cách ly (`DRQ-20261001-SEC-ALERT-BADGES-QUARANTINE`) - Hoạt ảnh khiên bảo mật App Attest (`DRQ-20261001-SEC-SHIELD-ACTIVE-ANIMATION`) - Lưới tọa độ giám sát gian lận & watermark pháp y (`DRQ-20261001-SEC-UI-FORENSIC-WATERMARK`) - Hiệu ứng kích hoạt Chiến Hồn Tế Cốt 3 cấp độ (`DRQ-20261001-SRV-AGENT-ORB-ACTIVATION-VFX`) - Biểu tượng đồng bộ AoI & chỉ số tickrate 30Hz (`DRQ-20261001-SRV-AOI-SYNC-TELEMETRY-VISUAL`) - Giao diện báo cáo thu hoạch offline (`DRQ-20261001-SRV-HARVEST-REPORT-OVERLAY`) - Giao diện lò rèn chế tác Lò Huyết Cốt (`DRQ-20261001-SYS-CRAFTING-STATION-UI`) - Bộ prop trang trí Sào Huyệt cá nhân & Mộc nhân (`DRQ-20261001-SYS-HIDEOUT-SAFEHAVEN-PROPS`) - Trận đài Tinh Đồ Nghi 6 cổng & Đấu trường Boss (`DRQ-20261001-SYS-MAP-DEVICE-ARENA`) - Node tương tác Huyết Cốt Ma Đồ & Nền tinh đồ (`DRQ-20261001-SYS-PASSIVE-TREE-NODES`) ### R2. Xử Lý Đồ Họa Kỹ Thuật (Tech Art Specifications) - Tất cả hình ảnh phải tuân thủ chuẩn kích thước lũy thừa 2 ($2^n$: $128\times 128, 256\times 256, 512\times 512, 1024\times 1024$, hoặc atlas chữ nhật $512\times 256, 1024\times 512$). - Với các tài nguyên yêu cầu Normal Map (`Normal Map Required: YES`), tạo tệp bản đồ pháp tuyến Tangent-Space Sobel (`*_normal.png`) đạt chuẩn độ sáng kênh xanh (Blue channel mean $\ge 128$). - Với các tài nguyên yêu cầu Emissive Mask, tạo tệp mặt nạ phát sáng lõi ma năng (`*_emissive.png`). - Cung cấp mã nguồn shader Apple Metal (`*.metal`) cho các hiệu ứng ánh sáng / hạt theo danh mục deliverables. - Cung cấp tệp metadata cấu hình lát cắt atlas (`*_metadata.json`) cho mỗi gói tài nguyên. ### R3. Thẩm Định 2 Cấp & Đồng Bộ Game Client - Thực hiện đầy đủ biên bản nghiệm thu 2 cấp (Cấp 1: QA Technical Audit, Cấp 2: CEO & Art Director Audit) trên toàn bộ 21 phiếu DRQ. - Di chuyển toàn bộ các phiếu đã duyệt từ `docs/design_requests/inbox/` sang `docs/design_requests/approved/`. - Đồng bộ toàn bộ tài nguyên tương ứng từ `assets/pending_review/` vào `assets/approved/` và thư mục asset của WebApp client (`client/webapp/assets/...`). ## Acceptance Criteria ### File & Asset Verification - [ ] Mọi deliverables nêu trong mục 4 của toàn bộ 21 tệp DRQ đều tồn tại trên đĩa và không rỗng (non-empty files). - [ ] Tất cả tệp hình ảnh `.png` đều mở được và thỏa mãn điều kiện kích thước là lũy thừa của 2 ($2^n$). - [ ] Kích thước tệp không vượt quá ngân sách dung lượng (Size Budget) quy định trong từng file DRQ. - [ ] Toàn bộ các tệp normal map (`*_normal.png`) có 3 kênh màu RGB với giá trị trung bình kênh xanh dương (Blue channel mean) $\ge 128$. ### Pipeline & Lifecycle Verification - [ ] Báo cáo kiểm định `python -m tools.asset_pipeline.design_pipeline_cli report` ghi nhận `inbox: 0` và số lượng `approved` tăng thêm 21 (từ 18 lên 39). - [ ] Thư mục `assets/approved/` chứa đầy đủ 21 thư mục con mới tương ứng với các mã DRQ. - [ ] Các asset cần dùng cho WebApp client được đồng bộ chính xác vào các thư mục con trong `client/webapp/assets/`. ## 2026-10-02T16:35:53Z Vận hành đội ngũ QA tự hành đa tác tử (Autonomous Multi-Agent QA Team) thực hiện kiểm thử chuyên sâu Client MMO ARPG FreeExile trên môi trường trình duyệt thật theo các tiêu chuẩn khắt khe nhất của ngành game trực tuyến (hiệu năng render 60/120fps, độ trễ phản hồi combat/i-frame, đồng bộ state/desync, độ bền phụ tải hạt VFX và rò rỉ bộ nhớ), đồng thời tự động lập tài liệu báo cáo kỹ thuật chi tiết phân loại theo từng phòng ban chịu trách nhiệm (Client, Server, Game Design, Art/VFX, Security) tại `docs/qa/reports/` để phục vụ khắc phục vấn đề. Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Real Browser MMO ARPG Deep Inspection Thực thi kiểm thử thực tế trên trình duyệt đối với Client Web/Mobile của FreeExile, giám sát và đánh giá nghiêm ngặt các chỉ số sống còn của một tựa game MMO ARPG: Frame rate & frame drops (mục tiêu 60fps/120fps), độ trễ phản hồi thao tác chiến đấu (combat input buffering, i-frame né tránh, combo chiêu thức), đồng bộ trạng thái mạng và phát hiện lỗi runtime qua Console và Network logs. ### R2. Responsive UI/UX, Viewport & Cross-Locale Validation Kiểm tra toàn diện hiển thị và tương tác trên đa kích thước màn hình (Desktop widescreen, Mobile portrait/landscape, Notch/Dynamic Island Safe Area), kiểm thử tính năng chuyển đổi đa ngôn ngữ (9 ngôn ngữ) phản xạ tại chỗ (in-place) mà không tải lại trang, và độ nhạy của các thành phần điều khiển (ảo joystick, nút bấm kỹ năng, hotswap vũ khí). ### R3. Stress, VFX Overload & Endurance Testing Thực hiện các kịch bản kiểm thử phụ tải cao và độ bền: Di chuyển liên tục qua các biome bản đồ, kích hoạt dồn dập các hiệu ứng hạt/VFX chiến đấu, thử nghiệm tại cọc bù nhìn (Target Dummy) với tần suất sát thương dày đặc, và theo dõi mức độ gia tăng bộ nhớ (Heap/DOM/WebGL contexts) để phát hiện rò rỉ bộ nhớ (memory leaks). ### R4. Actionable Cross-Department Issue Documentation Với mọi lỗi, độ trễ hoặc điểm nghẽn hiệu năng phát hiện được, tự động tạo tài liệu báo cáo chuẩn hóa được lưu trữ tại `docs/qa/reports/` theo cấu trúc phân định rõ cho 5 phòng ban: Client, Server, Game Design, Art/VFX, và Security. Mỗi báo cáo bắt buộc bao gồm: Mã định danh lỗi, Mức độ nghiêm trọng (Critical/High/Medium/Low), Các bước tái hiện chi tiết (Reproduction Steps), Trạng thái hệ thống & Logs bằng chứng, Phân tích nguyên nhân gốc rễ (Root Cause), và Đề xuất giải pháp khắc phục cho phòng ban đích. ## Acceptance Criteria ### Browser Testing Execution & Stability - [ ] Quy trình kiểm thử trình duyệt thật được khởi chạy thành công trên local web server và hoàn tất các kịch bản thử nghiệm gameplay ARPG cốt lõi (di chuyển, thi triển chiêu thức, né tránh, mở rương/menu). - [ ] Không có lỗi sập trình duyệt hoặc lỗi logic không được xử lý trong suốt phiên kiểm thử tiêu chuẩn. - [ ] Báo cáo ghi nhận đầy đủ các thông số đo lường hiệu năng thực tế (Frame time trung bình, p99 frame time, memory footprint trước và sau tải map). ### Documentation Quality & Departmental Routing - [ ] Thư mục `docs/qa/reports/` được khởi tạo và chứa đầy đủ các báo cáo sự cố được phân loại theo phòng ban chuyên trách tương ứng. - [ ] Mỗi báo cáo lỗi tuân thủ đúng cấu trúc định dạng chuẩn: Có mức độ nghiêm trọng, phân loại phòng ban, các bước tái hiện cụ thể, trích xuất log/telemetry và giải pháp kỹ thuật đề xuất. - [ ] Có một tài liệu tổng kết tổng thể (`docs/qa/reports/QA_EXECUTIVE_SUMMARY.md`) tổng hợp ma trận lỗi, mức độ rủi ro hệ thống và khuyến nghị thứ tự ưu tiên xử lý cho ban quản lý dự án. ## 2026-10-03T07:43:50Z Chuyển đổi toàn diện Client game FreeExile sang nền tảng Cocos Creator 3.x (TypeScript), bảo đảm tương thích 100% với kiến trúc Server C++/Python và giao thức Protobuf hiện tại; sau đó vận hành kiểm thử thực tế trên trình duyệt dưới góc độ của một người chơi thực (Human Player Empathy) và tổng hợp báo cáo nghiệm thu chuyên sâu. Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Cocos Creator 3.x Client Core Architecture & Porting Xây dựng dự án Cocos Creator 3.x hoàn chỉnh tại `client/cocos/` sử dụng TypeScript, kế thừa toàn bộ asset đồ họa (Sprites, Normal maps, Atlases, SFX, Catalogs) từ client hiện tại. Triển khai đầy đủ các hệ thống cốt lõi: - **Player & Camera Kinematics**: Điều khiển nhân vật 2.5D Isometric với cơ chế phanh dừng tức thì (Zero-Residual Momentum), A* pathfinding, va chạm trượt tường (Wall-Sliding), camera theo dõi exponential lerp và dynamic zoom. - **Combat & Animation System**: FSM hoạt ảnh (Idle, Run, Attack, Hurt, Dodge) kết hợp motion-matching, combo chiêu thức (Q/W/E/Space), telegraph chỉ báo đòn đánh của Boss và hiệu ứng vệt sáng vũ khí/hạt VFX. - **Sanctuary & Dungeon Scenes**: Tái hiện Doanh Trại Bến Lưu Đày với phân khu thoáng đãng, Y-sorting tự động, NPC tương tác mượt mà và Phụ Bản Ngục Tối có cơ chế mở Cổng Boss khi diệt đủ quái. - **UI HUD & Reactive i18n**: Thanh sinh lực/nội lực, Minimap đồng bộ vùng đất, kho đồ 40 ô, hộp thoại NPC và chuyển đổi ngôn ngữ phản xạ tại chỗ (9 ngôn ngữ) không tải lại trang. ### R2. Seamless Server & Protobuf Integration Kết nối trực tiếp vào cụm Server C++ và Python hiện có thông qua WebSocket Bridge cổng `8080`: - Tích hợp `protobufjs` để đóng gói và giải mã các thông điệp mạng chuẩn (`PlayerMoveInput`, `CombatAction`, `EntityState`, `ZoneData`). - Duy trì nguyên tắc Server-Authoritative 100%: Client chỉ mô phỏng hiển thị và nhận diện phản hồi, mọi chỉ số và giao dịch đều do Server quyết định. ### R3. Web Preview & Build Verification Stack Cung cấp pipeline biên dịch và khởi chạy Web preview cục bộ cho Cocos client, cho phép truy cập qua trình duyệt máy tính và giả lập mobile để kiểm thử không phụ thuộc công cụ ngoài. ### R4. Human-Centric Real-Browser Player Journey Testing (`/browser`) Vận hành kiểm thử E2E trên trình duyệt thực tế dưới góc độ của một game thủ ARPG đích thực (Human Player Perspective): - **Onboarding UX**: Luồng Đăng nhập, Tạo nhân vật, bấm `[🎲 Tên Ngẫu Nhiên]` nhận diện tức thì. - **Gameplay Feel & Phản hồi Thao tác**: Độ đầm chắc của bước chân, cơ chế dừng dứt điểm khi nhả phím/chuột (0 trôi dạt), phản xạ né đòn i-frame 0.25s, độ mượt combo khi thử đòn tại cọc gỗ (Target Dummy). - **NPC & Dungeon Progression**: Tự động tìm đường tiếp cận NPC không bị kẹt góc, mở hộp thoại mua bán/rèn đồ, vượt cổng ngục tối, diệt quái mở rào chắn phòng Boss và trảm Boss nhặt chiến lợi phẩm vào rương. - **Báo Cáo Nghiệm Thu Tổng Thể**: Lập tài liệu phân tích UX định lượng (FPS, Ping, Frame times) và định tính (cảm giác game, thẩm mỹ bản đồ, độ thỏa mãn khi nhặt đồ). ## Acceptance Criteria ### Cocos Client Implementation & Server Synchronization - [ ] Thư mục `client/cocos/` được thiết lập hoàn chỉnh với cấu trúc Cocos Creator TypeScript chuẩn, biên dịch thành công không có lỗi type-check. - [ ] Client kết nối thành công tới WebSocket Server `ws://127.0.0.1:8080`, gửi và nhận gói tin Protobuf ổn định với Server C++/Python. - [ ] Toàn bộ cơ chế điều khiển nhân vật đạt tiêu chuẩn: dừng ngay khi nhả phím/chuột, không có hiện tượng trôi dạt quán tính vô tận. ### Human-Centric Real-Browser QA & Report Delivery - [ ] Hoàn tất chuỗi kiểm thử 8 bước của hành trình người chơi trên trình duyệt thật (Login → Tạo nhân vật → Doanh Trại → Tương tác NPC → Đánh Cọc Gỗ → Vào Phụ Bản → Mở Cổng Boss → Diệt Boss Loot Đồ). - [ ] Bắt giữ đầy đủ ảnh chụp màn hình (screenshots) và logs làm bằng chứng cho từng bước trải nghiệm. - [ ] Xuất bản tài liệu báo cáo tổng hợp chi tiết tại `docs/qa/reports/COCOS_CLIENT_MIGRATION_AND_HUMAN_UX_REPORT.md`. ## 2026-10-04T09:01:16Z # Teamwork Project Prompt - Draft > Requested team: Full team Build a Character Stat Aggregator system for the server that calculates and aggregates stats from equipped items, the passive tree (Meridian), and base stats. It must support flat modifiers, percentage modifiers, tag-based modifiers, and conditional modifiers. The system must also persist the calculation formulas and logic into a database for future reference and auditing. Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Stat Aggregator Core Implement a `CharacterStatAggregator` in the server backend that correctly computes final attributes by combining base stats, item affixes from `inventory_service.py`, and passive stats from `meridian_service.py`. It must accurately handle flat additions, percentage multipliers, tag-based filters, and conditional modifiers. ### R2. Formula Persistence in Database The aggregator must output its calculation steps and formulas as a serialized JSON/AST structure, and save them into a local SQLite database table. This allows for historical auditing of exactly how a player's stats were calculated. ### R3. Server Engine Integration Wire the new `CharacterStatAggregator` into `server_engine_loop.py` so that when a player joins a map (`register_player`), their `CombatActor` is initialized with the fully aggregated stats instead of hardcoded base values. ## Acceptance Criteria ### Testing & Verification - [ ] A dedicated unit test or test script is provided that mocks a player with multiple items and passive nodes, and asserts that the final calculated stats exactly match the expected mathematical result. - [ ] The test suite verifies that the calculation formula is successfully written to the SQLite database in valid JSON format. - [ ] Running `server_engine_loop.py` tests or a manual verification script shows the `CombatActor` being instantiated with the aggregated stats rather than the default `50.0` attack damage. ## 2026-10-04T12:05:22Z Triển khai chu trình render thực thụ và đóng gói (pack) toàn bộ Texture Atlas nhị phân chuẩn PBR PoT cho 12 Kỹ năng Võ Học chủ động và 5 Ấn Ký Hỗ Trợ (sau đó tuần tự tới Quái Vật và Nhân Vật), thay thế hoàn toàn procedural canvas shader bằng tài nguyên đồ họa chất lượng cao tích hợp trực tiếp vào Cocos Creator 3.8.x và Apple Metal iOS. Working directory: c:\Projects\FreeExile Integrity mode: development ## Requirements ### R1. Render Chuỗi Khung Hình Kỹ Năng & Ấn Ký (High-Fidelity VFX Rendering) Render đầy đủ chuỗi khung hình chất lượng cao (frame strips) cho toàn bộ 12 Kỹ năng Võ Học chủ động (Active Skills) và 5 Thần Biến Phù/Ấn Ký hỗ trợ (Support Sigils) theo phong cách Grimdark Savage Dark Fantasy (vệt chém máu lửa, sóng xung kích rỉ sét, sấm sét dị biến, hư vô hắc ám), không sử dụng procedural drawing tạm bợ. ### R2. Đóng Gói Texture Atlas Nhị Phân Chuẩn PoT & PBR Normal Maps Đóng gói các chuỗi khung hình thành các tệp Texture Atlas chuẩn Power-of-Two ($1024\times 1024$ hoặc $2048\times 2048$), đi kèm Tangent-Space Sobel Normal Maps để hỗ trợ ánh sáng PBR thời gian thực. Áp dụng thuật toán Dilation Padding để triệt tiêu hoàn toàn hiện tượng viền đen/răng cưa (alpha bleeding) trên nền tối. ### R3. Xuất Bản Nhị Phân Cho Cocos Creator 3.8.x & Apple Metal iOS Tối ưu hóa và đóng gói tài nguyên vào thư mục tài nguyên của Cocos: `client/cocos/assets/resources/vfx/` và `client/cocos/assets/textures/`. Hỗ trợ định dạng nén phần cứng di động ASTC 4x4 cho iOS Metal API, đảm bảo tốc độ nạp 0ms và giữ ngân sách VRAM $< 450\text{MB}$ ở 120 FPS ProMotion. ### R4. Sinh Manifest Tọa Độ UV & Đồng Bộ SpriteAtlasRenderer Tự động sinh các tệp Manifest tọa độ khung hình (JSON/Binary Frame Descriptors) chứa kích thước frame, duration, sequence indices và anchor pivot chuẩn `[0.5, 0.90]`. Tích hợp và đồng bộ với script điều khiển `SpriteAtlasRenderer.ts` và shader `sprite_pbr.effect` trong Cocos. ### R5. Quy Chuẩn Đặt Tên & Kế Thừa Mở Rộng Cho Quái Vật & Nhân Vật Thiết lập cấu trúc thư mục và pipeline mẫu để tiếp tục mở rộng tuần tự cho chuỗi hoạt ảnh 8 hướng của Quái Vật (Monster Archetypes) và Nhân Vật Lưu Đày (Exile Characters + Weapon Pairs). ## Acceptance Criteria ### Technical & Engine Verification - [ ] 100% các sprite sheet kỹ năng được xuất xưởng đạt chuẩn Power-of-Two ($1024\times 1024$ / $2048\times 2048$) với cặp tệp Albedo + Tangent Normal Map. - [ ] Tệp UV Manifest JSON tương thích hoàn toàn với Cocos Creator 3.8.x, định vị chính xác từng khung hình và anchor pivot `[0.5, 0.90]`. - [ ] Toàn bộ tài nguyên được đồng bộ về đúng vị trí `client/cocos/assets/resources/vfx/`. - [ ] Kênh Alpha sạch 100%, không bị viền đen hoặc vỡ hạt khi kích hoạt hiệu ứng trên nền tối dưới ánh sáng PBR động. - [ ] Bộ kiểm thử xác thực pipeline đồ họa chạy thành công, không phát sinh ngoại lệ thiếu file hay sai định dạng.