scenario-godot-vfx

Godot VFX

目标：Godot 4.7.2.stable，macOS Apple Silicon。

这里的专家级意味着：将特效构建为多个小系统组成的层级；每个静默的粒子故障都会在任何人查看前由脚本捕获；每项关于视觉效果或成本的说法，都有精确时刻捕获的帧，以及按渲染器测得的过度绘制和 GPU 耗时作为依据。Agent 通过代码构建特效，以窗口模式渲染，并查看联系表。如果此处提到的某个同级技能不在你可用的技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，请根据工具架构继续操作，并标明缺失之处。

必备背景： scenario-godot-expert（gd_env、gd_run、gd_review、AgentKit、GD_MAX 插槽、窗口模式与无头模式）。

核心立场（专家级的关键差异）

1. 特效由多个层组成，弹丸的头部不是粒子。 弹丸由头部、尾迹和火花组成；头部是一个带滚动噪声和高于 1 的 HDR 颜色的着色器网格（Le Lu 74XywaLGO5Q 00:00:34、00:08:05）。爆炸由闪光、火焰、烟雾、火花、碎片、冲击波和光照组成，每一层都是通过复制一个可用系统并修改少量数值构建的小系统（Brackeys htRjt505sPg 00:02:30、00:13:27）。冲击波环使用单粒子系统也完全可行（00:18:02）。
2. 粒子设置可能静默失效，因此要用代码审计。 没有 vertex_color_use_as_albedo，颜色和 Alpha 曲线不会生效；粒子广告牌没有 billboard_keep_scale，缩放曲线不会生效；尾迹需要 trail_enabled、Ribbon 或 Tube 尾迹网格，以及 use_particle_trails（Godotneers cZ5Ang_Ji8E 00:09:44、00:32:54；Brackeys 00:23:44）。子发射器自身的 amount 是全局上限（Godotneers yKoGuBGZatY 00:44:48），且不会继承 AABB（cZ5Ang_Ji8E 01:06:19）。vfx_audit.gd 会标记所有这些问题。
3. visibility_aabb 既是剔除范围，也是碰撞区域（Godotneers cZ5Ang_Ji8E 00:45:28）。应进行测量，而不是猜测：在 4.7.2 中，capture_aabb() 会按绘制网格的最长轴扩展粒子位置，但会忽略每个粒子的缩放（实测：2 m 的 Flash 四边形产生了 4 m 的框；缩放到 4.5 m 的环仍然只有 2 m）[新增]。fit_aabb 会修正缩放，且必须在关卡内运行，因为没有碰撞体的碎片会穿过世界掉落 8 m。
4. 按渲染器划分档位，绝不使用 amount_ratio。 amount_ratio 只会隐藏粒子，并不能节省任何资源（GPUParticles3D 文档；Bonkahe BUa-mKHEPUM 00:01:18）。每个档位都应降低 amount，并移除渲染器无法绘制的层。兼容模式会在不发出警告的情况下移除贴花，并为尾迹和子发射器记录警告（实测）[新增]。
5. 粒子不会影响物理效果。 游戏命中检测来自每个物理帧执行一次的扫掠射线；粒子碰撞需要 GPUParticlesCollision 节点，每帧的步长为速度 / fixed_fps，默认 fixed_fps 为 30（Godotneers cZ5Ang_Ji8E 00:44:23、00:47:17）。
6. 增强手感的效果也应是可测试的代码。 命中停顿会降低 Engine.time_scale，并等待一个不受其影响的计时器，然后恢复为 1.0（Mostly Mad Jwv9t5zFlqI 00:00:32、00:01:37）。镜头震动通过带衰减的平滑噪声实现（Mostly Mad pG4KGyxQp40 00:00:39）；创伤值平方和 3D 摄像机偏移为[新增]。
7. 评判帧，而不是检查器。 使用 --fixed-fps 60 以窗口模式渲染，这样第 k 帧的时间 t = k/60 s；时间范围为 0.03 到 2.2 s，并为每个渲染器查看一张联系表。过度绘制通过 DEBUG_DRAW_OVERDRAW 和按层测得的校准值获取；GPU 耗时来自 Vulkan 驱动（Metal 在 macOS 上报告为 0）[新增]。
8. 跟随节点的尾迹是一种粒子着色器技巧。 在 start() 和 process() 中将粒子固定到 EMISSION_TRANSFORM[3].xyz，不施加任何力（Octodemy iPCzOe-S9EQ 00:05:42）。

首先确定

