Scenario Godot Vfx

Godot VFX

Target: Godot 4.7.2.stable, macOS Apple Silicon.

Expert level here means effects built as layers of small systems, every silent particle failure caught by a script before anyone looks, and every claim about look or cost backed by frames captured at exact times and by measured overdraw and GPU time per renderer. The agent builds effects in code, renders them windowed, and looks at contact sheets. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-godot-expert (gd_env, gd_run, gd_review, AgentKit, GD_MAX slots, windowed vs headless).

Stance (the expert delta)

1. An effect is layers, and the head of a projectile is not particles. A projectile is head, tail and sparks; the head is a shader mesh with scrolling noise and HDR color above 1 (Le Lu 74XywaLGO5Q 00:00:34, 00:08:05). An explosion is flash, fire, smoke, sparks, debris, shockwave and light, each a small system made by duplicating a working one and changing a few values (Brackeys htRjt505sPg 00:02:30, 00:13:27). A one-particle system is fine for a shockwave ring (00:18:02).
2. Particle settings fail silently, so audit them in code. Color and alpha curves do nothing without vertex_color_use_as_albedo; scale curves do nothing on a particle billboard without billboard_keep_scale; trails need trail_enabled, a Ribbon or Tube trail mesh and use_particle_trails (Godotneers cZ5Ang_Ji8E 00:09:44, 00:32:54; Brackeys 00:23:44). A sub-emitter's own amount is a global cap (Godotneers yKoGuBGZatY 00:44:48) and its AABB is not inherited (cZ5Ang_Ji8E 01:06:19). vfx_audit.gd flags all of these.
3. visibility_aabb is both culling and the collision area (Godotneers cZ5Ang_Ji8E 00:45:28). Measure it rather than guessing: on 4.7.2, capture_aabb() pads particle positions by the draw mesh's longest axis and ignores per-particle scale (measured: Flash quad 2 m gave a 4 m box; a ring scaled to 4.5 m still gave 2 m) [added]. fit_aabb corrects for scale and must run inside the level, because debris without its colliders falls 8 m through the world.
4. Tier by renderer, never by amount_ratio. amount_ratio hides particles and saves nothing (GPUParticles3D docs; Bonkahe BUa-mKHEPUM 00:01:18). Lower amount per tier and drop the layers the renderer cannot draw. Compatibility drops decals with no warning, and logs warnings for trails and sub-emitters (measured) [added].
5. Particles do not touch physics. Gameplay hits come from a ray swept every physics tick; particle collision needs GPUParticlesCollision nodes, and the step per tick is speed / fixed_fps, with fixed_fps 30 by default (Godotneers cZ5Ang_Ji8E 00:44:23, 00:47:17).
6. Juice is code you can test. Hit-stop lowers Engine.time_scale and waits on a timer that ignores it, then restores 1.0 (Mostly Mad Jwv9t5zFlqI 00:00:32, 00:01:37). Shake comes from smooth noise with decay (Mostly Mad pG4KGyxQp40 00:00:39); trauma squared and a 3D camera offset are [added].
7. Judge frames, not the inspector. Render windowed with --fixed-fps 60, so frame k is t = k/60 s, at 0.03 to 2.2 s, and look at one contact sheet per renderer. Overdraw comes from DEBUG_DRAW_OVERDRAW with a measured per-layer calibration, and GPU time from the Vulkan driver (Metal reports 0 on macOS) [added].
8. A trail that follows a node is a particle shader trick. Pin the particle to EMISSION_TRANSFORM[3].xyz in start() and process(), with no forces (Octodemy iPCzOe-S9EQ 00:05:42).

Establish first

Workflow

