粒子系统导出
LayaAir 粒子系统总览
Section titled “LayaAir 粒子系统总览”LayaAir 拥有 GPU、CPU、VFX 三套互补共存的粒子系统，覆盖全场景需求：
GPU 全程驱动，大规模粒子无 CPU 开销，适合海量简单粒子（火花、雨雪、星点等）。
对标 Unity Particle System，模块丰富、可编程性强，适合复杂行为与精细特效。
百万级粒子 + 程序化生成，节点蓝图驱动，表现力极致，适合次世代场景与电影级特效。
与 Unity 粒子的导出对应关系：
| Unity 粒子 | LayaAir 粒子系统 | 说明 |
|---|---|---|
Shuriken（ParticleSystem 组件） | GPU 粒子 或 CPU 粒子 | 随 Export Tool 场景 / 预设导出，两条互斥路径按第一章的规则逐对象决策；第一至五章详述 |
VFX Graph（.vfx 资产 / VisualEffect 组件） | VFX 粒子 | 通过独立的「VFX-SHADER 转换器」把 .vfx 转为 .laya.vfx，不走 Export Tool 场景导出；第六章详述 |
一、模式决策：GPU 还是 CPU
Section titled “一、模式决策：GPU 还是 CPU”首步——每个粒子系统按规则确定走 GPU 还是 CPU。 判定按三级优先决定导出模式：
- 物体 / 父级挂了
LayaParticleExportSetting组件：用它的exportMode（ShurikenParticle=0/CPUParticle=1）。沿父链向上查找。 - 否则自动检测
RequiresCPUParticle：粒子用了 Noise（噪声）/ Trails（拖尾）/ LimitVelocityOverLifetime（速度限制） 任一 → 强制 CPU（这些是 GPU 路径不支持的模块）。 - 否则用全局默认：
ExportConfig.ParticleExportMode，出厂默认0= GPU（Shuriken）。
第 3 级 · 全局默认： 导出窗口「其他设置」里的 Particle Export Mode 开关（Shuriken (GPU) / CPU Particle）——作用于没挂覆盖组件、也未命中自动检测的粒子。
第 1 级 · 手动指定： 给粒子物体加 LayaAir / Particle Export Setting 组件，Export Mode 下拉二选一：Shuriken Particle（GPU）/ CPU Particle。
第 2 级自动切换时，导出会在 Unity Console 打印提示：
[LayaAir Export] 'StaffSwish': 检测到 GPU 不支持的模块 [Noise]，自动切换为 CPU 粒子导出。二、GPU 路径（Shuriken）
Section titled “二、GPU 路径（Shuriken）”默认路径——判定为 GPU 时导出 ShurikenParticleRenderer，逐模块映射。 导出组件 _$type: ShurikenParticleRenderer，逐模块映射：main / startLifetime / gravity / emission / shape / velocityOverLifetime / colorOverLifetime / sizeOverLifetime / rotationOverLifetime / colorBySpeed / sizeBySpeed / forceOverLifetime / textureSheetAnimation。
导出前 · Unity： 粒子系统检视器——持续时间 / 起始生命周期 / 起始速度、发射、突发、形状等模块，逐项导出到 Laya。
渲染模式（renderMode）决定粒子面片如何朝向与成形——面向相机的广告牌、沿速度方向拉伸，或用网格作为粒子。Unity 的渲染模式映射到 Laya 对应值如下：
| renderMode | 值 | 说明 |
|---|---|---|
| Billboard | 0 | 默认，永远面向相机。0 为默认值，不写入产物 JSON（if (renderMode != 0) 才写字段） |
| Stretch | 1 | 拉伸（带速度方向参数） |
| HorizontalBillboard | 2 | 水平面片 |
| VerticalBillboard | 3 | 垂直面片 |
| Mesh | 4 | 用网格当粒子（maxParticles × meshVertexCount 即总顶点数） |
实测·导出后在 Laya 正确渲染： 一个默认 Billboard + 叠加（Additive）材质的 GPU 粒子，导出前后效果一致。
Unity： 默认粒子系统（Billboard，柔和圆形粒子）。
LayaAir： 导出后正常渲染，形态一致。材质产物 "type":"PARTICLESHURIKEN"、materialRenderMode:3（叠加）。
三、CPU 路径
Section titled “三、CPU 路径”判定为 CPU 时导出 ParticleSystem + Plus* 模块，表达 GPU 路径不支持的效果。 顶层组件 _$type: ParticleSystem，子模块用 Plus 命名（Laya CPU 粒子模块）：突发 PlusBurst、曲线关键帧 FloatKeyframe、网格粒子 MeshItem 等。过程中做 Unity→Laya 语义转换，例如突发 cycleCount=0（Unity 的 Infinite）→ Laya -1（Infinite）。CPU 路径能表达 GPU 不支持的 Noise / Trails / 速度限制，代价是 CPU 模拟开销。
实测·导出后在 Laya 正确渲染： 给一个粒子勾上 Noise（噪声） 模块，命中自动检测被转为 CPU 导出，导出前后效果一致。
Unity： 含 Noise 模块的粒子，命中自动检测 → CPU 路径。
LayaAir： 导出后正常渲染，形态一致。材质产物 "type":"CpuParticle3D"。
四、粒子材质
Section titled “四、粒子材质”两条路径各对应一种粒子材质类型。 下表按导出情况列出对应的材质 type：
| 情况 | 函数 | 材质 type |
|---|---|---|
| GPU + shader 已注册 | WriteParticleMaterial | PARTICLESHURIKEN |
| CPU 粒子 | CPU 路径 | CpuParticle3D |
| shader 未注册 + 没开自定义 shader | WriteParticleMaterialGeneric | 回退内置粒子 shader |
五、各模块支持差异
Section titled “五、各模块支持差异”各 Unity 粒子模块在两条路径下的支持情况如下。 GPU（Shuriken）只支持广告牌/网格 + 各 over Lifetime 这类，复杂模拟类模块需走 CPU；少数模块两条路径都不支持。
| Unity 模块 | GPU 路径 | CPU 路径 |
|---|---|---|
| Noise（噪声） | ✗ | ✓ |
| Trails（拖尾） | ✗ | ✓ |
| Limit Velocity over Lifetime（速度限制） | ✗ | ✓ |
| Inherit Velocity（继承速度） | ✗ | ✓ |
| Collision（碰撞） | ✗ | ✓ |
| Force over Lifetime（力） | ✗ | ✓ |
| Color / Size / Rotation by Speed（按速度变化） | ✗ | ✓ |
| External Forces（外力） | ✗ | ✓ |
| Sub Emitters（子发射器） | ✗ | ✓ |
| Lights（灯光） | ✗ | ✗ |
| Trigger（触发器） | ✗ | ✗ |
| Custom Data（自定义数据） | ✗ | ✗ |
| 其余常规模块（发射 / 形状 / 各 over Lifetime…） | ✓ | ✓ |
六、VFX Graph 粒子导出
Section titled “六、VFX Graph 粒子导出”以上第一至五章讲的是 Unity 内置 Shuriken 粒子（ParticleSystem 组件），随 Export Tool 场景 / 预设一起导出。VFX Graph 是另一套体系——Unity 的节点图式 GPU 粒子（.vfx 资产、场景中挂 VisualEffect 组件），LayaAir 对应的是 VFX 粒子系统。本章讲它的导入导出，与前面的 Shuriken 流程完全独立
6.1 转换器入口与界面
Section titled “6.1 转换器入口与界面”转换器是插件里独立于 Export Tool 的一个工具窗口，同时负责 VFX Graph 与 ShaderGraph（蓝图）的转换。
- 菜单入口：
LayaAir3D 3.0 / VFX-SHADER Converter，打开「转换器」窗口。
窗口有单文件和多文件两个页签：
| 页签 | 用途 | 主要控件 |
|---|---|---|
| 单文件转换 | 转换单个源文件 | 源文件（.vfx 或 .shadergraph，按扩展名自动识别类型）、输出目录（可空，空则输出到源文件同目录）、「转换」按钮 |
| 多文件转换 | 递归批量转换整个目录 | 源目录、目标目录、三个转换类型开关（蓝图 / VFX / 应用 prefab 属性覆盖）、「开始批量转换」按钮，保留相对子目录结构 |
窗口底部是日志区，转换后打印结果、依赖资源拷贝报告与缺失资源清单。
6.2 转换操作流程
Section titled “6.2 转换操作流程”以单个 .vfx 为例（多文件批量同理，只是换成选目录）：
- 打开转换器：菜单
LayaAir3D 3.0 / VFX-SHADER Converter，切到「单文件转换」页签。 - 选源文件：浏览选中要转换的
.vfx资产；窗口会提示「识别为：VFX（.vfx → .laya.vfx）」。 - （可选）设输出目录：留空则输出到
.vfx同目录。 - 点「转换」：插件先扫描资源映射（读 Unity 工程与 VFX/URP 包的
.meta建 GUID→类映射，并从已导出资源的 Laya 工程侧取纹理 / 网格 / shader 的 uuid），再把.vfx（Unity YAML）解析、转换、写出<名称>.laya.vfx（JSON 格式的节点图）。 - 收集依赖：转换器从产物里抓出所有引用的资源（
res://uuid），在 Laya 资源工程里按 uuid 反查真实文件（网格 / 纹理 / shader），连同.meta拷到输出目录旁的_deps/文件夹。 - 看日志：日志区列出产物路径、已拷贝的依赖数量，以及找不到的资源清单（多半是还没用 Export Tool 导出的 FBX / 贴图，提示先导出再重转）。
6.3 导入 LayaAir 与使用
Section titled “6.3 导入 LayaAir 与使用”转换主产物是一个 Laya .vfx 节点图（JSON 格式），内含上下文、算子、暴露属性等，对应 Laya VFX 粒子系统的图结构。放进 Laya 工程即可使用：
- 产物文件名是
<名称>.laya.vfx（.laya后缀只为避免和同目录的 Unity 源文件<名称>.vfx重名）。放进 Laya 工程时去掉.laya，改回<名称>.vfx。 - 拷进 Laya 工程
assets目录，在 IDE 里双击打开该.vfx→ 保存一次，编辑器会自动编译出运行时资源（.lvfx+computeshader），无需手动处理。 - 导入后，节点图、暴露属性（Blackboard）、图级设置（Initial Event 等）都完整保留：
怎么在场景里播放、用代码驱动？ 转换后的 VFX 与 Laya 原生 VFX 完全一致：挂
VisualEffect组件、事件触发、暴露属性的运行时读写等用法，见 VFX Graph 文档 系列（IDE 操作流程、图级与组件、代码篇）。
转换成品对比（Unity 原版 vs LayaAir）
Section titled “转换成品对比（Unity 原版 vs LayaAir）”以某治疗特效为例，把贴图 / shader 补齐后，转换产物在 LayaAir 中运行的实际画面与 Unity 原版基本一致——发射形态、十字光符、上升运动、整体观感都得到还原：
注：图逻辑（发射、模块、曲线、渐变、运动）由转换器自动还原；贴图 / 网格 / 自定义 shader 需按上文方式在 Laya 工程里补齐后，才能得到与原版一致的最终观感。
6.4 转换能力与边界
Section titled “6.4 转换能力与边界”VFX 转换器把 Unity VFX Graph 的节点图整体翻译成 Laya 的 VFX 节点图，覆盖面较广——上下文、算子、块、曲线渐变、暴露属性都在转换范围内。下面按类别说明支持面。
6.4.1 上下文（Context）与输出类型
Section titled “6.4.1 上下文（Context）与输出类型”VFX Graph 的系统流程节点（Spawn → Initialize → Update → Output）都能转换，各 Output 类型映射到 Laya 对应的输出上下文：
| Unity Output 类型 | Laya 输出 | 说明 |
|---|---|---|
| Planar Primitive（含 Lit / URP Lit / HDRP 变体） | 广告牌 | 面向相机的四边形粒子 |
| Mesh（含 Lit / URP Lit 变体） | 网格粒子 | 用网格作为粒子 |
| Static Mesh（含 Lit / URP Lit 变体） | 静态网格粒子 | 与 Mesh 是不同的输出类型 |
| Quad Strip / Particle Strip（含 Lit / URP Lit 变体） | 拖尾 | 条带 / 拖尾粒子 |
| Cube / Line / Point / Line Strip | 立方体 / 线 / 点 / 线条带 | 各对应 Laya 同类输出 |
| Composed Particle（组合粒子） | 组合粒子输出 | 复合拓扑 |
| Decal（URP / HDRP） | 广告牌（降级） | 贴花无专用输出，按广告牌近似 |
其中，若 Output 使用了 ShaderGraph 作为着色（topology 为 Mesh / Quad 且 shading 为 ShaderGraph），网格 / 广告牌输出会升级为专门的「ShaderGraph 网格 / ShaderGraph 广告牌」输出，并绑定由 ShaderGraph 转换出的着色器属性表达式图。
Spawn 块支持 Constant Rate（恒定速率）/ Burst（单次突发）/ Periodic Burst（周期突发）/ Variable Rate（变速率）/ Set Spawn Event Attribute（设置生成事件属性）/ Custom（自定义包装）。
6.4.2 块（Block）
Section titled “6.4.2 块（Block）”块的映射覆盖了 VFX 常用的绝大多数类别（映射表约 60 余条），主要有：
- 属性设置：Set Attribute（设置任意粒子属性）、Attribute from Curve（曲线驱动属性）、Attribute from Map、Color over Life（生命期颜色）。
- 朝向与位置：Orient（朝向，含 Along Velocity / Fixed Axis 等模式）、Position Shape（球 / 盒 / 锥 / 环 / 圆 / 线各形状发射）、Position Mesh / Depth / SDF / Sequential（网格 / 深度 / SDF / 序列位置）。
- 速度：Velocity Direction / Randomize / Spherical / Tangent（方向 / 随机 / 球面 / 切向速度）。
- 力场：Gravity（重力）、Drag（线性阻力）、Force（力）、Turbulence（湍流）、Vector Field Force（矢量场力）、Vortex（涡旋）、Conform to Sphere / SDF（吸附到球 / SDF）。
- 碰撞与消亡：Collision Sphere / AABox / Plane / Cone / Torus / SDF / Oriented Box（各形状碰撞）、Kill Sphere / AABox / Plane / Cone / Torus（各形状消亡区）。
- 其他：Camera Fade（相机淡入淡出）、Subpixel AA、Tile Warp、Flipbook Play（翻页动画播放）、Connect Target、Screen Space Size、Trigger Event（触发事件）、Custom HLSL（自定义 HLSL 块）。
6.4.3 算子（Operator）
Section titled “6.4.3 算子（Operator）”运算节点覆盖面很广（映射表约 100 条），包括：
- 数学：加减乘除、取模、取负、绝对值、三角函数（Sin / Cos / Tan）、取整（Floor / Ceil / Round）、幂 / 开方、Min / Max、Clamp / Saturate / Smoothstep、Lerp / InverseLerp / Step、Remap、One Minus、Fractional、Sign、Reciprocal 等。
- 向量 / 矩阵：Length / Distance / Normalize、点积 / 叉积、Append / Swizzle、Transform Position / Direction / Vector / Matrix、Look At、极坐标 / 球坐标互转。
- 采样：Sample Curve（曲线）、Sample Gradient（渐变）、Sample Texture 2D / 3D / Cube / 2DArray、Sample Mesh Position / Normal / Tangent / UV / Color / Index、Sample Point Cache、Sample SDF / Bezier。
- 噪声：Perlin / Value Noise、Curl Noise、Voro Noise。
- 粒子 / 时间 / 逻辑：Get Attribute、Age over Lifetime、Total Time、Random、Compare / Branch / Switch、Sequential 3D / Line / Circle 等。
- 属性：Get Property（读取暴露属性）。
6.4.4 曲线与渐变
Section titled “6.4.4 曲线与渐变”- 曲线（AnimationCurve） 烘成 Laya 曲线的关键帧数据——每个关键帧保留 7 个分量（时间、值、入 / 出切线、入 / 出权重、加权模式），无曲线数据时用 0→1 线性默认。
- 渐变（Gradient） 把 Unity 分离的颜色键（colorKeys）与透明度键（alphaKeys）按时间点并集重采样、合并成 Laya 的
stops色标数组（[{t, color:{r,g,b,a}}]），内联进.laya.vfx，不生成独立文件。另有两个后处理：HDR 条带渐变逐键最大值归一、stops 转成 IDE 渐变控件格式（规避 IDE 编译器的一个 bug）。
6.4.5 暴露属性
Section titled “6.4.5 暴露属性”暴露属性（Exposed Properties）完整保留：VFX 图上的暴露参数会转成 Laya 的 properties，保留暴露名、暴露标志、类型、默认值，还支持分组（m_Category）与数值范围（Min / Max）。默认值按类型处理——纹理 / 网格解析成 uuid、渐变转成 stops、向量 / 颜色给默认值。暴露参数还会参与着色器属性绑定的表达式图。
两个边界：Transform 类型的暴露属性会被跳过；从子图内联进来的参数不算用户暴露属性（不写进 properties）。
6.4.6 转换策略与边界
Section titled “6.4.6 转换策略与边界”转换器的总体策略是尽力转换 + 收集警告 + 缺省填默认，全程零崩溃。需要注意的边界：
- 坐标系转换：Unity 左手系 → Laya 右手系，位置 / 速度 / 角度等按分量取反。
- 子图（Subgraph）内联：先展开进主图，再整体转换。
- 降级处理：Masked 混合模式无对应，降级为 Opaque；Decal 无专用输出，归为广告牌；4 个内置参数（Frame Index / Play Rate / Fixed Time Step / Max Delta Time）无对应，跳过并记警告。
- 静默跳过（不崩溃）：映射表里没有的未知块 / 算子、被禁用（disabled / activation=false）的块、与所在上下文类别不匹配的块，都会被直接跳过；曲线若序列化成非法值（Infinity / NaN，即所谓 broken tangent），整条曲线丢弃、回退为默认曲线。
- 警告不可见：上述跳过 / 降级多数会记入转换器内部的警告列表，但这些内部警告目前不会显示在转换器窗口日志里——用户在窗口里只能看到资源依赖的缺失报告。因此转换后建议在 Laya IDE 中打开
.laya.vfx核对效果，确认没有关键节点被静默丢弃。
本页基于插件源码（Editor/Export/vfx/）与实测整理。