# STEP-081 iOS Metal Renderer 与真机 Smoke 入口 Codex 完成报告 v1

## 1. 执行结论

PARTIAL。Codex 代码实现与静态检查完成，但当前受控执行环境拒绝创建 `.git/index.lock`，所以无法暂存、提交或 push。iPhoneOS build/Metal runtime/真机验收未运行，Step 保持 `WAITING_RDC_BUILD_REVIEW`。

## 2. Git 基线

- branch：`particle/main`
- Start HEAD：`f23f4143b9642de0e8d6661dd567e791494a0a0b`
- End/Final HEAD：`f23f4143b9642de0e8d6661dd567e791494a0a0b`（未创建 commit）。
- 初始工作树有未跟踪任务书 `docs/40_任务/STEP-081_iOS_Metal_Renderer与真机Smoke入口_Codex任务_v1.md`；它不属于本提交。

## 3. 实现摘要

新增 Metal `ParticleGpuValidationShader`，覆盖 State A/B、trail fade、line draw、composite/frozen composite、WeatherColor、timeMix、field/respawn bounds、VELOCITY 与 DIRECTION、独立 particle/trail/speed color、weather ramp、invalid discard 与 matrix projection。Metal source 明确复用 31×16-byte UBO。

Metal registry 在 `RendererBackend::initShaders` 注册，属性和 texture table 由 stable shader IDs 映射；CMake Metal list 显式包含新增 source。

iOS Test App 的 Runtime Styling 菜单提供 `Particle / QBIN V4 Smoke (T0)` action sheet。Smoke 使用 bundle 中从 RN Wind Golden fixture source copied 的 T0/T1，private `MLNMapView::mbglMap` seam 创建现有 C++ source/layers，并允许 T0/midpoint/T1 和 clear/reload。

## 4. 与任务书差异

无架构差异。CMake fixture copy 采用 POST_BUILD app-bundle copy，而非在仓库复制 fixture。未建立 iOS SDK public API。

## 5. 构建与静态检查

- 构建：`NOT_RUN_BY_DESIGN — Codex prohibited from building`。
- 未运行 Xcode/CMake/Ninja/Make/Bazel/clang/metal/simctl/真机命令，未运行 Jest。
- 静态检查：`git diff --check`；Metal source/registry/CMake/fixture path 的 `rg` 结构检查；RenderRasterParticleLayer 与 RenderWeatherColorLayer gfx API read-only review。

## 6. 风险和未完成项

MSL 的实际 compiler diagnostics、Metal float render target/line pipeline compatibility、runtime shader compilation、device visual output、clear/recreate release 均待 RDC 真机验证。没有 simulator 验收计划。

## 7. 给 GPT/RDC 的验收清单

1. 用 `platform/ios/app/CMakeLists.txt` 的 `app` target 和 Metal-enabled iPhoneOS CMake/Xcode generation 路径执行 device build（勿使用 Simulator）。
2. 安装到真实 iPhone/iPad，进入 Settings → Runtime Styling → `Particle / QBIN V4 Smoke (T0)`。
3. 依次触发 T0、midpoint、T1；确认日志 `ParticleQbinV4Smoke: event=FIELD_READY`、`WeatherColorLayer: event=WEATHER_COLOR_FIELD_READY`、particle state/trail resource creation，且 WeatherColor 与 particles 均可见。
4. 触发 Clear / release，再次 Load T0，确认 `CLEAR_RELEASED` 及资源重建。
5. 若 runtime MSL compile/pipeline 失败，按此顺序检查 `particle_gpu_validation.hpp` pass source、`.cpp` attribute/texture table、`renderer_backend.cpp` registry、`cmake/metal.cmake` list；特别核对 UBO buffer index 与 `short2` attribute binding。

## 8. Git 收尾

未完成：执行 `git add` 时 Git 返回 `Unable to create .../.git/index.lock: Operation not permitted`。因此 commit hash、push result、remote branch 与新的 Final HEAD 均不存在；不得宣称已完成 Git 收尾。具备 `.git` 写入权限的 RDC/GPT 应复核 diff 后仅暂存本报告列出的 STEP-081 文件，提交 `feat: bring up particle renderer on ios metal` 并 push `origin/particle/main`。