godot-particles

粒子系统中绝对不要做的事

• 绝对不要使用 amount_ratio 动态优化性能——这既不会节省 GPU 内存，也不会提升处理速度；仍会分配完整的 amount。请直接更改 amount 属性。
• 绝对不要在桌面平台的性能关键型效果中使用 CPUParticles2D——除非目标是没有 GPU 支持的低端移动设备，否则请使用 GPUParticles。不过，如果需要在 2D 中为移动物体实现平滑拖尾的物理插值，请使用 CPUParticles2D。
• 绝对不要将 preprocess 设置为极高的值——较高的值（例如 60s）会迫使 GPU 在单个渲染周期内模拟数千帧，可能导致 GPU 立即崩溃。
• 大型系统绝对不要不配置 visibility_aabb——不正确的 AABB 会导致视锥剔除错误（粒子突然消失），并破坏 LOD 计算。请使用编辑器工具栏生成 AABB。
• 未经测试，绝对不要在移动设备／Web 平台上启用湍流——对每个粒子进行 3D 噪声计算的开销极大。请通过 Feature Tags 在低端平台上禁用。
• 绝对不要使用 Timer 清理生命周期结束的单次粒子效果——优先使用 smart_oneshot_recycler.gd：finished + restart()；只有对确实不再需要的实例才使用 queue_free()。
• 拖尾绝对不要使用 local_coords = true——弹丸留下的烟雾或火焰必须使用全局空间（local_coords = false），否则拖尾会像僵硬的棍子一样跟着弹丸移动。
• 绝对不要指望 GPUParticles2D 在 Godot 4.3 中正确插值——当它们挂载在物理物体下时会发生卡顿。高速 2D 移动时，请使用 fract_delta = true 的 CPUParticles2D。
• 收到 finished 信号后，绝对不要立即触发 emitting = true——异步 GPU 状态延迟可能导致重启失败。请改用 restart() 方法。
• 绝对不要尝试通过子发射器实现递归——粒子系统不能将自身设为子发射器；这样做会静默失败。
• 绝对不要忘记颜色渐变中的 alpha——粒子在生命周期结束时瞬间消失会显得生硬；请始终在 1.0 处添加一个 alpha 为 0.0 的渐变点，实现平滑淡出。
• 体积爆炸绝对不要使用 EMISSION_SHAPE_POINT——在同一个点生成所有粒子会让效果显得扁平。请使用 Sphere 或 Box 形状，实现自然的 3D 扩散。
• 单次 VFX 初始时绝对不要忘记设置 emitting = false——这样可以避免在有机会通过脚本定位节点之前，粒子就在场景原点意外发射。

选择表（仅加载匹配的脚本）

对所选行而言，必须遵守。单个效果不要加载未使用的粒子脚本。

目标	优先选用	脚本
爆发／单次 VFX（命中、枪口、爆炸）	GPUParticles* + 回收	必须 particle_burst_emitter.gd + smart_oneshot_recycler.gd
移动物体后方的轨迹	local_coords = false	必须 local_vs_global_coords.gd
天气（雨／雪）高度场	摄像机跟随的碰撞体	必须 screenspace_weather_heightfield.gd
百万级实体群	MultiMesh，而非 GPUParticles	必须 massive_swarm_multimesh.gd
自定义 GPU 运动／userdata	进程材质着色器	custom_particle_logic.gdshader、dynamic_userdata_modulation.gd
碰撞子发射器	碰撞子粒子	sub_emitter_impact.gdshader
避免吸引器产生全局开销	cull_mask 隔离	particle_attractor_opt.gd
远处环境 VFX 的 LOD	visibility_range	particle_lod_manager.gd
由 2D 物理节点驱动的轨迹出现卡顿	CPUParticles2D + fract_delta	必须 2d_physics_interpolation_fix.gd
着色器参数编排	材质辅助工具	vfx_shader_manager.gd

GPUParticles、CPUParticles 与 MultiMesh 的区别

• GPUParticles* —— 桌面／主机平台 VFX 数量预算的默认选择。
• CPUParticles2D —— 仅在需要 2D 物理插值／平滑父节点跟随时使用（参见“绝不使用”）。
• MultiMesh —— 实体数量超出粒子适用范围时使用（鱼群／昆虫／碎片场）。

可用脚本

smart_oneshot_recycler.gd

单次效果生命周期的推荐方案：finished + restart()，绝不基于 Timer 释放。

particle_burst_emitter.gd

连接到回收器的单次爆发效果。

local_vs_global_coords.gd

光环与轨迹的坐标空间 + 传送时调用 restart()。

screenspace_weather_heightfield.gd

通过摄像机跟随的高度场碰撞体实现全局天气。

massive_swarm_multimesh.gd

使用 set_buffer_interpolated() 实现百万级实体方案。

custom_particle_logic.gdshader

使用 CUSTOM/USERDATA 实现程序化 GPU 粒子运动。

sub_emitter_impact.gdshader

由碰撞驱动的 emit_subparticle() 冲击效果。

particle_attractor_opt.gd