输入	影响	默认值
目标渲染器	存在哪些层（轨迹、贴花、子发射器）	Forward+ 桌面端、手机端 Mobile、Web 兼容模式
2D 还是 3D	节点系列、碰撞（LightOccluder2D 与 GPUParticlesCollision3D）	3D
摄像机距离和屏幕占比	四边形尺寸、过度绘制预算	游戏摄像机距离 4 到 10 m
VFX 帧预算	各层级的数量	在 720p 下，开发用 Mac 上六次爆发的 GPU 耗时低于 2.5 ms［新增］
外观	无光照加法混合与有光照烟雾（Le Lu e_6ZA-xa_DQ 00:07:23）	风格化、无光照火焰、Alpha 混合烟雾
生成模型	完成后释放与对象池	fx_burst 自行释放；对象池使用 done 信号

工作流

1. 项目和工具包。 克隆 Base3D，gd_vfx.install(P) 会将工具复制到 addons/agentkit/vfx/， 并将着色器和运行时脚本复制到 res://vfx/（它们会随游戏一起发布）。阅读 project.godot。 验收标准：文本中包含 3d/physics_engine="Jolt Physics" 和预期的 renderer/rendering_method；vfx_selftest.gd:compile 在 10 个脚本中报告 0 个错误（check_all 会跳过 addons/agentkit/）。
2. 在代码中按层级构建。 gd_vfx.build(P, "high"|"mobile"|"low") 会根据 vfx_recipes.gd 保存 explosion_、 impact_、fireball_、shot_ 和 burst_stage_<tier>.tscn。规格是字典（VB.emitter）； 曲线和渐变会转换为 CurveTexture 和 GradientTexture1D（当某个通道超过 1 时使用 HDR）；共享纹理 存放在 res://vfx/tex/*.tres 中（Brackeys 00:15:04：切勿嵌入）。验收标准：构建成功，未捕获到 错误。工具包层包括：fireball（拉伸的 SphereMesh 头部，带有 fx_fire_head、噪声减去渐变、HDR； 反向 Fresnel 的 fx_soft_core；由 INSTANCE_CUSTOM.y 驱动的世界空间侵蚀烟团，onetupthree N9ilhL8JFes 00:05:38； 速度火花；通过 fx_trail_follow 实现的轨迹和一个 OmniLight3D，两者在 low 层均关闭）；explosion （闪光、火焰、深度排序的烟雾、碰撞火花、Face-Y 光环、high 层带有 30 Hz 烟雾子发射器的碎片、灯光、 除 low 层外的焦痕 Decal）；fx_projectile（每个刻度都进行射线扫掠，在命中法线处产生冲击效果， 轨迹消失后释放自身）。
3. 静态审查。 gd_vfx.audit(P, scene, tier, level)。验收标准：匹配层级下有 0 个错误。 阅读警告，并逐一修复或记录。在 broken.tscn 上证明审查能捕获问题（21 项发现，4 个错误）。
4. 在上下文中适配 AABB。 gd_vfx.fit_aabb(P, "res://vfx/burst_stage_high.tscn", node="Explosion", play_method="Explosion:play", write=True, out=effect_scene)。 验收标准：每个发射器的 old_encloses_live 都为 true，时间轴的 aabb_check 未报告任何越界内容。
5. 按渲染器查看效果。 gd_vfx.timeline(P, scene, times=[0.03,0.1,0.2,0.35,0.6,1.0,1.5,2.2], renderer=..., trigger="none", extra={"play_method": "Explosion:play", "aabb_check": True})； 对于投射物，使用 extra={"hold": "Fireball"}。打开联系表。验收标准：没有全黑、全白或颜色均匀的标记。 目测确认：先出现闪光，火焰转为烟雾，没有突然闪现的效果，光环逐渐消失，火花在地面上弹跳， 焦痕保留，头部看起来像火焰，尾迹位于其后。
6. 回退方案。 对于 Compatibility，使用 low 层（无轨迹、贴花、灯光或子发射器），或者使用 gd_vfx.to_cpu 创建一个 CPUParticles3D 副本。验收标准：阅读 lost 列表（碰撞、子发射器、轨迹、 粒子着色器、烘焙到渐变中的 alpha_curve、对齐模式），并在 gl_compatibility 中渲染该副本。
7. 预算。 按层级运行 gd_vfx.overdraw(...)，并运行 gd_run.profile_scene(stress scene, size=(1280,720), driver="vulkan")。验收标准：p99 层数和 GPU p95 均在下方数值范围内，low 层的开销低于 high 层。
8. 行为。 运行 vfx_selftest.gd：lifecycle（生成 5 次后 节点数恢复到基线）、projectile（命中一次、生成爆炸效果、所有对象均已释放）和 juice（恢复 time_scale、震动幅度受限且最终归零）。验收标准：全部通过。

专家检查清单（在计划中明确列出）

