# Project: FreeExile Cocos Creator 3.x Client Migration & Human-Centric Player Journey Verification

## Architecture
- **Client Cocos Creator 3.x (TypeScript)** (`client/cocos/`):
  - `assets/scripts/core/`: Math25D, CameraController, KinematicsEngine, AStarPathfinder, WallSliding.
  - `assets/scripts/animation/`: AnimationFSM, SpriteAtlasRenderer, MotionMatching, PivotManager.
  - `assets/scripts/combat/`: CombatController, ComboManager, EvasionController (0.25s i-frame), TelegraphRenderer, DamageNumberBuffer.
  - `assets/scripts/network/`: NetworkManager, ProtobufCodec, OpcodeRegistry, EntityInterpolator (0.25 damping).
  - `assets/scripts/proto/`: Compiled protobufjs ES modules (`bundle.js`, `bundle.d.ts`).
  - `assets/scripts/world/`: ZoneController, SceneManager, BossGateController, YSortManager, TargetDummy.
  - `assets/scripts/ui/`: HudController, LiquidOrbView, MinimapView, InventoryView (40 slots), NpcDialogueView, CharCreationView, I18nManager.
  - `assets/resources/`: Shaders (`sprite_pbr.effect`), Atlases, Sprites, Normal maps, Audio SFX, Manifests.
  - `preview-template/` & `web-preview/`: Local HTTP web preview and mobile simulation harness.
- **Server Gateway & Protocol Layer**:
  - `server/gateway/ws_gateway_bridge.py`: WebSocket bridge on port 8080 with dual binary Protobuf (2-byte Opcode) and JSON diagnostic handling.
  - `proto/`: All 17 canonical schemas (`network.proto`, `combat.proto`, `map_zone.proto`, `auth.proto`, etc.).
  - `server_cpp/` & `server/world/`: Authoritative 30Hz simulation, zero-residual momentum verification, movement authority.
- **Human-Centric QA & Verification Stack**:
  - `tools/qa/run_cocos_human_journey.py`: Playwright browser automation for the 8-step player journey.
  - `docs/qa/reports/COCOS_CLIENT_MIGRATION_AND_HUMAN_UX_REPORT.md`: Comprehensive UX evaluation report with empirical metrics and screenshots.

