Native Post-Processing Shaders, Advanced Lighting & Physics3D Joints

[Carrotstudio0]

Summary

This PR adds several new native systems to GDevelop's 3D engine. The core additions are fully integrated and production-ready. The Physics3D joints/ragdoll system is also included but can be dropped from this PR if the team prefers to keep the scope focused — the lighting and shader systems are the more complete and tested part of this work.

---

What Was Added

New Effects Overview

System	Effect	Registered As	Status
Post-Processing	Chromatic Aberration	Scene3D::ChromaticAberration	Ready
Post-Processing	Color Grading	Scene3D::ColorGrading	Ready
Post-Processing	Tone Mapping	Scene3D::ToneMapping	Ready
Post-Processing	Screen-Space Reflections	Scene3D::ScreenSpaceReflections (SSR)	Ready
Post-Processing	Depth of Field	Scene3D::DepthOfField (DOF)	Ready
Post-Processing	Volumetric Fog	Scene3D::VolumetricFog (FOG)	Ready
Post-Processing	SSAO	Scene3D::SSAO	Ready
Lighting	Rim Light	Scene3D::RimLight	Ready
Lighting	Flickering Light behavior	Scene3D::FlickeringLight	Ready
Lighting	CSM Shadows + Stabilization	DirectionalLight upgrade	Ready
Lighting	Light Bounce (physics-aware)	PointLight / SpotLight	Ready
Physics3D	PulleyJoint	Physics3D::PulleyJoint	Included — droppable
Physics3D	Advanced Joint Controls	Motors / Springs / Break thresholds	Included — droppable
Physics3D	Ragdoll System + Humanoid builder	Jolt behavior extension	Included — droppable

Note: If the joints/ragdoll system is not yet practical to merge, it can be excluded from this PR entirely. The lighting and shader effects are self-contained and have no dependency on the Physics3D additions.

---

Shader Architecture (SSAO, SSR, DOF, Volumetric Fog and more )

All four screen-space effects share the same consistent pattern:

Structure of each shader:

• An independent ShaderPass per effect — no coupling between passes.
• A minimal vertex shader (fullscreen pass-through) that forwards UV coordinates.
• A fragment shader that reads:
  • tDiffuse — current rendered scene color
  • tDepth — scene depth buffer
  • resolution + camera matrices (primarily projectionMatrixInverse)
• All computation is fully screen-space. No geometry, materials, or object data is modified.

How they are registered in the engine:

1. Each effect is registered via gdjs.PixiFiltersTools.registerFilterCreator('Scene3D::...').
2. Declared in JsExtension as official effects with user-configurable properties.
3. On enable: addPostProcessingPass(shaderPass).
4. On disable: removePostProcessingPass(shaderPass).
5. Each frame: updatePreRender updates all uniforms.

---

Why There Are No Conflicts Between Effects

The pipeline is designed so all effects can be active simultaneously without interference:

1. PostProcessingSharedResources provides a single unified color + depth capture per layer, rather than each effect rendering independently. This is the key reason stacking multiple effects is safe.
2. State is stored using WeakMap keyed by renderer, so each layer's state is fully isolated.
3. Pass order is fixed and managed: SSAO -> RIM -> DOF -> SSR -> FOG -> BLOOM — no ordering conflicts and no unexpected compositing results.
4. Each pass has a unique ID. Re-ordering operates only on managed passes, not the full pipeline.
5. Each effect owns its own state and uniforms. No mutable state is shared directly between effects.

---

Why There Are No Conflicts With Existing Engine Systems

1. All shader work runs after the scene render as a post-process — physics, gameplay, collisions, and behaviors are completely untouched.
2. Effects only read from the scene (depth buffer, color buffer, light data). They do not write to or modify any object, behavior, or runtime state.
3. Safety guards are in place:
   • If THREE is not available, an EmptyFilter is returned instead of throwing.
   • If the target is not a valid Layer or the stack is locked, the pass disables safely.
4. All configurable values (radius, samples, intensity, etc.) are clamped to valid ranges to prevent unstable or undefined shader behavior.

---

Lighting Changes

DirectionalLight — CSM + Stabilization

The existing Scene3D::DirectionalLight was upgraded with:

• 3 shadow cascades replacing the single shadow map, with cascadeSplitLambda controlling split distribution.
• Per-cascade quality levels (near = high detail, far = soft shadows).
• Shadow stabilization via texel-grid snapping in light-space — eliminates shadow swimming during camera movement.
• Two anchor modes: shadowFollowCamera true/false.
• Shadow map size updated to support up to 4096 on high-end GPUs.

New parameters: maxShadowDistance, cascadeSplitLambda, shadowMapSize, shadowFollowLead, shadowFollowCamera.

SpotLight & PointLight

• Both lights now accept an origin object (position follows the object) and a target object (direction auto-aims at target every frame).
• Added a light bounce system: PointLight and SpotLight detect physics-enabled objects within range and calculate reflected light contribution based on surface normals and material properties.

Flickering Light Behavior

New behavior attachable to PointLight or SpotLight. Parameters: baseIntensity, flickerSpeed, flickerStrength, failChance, offDuration. Uses a sine + noise signal, writing intensity via updateDoubleParameter.

Rim Light

New Scene3D::RimLight effect for cinematic character separation. Controllable color, intensity, and falloff.

---

Physics3D (Jolt) — Optional / Droppable

As noted above, this can be excluded if not ready to review. Included:

• Physics3D::PulleyJoint — rope-over-pulley constraint with ratio and totalLength.
• Advanced joint controls: Motors, Limits, Springs, Friction, Solver overrides, Break thresholds (SetJointBreakThresholds / ClearJointBreakThresholds), Reaction force/torque monitoring.
• Full Ragdoll system with states (Active, Limp, Stiff, Frozen), group controls, humanoid templates (BuildHumanoidRagdoll, BuildHumanoidRagdollFromTag), and a built-in GUI.

---

Files Modified / Added

• Extensions/3D/ChromaticAberrationEffect.ts
• Extensions/3D/ColorGradingEffect.ts
• Extensions/3D/ToneMappingEffect.ts
• Extensions/3D/ScreenSpaceReflectionsEffect.ts
• Extensions/3D/DepthOfFieldEffect.ts
• Extensions/3D/VolumetricFogEffect.ts
• Extensions/3D/SSAOEffect.ts
• Extensions/3D/RimLightEffect.ts
• Extensions/3D/FlickeringLightBehavior.ts
• Extensions/3D/DirectionalLight.ts (modified — CSM upgrade)
• Extensions/3D/JsExtension.js (modified — effect registrations)
• Extensions/Physics3DBehavior/Physics3DRuntimeBehavior.ts (modified)
• Extensions/Physics3DBehavior/JsExtension.js (modified)