• 交付内容包含完整代码：粘贴 vfx_recipes.gd 规格和 fx_fire_head.gdshader，不要只写说明；读者 可能没有该工具包。
• 重放使用 restart()，不要使用 emitting = true（文档）。
• 确定性帧：使用 use_fixed_seed，然后设置 speed_scale = 0，调用 restart()， 再调用 request_particles_process(t)。两次跳转到 0.4 s 的画面像素完全相同；不使用固定种子时， 差异为 0.50（P13）。
• 在一个系统中从火焰过渡到烟雾：使用预乘混合（BLEND_MODE_PREMULT_ALPHA，纹理导入时启用 Premultiply Alpha）：低 alpha 会叠加，高 alpha 会混合；使用黑色和 alpha 0 淡出（Brackeys 30:56 至 32:39）。在灰色背景上测量：alpha 0 会使背景变亮，alpha 1 会替换背景（P13）。
• 烟雾 LOD：fx_smoke_lod.gdshader 将黑到白的颜色渐变映射到单张噪声纹理的 mip 0 到 8，让烟团几乎不增加成本就能扩散； 颜色移至 uniform（Le Lu e_6ZA-xa_DQ 16:40 至 24:20）。三种渲染器上的细节扩散值都在生命周期内从 0.10 降至 0.0（P13）。
• 复制系统：Brackeys 所说的“Make Unique Recursive, but never the texture”在 4.7.2 中对应 duplicate(true)：嵌入的曲线会变为独立副本，外部 .tres 纹理仍保持共享（P13）。网格保持共享，材质放在 material_override 中（Brackeys 13:59 至 15:04）。
• Billboard 与方向：Align Y 会与 Billboard 冲突；使用 transform_align Z Billboard + Y to Velocity（Brackeys 27:07）。
• 分层透明对象闪烁：先偏移节点，再设置 sorting_offset（Brackeys 29:57）。
• TAA 残影：DRAW_ORDER_INDEX（3D 默认值）是唯一带有运动矢量的顺序；不透明粒子应保持此设置（文档）。
• 预处理会按预处理秒数运行着色器 fixed_fps 次，并可能导致 GPU 卡顿；绝不要用于一次性效果（文档，审查 preprocess_one_shot）。
• 靠近摄像机的四边形：distance_fade_mode Pixel Alpha 会按距离淡出，无需读取深度；邻近淡出则能柔化相交处。

数值

数值	相对于	来源
头部 HDR 颜色 (2, 1.3, 0.6)；火花 (2, 1.3, 0.5)；火花生命周期 0.3 s	发光阈值 1.0	Le Lu 00:08:05, 00:28:15
头部渲染优先级为 2，高于核心的 1；反转菲涅耳幂为 4 至 5	嵌套透明网格	Le Lu 00:18:25
冲击波：1 个粒子，0.4 至 0.5 s	单次爆发	Brackeys 00:18:34
隧道步长 = v_max / fixed_fps；fixed_fps 默认值为 30	最薄碰撞体	Godotneers 00:47:17, 文档
collision_base_size 默认值为 0.01 m	可见粒子大小	Godotneers 00:57:27
子级 amount 至少为父级数量 x 每事件计数（AT_END、AT_COLLISION、AT_START）；CONSTANT 模式：父级数量 x Hz x 子级生命周期	子发射器上限	Godotneers 00:44:48（每事件）；CONSTANT 根据 link_sub_emitter 推导 [新增]
sub_emitter_frequency 的单位为 Hz：在 1 m/s 时，点之间相距 1/f m	实测 4 和 10 Hz	实时 V10
每层过度绘制：0.070 线性亮度（Forward+、Mobile）；36.6/255 原始值（Compatibility，超过 6 后饱和）	DEBUG_DRAW_OVERDRAW PNG	实时 V11 [新增]
爆炸在 0.6 s 峰值时的 p99 层数：高 4.9 至 5.9，低 2.3 至 3.3（因种子而异）	约 5 m 处的 640x360 视图	实时 V11，3 次运行
GPU p95，1280x720，M5 Max 使用 Vulkan，机器与其他 Godot 作业共用：单独运行阶段为 1.0 至 2.3 ms；六个循环爆炸：高 3.4 至 4.0，移动档 2.1 至 2.7，低 1.2 ms	帧	实时 V12，3 次运行
粒子数量，爆炸 / 火球：高 208 / 57，移动 48 / 35，低 34 / 22	档位缩放 1.0 / 0.6 / 0.4	工具包 [新增]
命中停顿：0.05 时间缩放，持续 0.08 s；震动：创伤值为 1 时为 0.30 x 0.22 m，衰减速度 1.8/s	摄像机	[新增]，Mostly Mad 说明中的典型范围
烟雾渐变：Forward+ 下中灰约为 0.06 线性值；Compatibility 下为 x3.6	同一帧	实时 V5 [新增]

质量门槛

可衡量指标：

