# BRIEFING — 2026-10-04T12:17:15Z

## Mission
Investigate Cocos Creator 3.8.x and Apple Metal iOS integration in FreeExile (SpriteAtlasRenderer, sprite_pbr.effect, UV manifests, textures, VFX, and zero-allocation hot paths).

## 🔒 My Identity
- Archetype: explorer
- Roles: [investigation, synthesis]
- Working directory: c:\Projects\FreeExile\.agents\teamwork\explorer_survey_2
- Original parent: 34037784-62e1-41f8-bfe6-912696fdec14
- Milestone: Cocos Creator 3.8.x & Apple Metal iOS Integration Survey

## 🔒 Key Constraints
- Read-only investigation — do NOT implement
- Write only to .agents/teamwork/explorer_survey_2/
- Follow Handoff Protocol & 5-component report structure

## Current Parent
- Conversation ID: 34037784-62e1-41f8-bfe6-912696fdec14
- Updated: not yet

## Investigation State
- **Explored paths**:
  - `client/cocos/assets/scripts/animation/SpriteAtlasRenderer.ts`
  - `client/cocos/assets/scripts/animation/AnimationFSM.ts`
  - `client/cocos/assets/resources/shaders/sprite_pbr.effect`
  - `client/assets/shaders/SpritePBRNormal.metal`
  - `client/cocos/assets/resources/skills/elemental_particles.metal`
  - `client/cocos/assets/resources/vfx/savage_primal_skills_vfx_atlas.json`
  - `client/cocos/assets/resources/skills/martial_skills_metadata.json`
  - `client/cocos/assets/resources/animations/char_sword_master_anim_manifest.json`
  - `client/webapp/js/engine/animation_engine.js`
  - `client/webapp/js/engine/vfx_renderer.js`
  - `client/cocos/assets/scripts/combat/CombatController.ts`
  - `client/cocos/assets/scripts/data/skill_catalog.ts`
  - `client/cocos/assets/scripts/data/support_skill_catalog.ts`
  - `tools/asset_pipeline/produce_all_missing_skills_vfx.py`
  - `tools/asset_pipeline/savage_vfx_factory.py`
  - `tools/perf/ios_metal_profiler.py`
  - `tests/e2e_cocos/test_tier1_cocos_assets.py`
- **Key findings**:
  - `SpriteAtlasRenderer.ts` creates garbage allocations (`new Rect`, arrays, objects) on hot path, violating 120 FPS ProMotion zero-allocation mandate.
  - `SpriteAtlasRenderer.ts` assumes a static 1-row-per-clip mapping, causing coordinate drift on sequential and custom VFX clips.
  - Four incompatible manifest schemas exist across the codebase (Character, SpriteAtlasRenderer, VFX, and Static Skills).
  - Only 7 skills/sigils exist in `savage_primal_skills_vfx_atlas.png`; 10 active skills and 3 support sigils are completely absent.
  - `client/cocos/assets/textures/` does not exist; dynamic assets reside in `assets/resources/vfx/`.
  - No VFX playback component exists in Cocos to handle `EventBus.emit('skillCasted', ...)`.
  - PBR Tangent-Space Normal map lighting in `sprite_pbr.effect` is operational, but lacks rim lighting and ghost alpha compared to `SpritePBRNormal.metal`.
- **Unexplored areas**: None within the scope of this survey.

## Key Decisions Made
- Completed survey of Cocos 3.8.x and Metal integration.
- Documented complete architecture, gaps, and remediation plan in `analysis.md` and `handoff.md`.

## Artifact Index
- analysis.md — Full deep-dive technical investigation report
- handoff.md — 5-component handoff report for orchestrator
- progress.md — Liveness heartbeat and completed task index
- DISPATCH.md — Incoming instruction record