吸引器的 cull_mask 隔离。

dynamic_userdata_modulation.gd

运行时使用 USERDATA，而不破坏 GPU 批处理。

particle_lod_manager.gd

用于环境 VFX 的 visibility_range 层级结构。

2d_physics_interpolation_fix.gd

CPUParticles2D + fract_delta，用于由物理节点驱动的 2D 轨迹。

vfx_shader_manager.gd

粒子材质的自定义着色器集成辅助工具。

专家提示

• 单次效果：在场景原点设置 emitting = false → 放置 → 调用 restart()（smart_oneshot_recycler.gd）。
• 轨迹：设置 local_coords = false，否则轨迹会粘在投射物上。
• 不要在此处臆造爆炸／烟雾／闪光材质配方——材质界面请参阅官方文档；本技能负责生命周期、坐标、LOD 和群集方案选择。

深入探讨（按需）

• 碰撞子发射器、流体着色器、VFX 池 → expert-vfx-patterns.md
• VFX 池回收模式 → vfx_pool_manager.gd
• 原因：GPU 粒子无法驱动逐次碰撞的 SFX——CPU 没有碰撞回调；只能使用子发射器或循环播放的撞击音效底音。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在切换到相邻领域时加载相关技能——不要预先加载整个技能网络。

官方文档

• 粒子系统（2D） — GPUParticles2D/CPUParticles2D 设置、amount/lifetime/one-shot，以及 2D 拖尾需要 CPU 粒子才能平滑运动的情况。
• ParticleProcessMaterial 2D — 发射形状、重力/速度曲线和颜色渐变，无需自定义着色器即可驱动大多数 2D VFX。
• 创建 3D 粒子系统 — GPUParticles3D 场景连接、处理材质分配，以及 3D VFX 首次发射检查清单。
• 处理材质属性 — ParticleProcessMaterial 发射、力、缩放/颜色曲线，以及专家模式中使用的碰撞/子发射器模式。
• 粒子属性 — 节点级别的 amount、lifetime、explosiveness、local_coords、可见性 AABB、preprocess，以及 restart/finished 生命周期。
• 粒子子发射器 — 串联撞击/碎屑系统，以及粒子系统无法递归地将自身用作子发射器的原因。
• 粒子碰撞 — GPUParticlesCollision* 形状、刚体/隐藏模式，以及 GPU 碰撞相对于 CPU 同步 SFX 的限制。
• 粒子吸引器 — 吸引器类型，以及 cull_mask/图层隔离，避免全局天气承担每个吸引器的开销。
• 粒子拖尾 — 拖尾带，以及烟雾/火焰拖尾必须使用全局空间（local_coords = false）的原因。
• 粒子着色器 — shader_type particles、CUSTOM/USERDATA、COLLIDED/emit_subparticle()，以及 keep_data 处理循环。
• 使用 MultiMesh — 何时应让数百万个实体绕过 GPUParticles，改用 MultiMesh 和插值缓冲区。
• 可见性范围 — GeometryInstance3D 距离淡出/滞后机制，可停止处理远处的环境粒子。

相关技能

前置条件

• godot-project-foundations — 在打包 VFX Prefab 和 GradientTexture1D 材质前，了解场景、资源和导入基础知识。
• godot-gdscript-mastery — 掌握类型化 GPUParticles API、finished 处理器，以及池和爆发生成器使用的安全 restart()/await 模式。
• godot-shaders-basics — 在编写 shader_type particles 处理逻辑前，了解 ShaderMaterial 工作流和着色语言基础。

补充项

• godot-3d-materials — 绘制材质、透明度排序，以及用于渲染 GPUParticles3D 生成的四边形/网格的 next_pass 堆栈。
• godot-3d-lighting — 发光火焰/火花与环境曝光；当 VFX 必须照亮场景时，将粒子反照率与真实光源搭配使用。
• godot-audio-systems — GPU 发射器运行期间的撞击/循环音效，适用于无法使用逐粒子碰撞音频的情况。
• godot-performance-optimization — 当 VFX 占用大量 GPU 时间时，调整粒子数量预算、可见性 AABB、吸引器遮罩，以及切换到 MultiMesh。
• godot-camera-systems — 摄像机跟随高度场、可见范围阈值，以及考虑视锥体的天气发射器。
• godot-signal-architecture — 为必须避免残留幽灵回调的池化回收器，规范 finished 和一次性连接的使用。
• godot-2d-physics — 由物理节点作为父节点的 2D 拖尾；在这种场景中，CPUParticles2D + 插值可取代会卡顿的 GPUParticles2D。

下游 / 使用方

• godot-combat-system — 在伤害结算时生成的命中火花、血液/碎片爆发效果和枪口特效。
• godot-ability-system — 与技能生命周期和目标反馈关联的施法/引导/命中特效。
• godot-genre-shooter — 基于这些粒子模式构建的枪口闪光、曳光弹、爆炸和环境烟雾堆栈。
• godot-monte-carlo-balancer — 当 VFX 密度/可读性影响感知难度或预警清晰度时，通过战斗结果模拟表现力预算。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。