• 审计：该层级为 0 个错误。Kit 编译：0 个解析错误。项目文件包含 Jolt 和所选渲染器。
• AABB：每个发射器在所有捕获时间点的实时包围盒都位于 visibility_aabb 内。
• 生命周期：生成 N 次后，节点数量与基线一致；done 触发 N 次，且没有安全超时。
• Projectile：在预期时间触发一次 hit（14 m/s 的速度行进 12 m，需要 0.867 s，即第 52 帧），且树中不剩任何内容。
• Juice：单次停止和重叠停止后，Engine.time_scale 均为 1.0，且不会提前恢复；抖动偏移不超过最大值，并在结束时精确归零。
• 各层级的过度绘制 p99 和 GPU p95 均符合表格要求。兼容性日志显示预期警告，且无意外警告。

视觉效果（不超过 1600 px 的联系表；评分标准见 references/critique.md）：先闪光，再燃烧，最后冒烟；没有突变；在游戏距离下轮廓清晰可辨；光环渐隐；火花会反弹；轨迹跟随弹头；爆炸朝向表面法线；每个层级在其渲染器上都效果良好。

常见错误

错误	表现	修复
顶点颜色未启用	四边形呈白色，曲线被忽略	vertex_color_use_as_albedo
粒子广告牌未启用保留缩放	缩放曲线被忽略	billboard_keep_scale
轨迹未启用 use_particle_trails	变成零碎的平面片段	在轨迹网格材质上启用此项
子发射器数量低于上限	子发射器轨迹变稀疏	link_sub_emitter 会计算上限
使用默认的 8 m AABB	效果突然消失，碰撞停止	在关卡中使用 fit_aabb
collision_base_size 大于生成高度	碎片卡在原点（实测：移动 0.5 m，而非 10 到 12 m）	在碰撞体上方生成
将 amount_ratio 用作移动设备层级	没有节省	降低 amount
用 emitting = true 重新播放	单次效果有时会被跳过	使用 restart()（见文档）
命中时释放弹体	世界空间轨迹立即消失	停止发射器，等待轨迹消失后再释放
在视图深度排序中使用 convert_from_particles	出现 "Index p_order = 3 is out of bounds"，排序丢失	VB.to_cpu 会映射绘制顺序
所有渲染器都使用相同颜色	在 Compatibility 上烟雾接近黑色	在 Compatibility 上重新调整低层级
在 Metal 上进行性能分析	gpu_ms 为 0	driver="vulkan"

交接

• 接收来自 scenario-godot-gameplay 的命中事件（点、法线、池化），来自 scenario-godot-performance-export 的预算，以及来自 scenario-godot-rendering-lighting 的辉光和环境。
• 交付各层级的 res://vfx/*.tscn、res://vfx/shaders 和 runtime（fx_burst、 fx_projectile、Juice）、审计 JSON、图集、过度绘制和 GPU 表格。
• 请求 scenario-godot-shaders 提供新的表面着色器（溶解、水、扭曲），请求 scenario-godot-audio 提供命中音效，并请求 scenario-godot-2d 协助集成 2D 效果。

Godot 4.7 注意事项

• capture_aabb() 会按绘制网格的最长轴扩展边界，并忽略粒子缩放（4.7.2，实测）。
• CPUParticles3D.convert_from_particles 会将 draw_order 复制为原始整数，但枚举值不同：GPU 视图深度为 3，CPU 视图深度为 2。CPUParticles3D 没有 alpha_curve（4.7.2，实测）。
• Compatibility 会记录“Particle trails are only available when using the Forward+ or Mobile renderer”和“does not support particle sub-emitters”；贴花会在没有警告的情况下消失。
• 无头模式不会绘制任何内容，因此捕获需要在窗口化运行中进行。在 macOS 上，Metal 报告的 GPU 时间为 0；请使用 --rendering-driver vulkan。
• 自 4.4 起，Curve 会强制执行 min_value 和 max_value，因此对于大于 1 的缩放曲线，请扩大取值范围。AgX 在 4.4 中引入。Glow 默认值在 4.6 中变更（强度从 0.8 调至 0.3）：请重新调整较早的效果。
• 粒子着色器使用 start() 和 process()；Godot 3 中将 VELOCITY 写入 vertex() 的做法会报错。
• 尚未在 4.7.2 上运行粒子轨迹分段刷新错误（Octodemy，4.7 时代）以及 Godotneers 的 4.2 粒子轨迹和 SDF 错误。

参考资料

• references/procedures.md（P1 至 P13、调用、代码、实时结果）， expert-notes.md（带时间戳的原则），critique.md （评分标准），gui-paths.md（编辑器路径）， sources.md（来源和时间戳）。
• scripts/gd_vfx.py：安装、构建、审计、时间线、过度绘制、fit_aabb、 to_cpu、maths。
• scripts/agentkit/vfx/：vfx_build、vfx_recipes、vfx_audit、vfx_capture、 vfx_jobs、vfx_selftest；shaders/（包括 fx_smoke_lod）和 runtime/ 随游戏一同提供。