## Feature Inventory
Every feature from user requirements and surveys is cataloged with its assigned milestone:
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | Cocos Project & TS Config | Canonical CC 3.8 layout, package.json, tsconfig.json, project.json | M1 | Survey 3 / R1 |
| 2 | Shader & PBR Asset Pipeline | Sprite PBR normal mapping (`sprite_pbr.effect`), 21 animation manifests | M1 | Survey 1 / R1 |
| 3 | 2.5D Isometric Math & Coordinates | 2:1 projection (64x32 tiles), screen-to-world & world-to-screen transforms | M2 | Survey 1 / R1 |
| 4 | Zero-Residual Momentum Kinematics | Instant digital brake in frame 0 when input mag <= 0.05, 0 residual drift | M2 | Survey 1 / R1 |
| 5 | Wall-Sliding & A* Pathfinding | 2-axis sliding along obstacles, zero-heap allocation A* grid pathfinding | M2 | Survey 1 / R1 |
| 6 | Camera Lerp & Dynamic Zoom | Exponential damping camera tracking player with smooth zoom | M2 | Survey 1 / R1 |
| 7 | Animation FSM & Motion Matching | Idle, Run, Attack, Hurt, Dodge FSM with 8 directions & bottom-center pivot | M2 | Survey 1 / R1 |
| 8 | Protobufjs ES Module Compilation | Compiled static ES bundle for all 17 proto schemas | M3 | Survey 2 / R2 |
| 9 | 2-Byte Opcode Network Framing | Big-endian uint16 opcode header + protobuf binary payload over WebSocket | M3 | Survey 2 / R2 |
| 10 | WebSocket Bridge Port 8080 | Connect to ws://127.0.0.1:8080, heartbeat ping/pong, auto-reconnect | M3 | Survey 2 / R2 |
| 11 | 30Hz Server Reconciliation | Exponential damping (0.25) reconciliation, last_processed_input_seq sync | M3 | Survey 2 / R2 |
| 12 | Sanctuary Safe Haven & Y-Sorting | `zone_boundless_sanctuary` 100% monster-free, depth = wx + wy sorting | M4 | Survey 1 / R1 |
| 13 | 4 Encampment NPCs & Dialogue | Scavenger, Blacksmith, Shaman, Tracker with interaction radii <= 2.5m | M4 | Survey 3 / R1 |
| 14 | Target Dummy Combat & Combos | Immortal dummy at (6.0, -3.0), Q/W/E/Space combos, DPS telemetry | M4 | Survey 1 / R1 |
| 15 | 0.25s i-frame Dodge Roll | Invulnerability frames, ghost trail effect, instant attack cancel | M4 | Survey 1 / R1 |
| 16 | Boss Gate State Machine | 3-pack encounter threshold, runic seal ring, obstacle-to-floor mutation | M4 | Survey 3 / R1 |
| 17 | Strand Executioner Boss & Loot | Boss combat, HP 18,500, telegraphs, loot fountain with rarity beams | M4 | Survey 3 / R1 |
| 18 | Dual Liquid Orbs & Minimap | HP/MP fluid orbs with wave crests, 120x80 minimap with Fog of War | M5 | Survey 1 / R1 |
| 19 | 40-Slot Backpack Inventory | 40 slots, item tooltips, rarity borders, auto-pickup integration | M5 | Survey 3 / R1 |
| 20 | Character Creation & Randomizer | 6 archetypes, 12 Vietnamese martial names [🎲 Tên Ngẫu Nhiên] | M5 | Survey 3 / R4 |
| 21 | Reactive 9-Language i18n | In-place atomic UI string re-render (vi, en, zh, ja, ko, th, de, ru, es) | M5 | Survey 1 / R1 |
| 22 | Web Preview & Mobile Simulation Stack | Local HTTP preview on port 8088/7456, responsive 1080p & mobile viewport | M6 | Survey 3 / R3 |
| 23 | Human-Centric Real-Browser QA | Playwright 8-step player journey test with screenshots & telemetry capture | M6 | Survey 3 / R4 |
| 24 | UX Analysis & Handoff Report | Quantitative & qualitative report at `COCOS_CLIENT_MIGRATION_AND_HUMAN_UX_REPORT.md` | M6 | Survey 3 / R4 |
| 25 | E2E Testing Suite (Tiers 1-4) | Opaque-box requirement-driven test verification suite (110+ tests) | M_E2E | Dual Track |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| M1 | Cocos Project Setup & Asset Pipelines | Features 1-2: CC 3.8 structure, tsconfig, shaders, manifests | none | DONE |
| M2 | Kinematics, Camera & Animation FSM | Features 3-7: Iso math, zero-momentum, wall-slide, A*, FSM | M1 | DONE |
| M3 | Protobuf & Server Integration | Features 8-11: Protobufjs, opcode framing, ws 8080, 30Hz recon | M1 | DONE |
| M4 | Combat, Scenes & Boss Encounter | Features 12-17: Sanctuary, NPCs, Dummy, combos, Boss Gate, Boss | M2, M3 | DONE |
| M5 | UI HUD, 40-Slot Bag & Reactive i18n | Features 18-21: Orbs, Minimap, 40 slots, char creation, i18n | M4 | DONE |
| M6 | Web Preview, Human QA & UX Report | Features 22-24: Web preview stack, 8-step browser QA, report | M5, TEST_READY | DONE |
| M_E2E | E2E Opaque-Box Test Track | Feature 25: Comprehensive requirement-driven test suite (178 tests) | none | DONE |

## Interface Contracts
### Client Kinematics & Movement ↔ Server MovementAuthority
- `PlayerMoveInput { seq: uint32, input_x: float, input_y: float, client_time: double, buttons: uint32 }`
- `EntitySnapshot { entity_id: uint32, pos_x: float, pos_y: float, vel_x: float, vel_y: float, heading_deg: float, state: uint32, last_processed_input_seq: uint32 }`
- Instant Brake Contract: When `input_x == 0 && input_y == 0`, client predicted velocity snaps to 0 immediately in frame 0. Server confirms zero-momentum.

### Client Combat ↔ Server CombatEngine
- `CastMartialSkillRequest { skill_id: uint32, target_entity_id: uint32, target_pos_x: float, target_pos_y: float, client_timestamp: double }`
- `CombatDamageEvent { attacker_id: uint32, target_id: uint32, damage_amount: float, element: uint32, is_crit: bool, remaining_hp: float, poise_broken: bool }`
- `PhantomEvasionRequest { direction_angle: float, timestamp: double }` -> triggers 0.25s i-frame window.

### Scene & World Contracts
- `BossGateState`: `0: LOCKED` (obstacle tile, runic seal active), `1: UNLOCKED` (walkable tile, runic seal dissolved upon 3 pack kills), `2: BREACHED` (player entered arena).
- `SafeHavenPolicy`: `zone_boundless_sanctuary` enforces 0 hostile spawns, 100% safe zone, dummy allows damage telemetry without retaliation.

## Code Layout
- `client/cocos/`: Root of Cocos Creator 3.8 TypeScript project
- `client/cocos/assets/scripts/`: TypeScript source files (<= 350 lines per logic file)
- `client/cocos/assets/resources/`: Atlases, audio, shaders, manifests
- `client/cocos/preview-template/`: Web preview harness & HTML shell
- `server/gateway/`: `ws_gateway_bridge.py`, `authoritative_gateway_service.py`
- `tools/qa/`: Browser QA automation scripts, Playwright test runners
- `docs/qa/reports/`: QA test reports and screenshots