渲染验证与引擎落地技术选型

记录 AoifeLab Web 在「网站原型验证 → MCP 自动落地引擎」路径上的技术决策。
首验引擎：Unreal Engine（UE）

1. 总体目标

在网站内完成渲染效果的初步测试与搭建，验证通过后将资产经 MCP（Model Context Protocol） 自动分发到各游戏引擎实现，形成可复用的 TA 研发闭环。

网站验证（低成本、快迭代）
    ↓  Canonical Spec（语言无关契约）
MCP 分发层（Agent 可读、可执行）
    ↓
引擎落地（首验：UE → 后续：Unity / Godot 等）
    ↓
引擎内验证（RenderDoc 抓帧等）

与项目 Framework 材质研发管线一致：渲染特性库 → 算法库 → 原型验证 → UE 集成。

2. 核心原则

3. 双 GPU 运行时选型

网站内采用 WebGL + WebGPU 双运行时，按验证粒度分工，而非全站二选一。

3.1 WebGL — 特性函数验证（Shader 验证）

适用场景： 渲染特性库（/repo/rendering-feature）中，验证单个特性函数是否正确。

验证问题： 「这个 Feature_XXX 函数算对了吗？」

覆盖特性分类：

• Optical Transport（反射、折射、透射）
• Surface Layer（薄膜、清漆、各向异性）
• Micro Structure（闪粉、薄片、视差）
• Volume Effect（比尔定律、SSS）

与 UE 的关系： 验证的是材质函数级逻辑，对应 UE 侧 Custom HLSL 节点 / Material Function 的算法正确性。浏览器不编译 HLSL，网站运行时统一使用 GLSL。

3.2 WebGPU — 风格化画面验证

适用场景： 实验台（/lab）中，验证风格化效果与多 Pass 合成后的最终画面。

验证问题： 「这个画面风格 / Pass 链路对不对？」

覆盖特性分类：

• Stylized Feature（猫眼、Noise、Flow 等）
• 需要多 Pass 的复核场景（如 SSR 链路、FlowMap 全屏驱动）
• 物理特性在风格化场景中的整体观感复核（如 ThinFilm 肥皂泡场景）

与 UE 的关系： WebGPU 的 Pass 调度与资源绑定方式更接近 UE 现代管线（RDG、显式 Descriptor），适合作为「缩小版渲染管线实验室」，但不替代 UE 本身。

3.3 运行时路由规则

// 概念：按特性分类自动选择预览运行时
function getPreviewRuntime(category: FeatureCategory): "webgl" | "webgpu" {
  if (category === "stylized-feature") return "webgpu"
  return "webgl"
}

3.4 为何不用单一 API

结论： WebGL 负责「快」，WebGPU 负责「全」与「像 UE」；两者互补。

4. Shader 资产分层

同一特性在不同层使用不同语言载体，共享 Canonical Spec：

Canonical Spec（契约，语言无关）
    ├── glsl    → WebGL 网站预览（渲染特性库）
    ├── wgsl    → WebGPU 网站预览（实验台）
    └── hlsl    → UE MCP 导出（引擎落地）

4.1 函数签名（特性库统一接口）

float3 Feature_<Name>(float3 BaseColor, float3 Normal, float3 ViewDir)

隐式依赖（由宿主材质 / 预览运行时提供）：UV、世界空间变换等。

4.2 采样通道

通道定义写在 Spec 中；WebGL / WebGPU 各自实现纹理绑定，语义一致。

4.3 验证状态（规划）

将单一的 validated 拆分为两级：

5. MCP 与引擎落地

5.1 MCP 角色

MCP 是 Agent 与本站资产之间的协议层，不是渲染运行时。

站点入口：/tools/mcp、/tools/mcp/feature-spec
规划端点：/api/mcp（Streamable HTTP）

5.2 首验引擎：Unreal Engine

UE 集成按侵入程度分档，首验从低到高：

首条链路：

网站 Canonical Spec + HLSL 参考
    → MCP get_feature_spec / get_feature_hlsl
    → UE Custom HLSL 文件 + 母材质实例
    → LookDev 场景目视确认
    → RenderDoc MCP 抓帧对比（验证闭环）

5.3 现有 MCP 能力复用

6. 网站模块与代码映射

7. 数据流

7.1 WebGL 特性验证流

用户编辑 GLSL 代码
  → debounce → compileShader
  → 成功：球体预览更新 / 失败：显示编译错误

用户拖动参数滑条（来自 Spec）
  → 更新 uniform（无需重新编译）

用户更换采样（图片 / 算法）
  → 重新生成 iChannel 纹理 → 更新 uniform

7.2 WebGPU 风格化验证流

用户配置 Pass Graph（或选择预设场景）
  → 各 Pass WGSL 编译
  → 按依赖顺序执行 RenderPass / ComputePass
  → 输出最终画面

可将 WebGL 已验证特性作为 Graph 中的一个 Pass 输入

7.3 MCP → UE 落地流

特性 algorithmValidated = true
  → Agent 调用 MCP 读取 Spec + HLSL
  → 写入 UE 工程 Content/Shaders/Features/
  → Editor Python 更新母材质参数与节点
  → LookDev 确认 → RenderDoc 复核

8. 实施路线图

原则： 不等待 WebGPU 完成再启动 WebGL；UE 落地可与网站 WebGL 验证并行推进。

9. 关键决策记录

10. 相关文档

• 2026-07-15-渲染特性库预览与采样原型计划.md
• 2026-07-16-渲染特性Shader资产计划.md
• 2026-07-16-MCP开发计划.md
• 2026-07-16-工具MCP子页面计划.md
• 2026-07-16-MCP特性规则设计子页面计划.md

修订记录