1. Project and kit. Clone Base3D, gd_vfx.install(P) copies tooling to addons/agentkit/vfx/, and shaders and runtime scripts to res://vfx/ (they ship with the game). Read project.godot. GATE: 3d/physics_engine="Jolt Physics" and the intended renderer/rendering_method are present as text; vfx_selftest.gd:compile reports 0 errors over 10 scripts (check_all skips addons/agentkit/).
2. Build per tier in code. gd_vfx.build(P, "high"|"mobile"|"low") saves explosion_, impact_, fireball_, shot_ and burst_stage_<tier>.tscn from vfx_recipes.gd. Specs are dictionaries (VB.emitter); curves and ramps become CurveTexture and GradientTexture1D (HDR when a channel exceeds 1); shared textures live in res://vfx/tex/*.tres (Brackeys 00:15:04: never embed). GATE: build ok, no captured errors. Kit layers: fireball (stretched SphereMesh head with fx_fire_head, noise minus gradient, HDR; inverted-Fresnel fx_soft_core; world-space eroded puffs driven by INSTANCE_CUSTOM.y, onetupthree N9ilhL8JFes 00:05:38; velocity sparks; ribbon via fx_trail_follow and an OmniLight3D, both off on low); explosion (flash, fire, depth-sorted smoke, colliding sparks, Face-Y ring, debris with a 30 Hz smoke sub-emitter on high, light, scorch Decal except low); fx_projectile (ray swept every tick, impact on the hit normal, frees itself after its trail dies).
3. Static audit. gd_vfx.audit(P, scene, tier, level). GATE: 0 errors for the matching tier. Warnings are read and either fixed or written down. Prove the audit catches problems once on broken.tscn (21 findings, 4 errors).
4. Fit AABBs in context. gd_vfx.fit_aabb(P, "res://vfx/burst_stage_high.tscn", node="Explosion", play_method="Explosion:play", write=True, out=effect_scene). GATE: old_encloses_live true for every emitter, and the timeline aabb_check reports nothing outside.
5. Look at it, per renderer. 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}); for the projectile, extra={"hold": "Fireball"}. Open the contact sheet. GATE: no all-black, all-white or uniform flags. By eye: the flash reads first, fire turns to smoke, nothing pops, the ring fades, sparks bounce on the floor, the scorch stays, and the head reads as fire with its tail behind it.
6. Fallback. For Compatibility, use the low tier (no ribbon, decal, light or sub-emitter), or gd_vfx.to_cpu for a CPUParticles3D twin. GATE: read the lost list (collision, sub-emitters, trails, particle shaders, alpha_curve baked into the ramp, align mode) and render the twin in gl_compatibility.
7. Budget. gd_vfx.overdraw(...) per tier, and gd_run.profile_scene(stress scene, size=(1280,720), driver="vulkan"). GATE: p99 layers and GPU p95 inside the numbers below, low tier lighter than high.
8. Behavior. Run vfx_selftest.gd: lifecycle (node count back to baseline after 5 spawns), projectile (one hit, explosion spawned, everything freed) and juice (time_scale restored, shake bounded and back to 0). GATE: all ok.

Expert checklist (state these in the plan)

• Complete code in the deliverable: paste the vfx_recipes.gd specs and fx_fire_head.gdshader, not prose; readers may lack the kit.
• Replay with restart(), not emitting = true (docs).
• Deterministic frames: use_fixed_seed, then speed_scale = 0, restart(), request_particles_process(t). Two seeks to 0.4 s were pixel-identical; without a fixed seed they differed by 0.50 (P13).
• Fire into smoke in one system: premultiplied blend (BLEND_MODE_PREMULT_ALPHA, texture imported with Premultiply Alpha): low alpha adds, high alpha mixes; fade with black and alpha 0 (Brackeys 30:56 to 32:39). Measured over gray: alpha 0 brightened it, alpha 1 replaced it (P13).
• Smoke LOD: fx_smoke_lod.gdshader maps a black-to-white color ramp to mip 0 to 8 of one noise texture, so the puff diffuses almost free; color moves to a uniform (Le Lu e_6ZA-xa_DQ 16:40 to 24:20). Detail spread fell from 0.10 to 0.0 over life on all three renderers (P13).
• Duplicating a system: Brackeys' "Make Unique Recursive, but never the texture" is duplicate(true) in 4.7.2: embedded curves become unique, external .tres textures stay shared (P13). Keep the mesh shared and the material in material_override (Brackeys 13:59 to 15:04).
• Billboard plus direction: Align Y conflicts with billboards; use transform_align Z Billboard + Y to Velocity (Brackeys 27:07).
• Layered transparents flicker: offset the nodes first, then sorting_offset (Brackeys 29:57).
• TAA ghosting: DRAW_ORDER_INDEX (the 3D default) is the only order with motion vectors; keep it for opaque particles (docs).
• Preprocess runs the shader fixed_fps times per preprocessed second and can stall the GPU; never on one-shots (docs, audit preprocess_one_shot).
• Near-camera quads: distance_fade_mode Pixel Alpha fades by distance without a depth read; proximity fade softens intersections.