# TEST_INFRA.md — 4-Tier Test Infrastructure Specification ## PBR Power-of-Two (PoT) Texture Atlas VFX & Cocos 3.8.x / Apple Metal iOS Pipeline - **Document Version**: 2.0.0 - **Target Platform**: Cocos Creator 3.8.x, WebApp PWA & Apple Metal iOS (120 FPS ProMotion) - **Authoritative Specifications**: - `ORIGINAL_REQUEST.md` (Header `## 2026-10-04T12:05:22Z`) - `PROJECT.md` (`orchestrator_22` architecture and interface contracts) - `FE-SURVEY-SKILLS-VFX-20261004` (`explorer_survey_1` Skills and Sigils matrix) - `SURVEY-20261004-ASSET-PIPELINE-TEXTURES` (`explorer_survey_3` PBR and Normal Map standards) - **Test Suite Location**: `tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py` - **Primary Test Runner**: `pytest tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py -v` --- ## 1. Test Architecture Overview The FreeExile VFX texture atlas and Cocos 3.8 client pipeline mandates strict real-time graphics performance, zero-trust server authority, and high-fidelity Grimdark Savage Cổ Võ visual aesthetics. To prevent visual defects, black halo bleeding, memory bloat, and engine desync, the testing infrastructure implements the rigorous **4-Tier Test Methodology**: ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 4-TIER TEST ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Tier 1: Category-Partition (Functional Feature Coverage) │ │ - 12 Active Skills + 5 Support Sigils present in Atlas and Manifest │ │ - Power-of-Two (PoT) dimensions (1024x1024 or 2048x2048) │ │ - Albedo Diffuse + Tangent-Space Sobel Normal Maps generated │ │ - Mobile ASTC 4x4 container file and canonical 16-byte header │ │ - Monster and Exile Character scaffolding directory & template structure │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Tier 2: Boundary Value Analysis (Corner & Extreme Cases) │ │ - Edge texel dilation padding (RGB > 0 where alpha == 0 on fringe) │ │ - Tangent Normal Map Blue channel mean > 128.0 (strict positive Nz) │ │ - Normalized UV coordinates bounded strictly in [0.0, 1.0] │ │ - Frame dimension matching between declared grid and pixel coordinates │ │ - Bottom-center anchor pivot precision [0.5, 0.90] │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Tier 3: Pairwise Combinations (Cross-Feature System Interleaving) │ │ - Active Skill + Support Sigil animation sequence compatibility │ │ - Tangent normal vector unit length normalization |N| = 1.0 │ │ - Cocos Creator vs WebApp client manifest cross-platform parity │ ├─────────────────────────────────────────────────────────────────────────────┤ │ Tier 4: Real-World Workload Scenarios (End-to-End Game Workflows) │ │ - Full combat loadout rotation simulation (Q / W / E / Space i-frame) │ │ - Cocos Creator 3.8.x TypeScript compilation check (npm run build:web) │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Tier 1: Category-Partition (Feature Coverage) ### 2.1. Feature Partitioning Input domain is partitioned into the canonical gameplay capabilities specified in `PROJECT.md` Features 1–9: | Partition ID | Feature Name | Canonical Requirement | Authoritative Source | |:---|:---|:---|:---| | **CP-01** | Active Skills VFX | 12 Active Skills present in manifest `clips` and atlas grid | `PROJECT.md:21`, `skill_catalog.ts` | | **CP-02** | Support Sigils VFX | 5 Support Sigils present in manifest `clips` and atlas grid | `PROJECT.md:22`, `support_skill_catalog.ts` | | **CP-03** | PoT Texture Packing | Dimensions are strictly Power-of-Two ($1024 \times 1024$ or $2048 \times 2048$) | `PROJECT.md:23`, `SURVEY-3:41` | | **CP-04** | Dual PBR Textures | Both Albedo (`*_atlas.png`) and Normal (`*_atlas_normal.png`) exist | `PROJECT.md:24`, `SURVEY-3:29` | | **CP-05** | ASTC Mobile Binary | Hardware-compressed ASTC 4x4 file with canonical 16-byte header | `PROJECT.md:28`, `SURVEY-3:225` | | **CP-06** | Extensible Scaffolding | Monster (10 genus) and Character (6 classes) pipeline scaffolding | `PROJECT.md:29`, `FE-SURVEY-1:134` | ### 2.2. Authoritative Active Skills (12 + Mobility) 1. `skill_1001_cuu_tieu_loi_kiem` (Thunder Piercing Greatsword) 2. `skill_1002_thanh_phong_van_kiem_vu` (Thunder Fan of Swords) 3. `skill_1003_u_minh_huyet_doc_cham` (Toxic Corrosion Needle) 4. `skill_1004_thien_ma_boc_doc_kinh` (Corpse Poison Nova Detonation) 5. `skill_1005_bang_phach_han_quang_tran` (Glacial Freeze Seal Arena) 6. `skill_1006_bang_tien_xuyen_tam` (Piercing Frost Arrow) 7. `skill_1007_liet_hoa_toan_phong_tram` (Fire Whirlwind Slash) 8. `skill_1008_liet_diem_boc_khi_tram` (Conflagration Magma Cleave) 9. `skill_1009_kim_cang_truy_dia_chan` (Ground Slam Shockwave Crater) 10. `skill_1010_kim_cang_bat_hoai_the` (Golden Vajra Unyielding Guard) 11. `skill_1011_huyet_ma_khap_huyet_kinh` (Blood Drain Chaos AoE) 12. `skill_1012_man_cot_trieu_hon_do` (Bone Totem Slam & Minions) - Core Mobility: `skill_1099_huyen_anh_bo` (0.25s i-frame Phantom Evasion) ### 2.3. Authoritative Support Sigils (5 Core Augments) 1. `sigil_2001_phan_quang_da_hoa_an` / `multi_projectile_split` (Multi-Projectile Split) 2. `sigil_2002_boc_pha_khuech_dai_an` / `aoe_expansion` (Area of Effect Expansion) 3. `sigil_2004_huyet_khi_quy_tong_an` / `blood_magic` (Blood Magic Conversion) 4. `sigil_2005_loi_dinh_xau_chuoi_an` / `chain_lightning_arc` (Chain Lightning Conduit) 5. `sigil_2006_cuc_lanh_an` / `freeze_affliction` or `sigil_2003_cuc_han_boc_kinh_an` / `damage_boost` ### 2.4. ASTC Container Header Specification The Apple Metal iOS texture container uses the canonical 16-byte ASTC header: ``` Offset Length Description 0x00 4 Magic number: 0x5CA1AB13 (bytes: 0x13, 0xAB, 0xA1, 0x5C) 0x04 1 blockdim_x (0x04) 0x05 1 blockdim_y (0x04) 0x06 1 blockdim_z (0x01) 0x07 3 xsize (little-endian 24-bit integer) 0x0A 3 ysize (little-endian 24-bit integer) 0x0D 3 zsize (little-endian 24-bit integer = 1) ``` --- ## 3. Tier 2: Boundary Value Analysis (Corner & Extreme Cases) ### 3.1. Edge Texels Dilation Padding - **Problem**: When bilinear filtering or mipmapping downsamples alpha-blended sprites on dark backgrounds, transparent pixels with $(R,G,B,A) = (0,0,0,0)$ pull edge colors towards black, creating dark fringe artifacts (alpha bleeding). - **Boundary Condition**: - Boundary fringe texel: $\text{pixel}(x, y)$ where $\alpha = 0$, but at least one immediate 8-neighbor has $\alpha > 0$. - **Invariant**: The RGB value of boundary fringe texels must be non-zero: $$\sum_{c \in \{R,G,B\}} \text{pixel}(x, y)_c > 0 \quad \text{while } \alpha(x, y) = 0$$ - At least $K \ge 500$ edge fringe pixels in the atlas must exhibit dilated color values. ### 3.2. Tangent Normal Map Blue Channel Mean ($\mu_B > 128.0$) - **Problem**: In tangent-space normal maps, surface normals are defined by: $$\vec{N} = (N_x, N_y, N_z), \quad N_z = \frac{1}{\sqrt{\Delta x^2 + \Delta y^2 + 1}} > 0$$ Color mapping: $B = \lfloor (N_z \times 0.5 + 0.5) \times 255 \rfloor \in [128, 255]$. - **Boundary Condition**: $$\mu_B = \frac{1}{W \times H} \sum_{x,y} \text{Blue}(x, y) > 128.0$$ - A mean $\le 128.0$ flags the severe OpenCV BGR channel swapping bug where $N_x$ was written to Blue and $N_z$ was written to Red. ### 3.3. Normalized UV Coordinate Bounds ($[0.0, 1.0]$) - For every frame declared in `manifest.clips` or `manifest.frames`: $$0.0 \le u_0 < u_1 \le 1.0, \quad 0.0 \le v_0 < v_1 \le 1.0$$ $$\text{frameWidth} = (u_1 - u_0) \times \text{textureWidth} = 128.0$$ $$\text{frameHeight} = (v_1 - v_0) \times \text{textureHeight} = 128.0$$ ### 3.4. Grounding Pivot Tolerance - Standard FreeExile bottom-center pivot: $$P_x = 0.50 \pm 10^{-4}, \quad P_y = 0.90 \pm 10^{-4}$$ --- ## 4. Tier 3: Pairwise Combinations (Cross-Feature Interleaving) ### 4.1. Active Skill $\times$ Support Sigil Augmentation Matrix Tests pairwise compatibility between active martial skills and augment sigils: | Pair ID | Active Skill (Host) | Support Sigil (Augment) | Frame Alignment | Expected Interaction | |:---|:---|:---|:---|:---| | **P-01** | `1001` (Thunder Sword) | `2001` (Multi-Projectile) | $128\times 128$, 16 fps | 3-way split projectile frame strips match timing | | **P-02** | `1002` (Wind Sword Fan) | `2005` (Chain Lightning) | $128\times 128$, 16 fps | Fan projectile transitions to chain arcs | | **P-03** | `1007` (Whirlwind Slash) | `2004` (Blood Magic) | $128\times 128$, 16 fps | Fire slash accompanied by arterial crimson aura | | **P-04** | `1009` (Ground Slam) | `2002` (AoE Expansion) | $128\times 128$, 16 fps | Crater fissure bounds scaled $1.5\times$ without texture clip | | **P-05** | `1003` (Toxic Needle) | `2006` (Freeze Sigil) | $128\times 128$, 16 fps | Poison needle augmented with frost shatter burst | ### 4.2. Tangent Vector Unit Length Invariant For all non-transparent pixels ($\alpha > 10$): $$\vec{N} = \left(\frac{R}{255} \times 2 - 1,\; \frac{G}{255} \times 2 - 1,\; \frac{B}{255} \times 2 - 1\right)$$ $$\|\vec{N}\| = \sqrt{N_x^2 + N_y^2 + N_z^2} \approx 1.0 \quad (\pm 0.08 \text{ quantization tolerance})$$ ### 4.3. Cocos Creator $\leftrightarrow$ WebApp Manifest Parity - Manifest schemas in `client/cocos/assets/resources/vfx/` and `client/webapp/assets/vfx/` must have: 1. Identical clip keys and frame sequences. 2. Matching FPS and duration values. 3. Shared texture dimension metadata ($1024$ or $2048$). --- ## 5. Tier 4: Real-World Workload Scenarios ### 5.1. ARPG Combat Rotation Simulation (Q / W / E / Space) Simulates a real human player executing an intense combat rotation at 120 FPS: 1. **Key Q**: Cast Skill 1001 (Thunder Sword) — 6 frames at 16 fps ($375\text{ ms}$). 2. **Key W**: Cast Skill 1007 (Whirlwind Slash) — 4 frames looping at 16 fps ($250\text{ ms}$). 3. **Key E**: Cast Skill 1009 (Ground Slam) — 6 frames at 16 fps ($375\text{ ms}$). 4. **Key Space**: Trigger Huyễn Ảnh Bộ (Phantom Evasion 1099) — 4 frames, $0.25\text{ s}$ invulnerability window. **Verification Assertions**: - All 4 animation clips exist in the manifest. - Total animation sequence step transitions yield valid frames. - Frame rect coordinates remain within canvas bounds $[0, \text{atlasSize}]$. - Simulated VRAM allocation footprint stays $< 450\text{ MB}$. ### 5.2. Cocos Creator TypeScript Compilation Gate - Executes `npm run build:web` (`tsc --noEmit`) in `client/cocos/`. - Must terminate with exit code `0` and zero TypeScript diagnostic errors. --- ## 6. Test Execution & Reporting Protocol ```bash # Execute entire E2E test suite with verbose output pytest tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py -v # Target specific testing tiers pytest tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py -k "Tier1" -v pytest tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py -k "Tier2" -v pytest tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py -k "Tier3" -v pytest tests/e2e_cocos/test_vfx_texture_atlas_pipeline_e2e.py -k "Tier4" -v ```