Add ambient GPU VFX system (spores, dust, embers, resin drips, glow pulses, market ambience) and scene/renderer integration

[ercmine]

Motivation

• Provide the engine's first practical ambient VFX layer to materially improve atmosphere for Perbug's stylized subterranean world.
• Deliver lightweight GPU-instanced particles and a few specialized primitives (drips, pulses) that integrate cleanly with the existing renderer, scene, and shader pipeline.
• Keep runtime costs and API surface practical for procedurally generated rooms while enabling deterministic tuning and profiling.

Description

• Added an engine-owned VFX subsystem engine/render/vfx.hpp/.cpp that exposes typed EffectDefinition templates, per-instance EffectState, deterministic core::Random seeding, CPU-side spawn/update simulation, and per-frame instanced FrameSubmission outputs. (new files: engine/render/vfx.hpp, engine/render/vfx.cpp).
• Implemented lightweight primitives and presets for spores, dust, embers, resin drips, glow pulses, and a composite market ambience preset, each with dedicated parameter groups (ParticleStyle, ResinDripStyle, GlowPulseStyle) and sensible defaults via make_*_definition helpers. (VFX behavior in vfx.cpp).
• GPU path: use existing shader pipeline and renderer instancing path (Renderer::submit_instanced) to draw quad sprites; CPU sim handles spawn/lifetime/drift and uploads instance transforms as packed 4x4 matrices per instance. (integration hooks in vfx.cpp and shell submission in engine/shell/main.cpp).
• Scene integration: added scene::VfxAttachmentComponent plus collect_visible_vfx_attachments so effects can attach to scene nodes and follow transforms; scene APIs to set/clear vfx attachments were added. (changes in engine/scene/scene.hpp/.cpp).
• Renderer & shader integration: added vfx/ambient_sprite shader family and manifest variants for spores/dust/embers/resin/glow; VFX programs are loaded via ShaderProgramLibrary and used by VFX submissions. (shaders/vfx/*, shaders/shaders.cmake).
• Diagnostics and debug: extended RendererDebugCounters and overlay text to report VFX active effects, particles, draw counts and instance upload counts; added a vfx-ambient-pass timing row in the shell. (changes in engine/render/debug_renderer.* and engine/shell/main.cpp).
• Documentation and validation: added docs/vfx.md and updated docs/rendering.md and engine/render/README.md describing architecture, CPU vs GPU responsibilities, pass placement, and current limits; added deterministic unit smoke tests and scene attachment assertions (tests/render/vfx_system_tests.cpp, updated tests/scene/scene_tests.cpp).

Testing

• Ran a repository hygiene check: git diff --check (no whitespace errors) — succeeded.
• Attempted CMake configure/build via cmake --preset linux-debug and -DRENDER_ALLOW_FETCHCONTENT=ON; configuration failed due to missing external dependencies (SDL3/bgfx) and blocked network fetch (CONNECT tunnel failed, response 403) in this environment, so compiled unit tests were not executed here — failed for environmental reasons.
• Added unit tests for VFX presets and scene VFX attachment visibility (render_vfx_system_tests, updated scene_tests), and wired them into CMake test targets; these tests are deterministic and should run in CI when dependencies/build succeed.

---

Codex Task