Lighting & Shadows - ReForge-MMD/ray-mmd-reforge GitHub Wiki

Lighting & Shadows

Ray-MMD ReForge combines physically based analytic light sources with cascaded shadow mapping and screen-space contact shadows.

1. Light Types

Light Type PMX Path Shader FX Path Use Case
Directional (Sun) Lighting/DirectionalLight/directional_light.pmx directional_lighting.fx Sun, moon, outdoor key light.
Point Light Lighting/PointLight/point_light.pmx point_lighting.fx Bulbs, fire, small omnidirectional sources.
Spot Light Lighting/SpotLight/spot_light.pmx spot_lighting.fx Flashlights, stage spotlights, lamps.
Tube Light Lighting/TubeLight/tube_light.pmx tube_lighting.fx Fluorescent tubes, neon rods, laser swords.
Sphere Light Lighting/SphereLight/sphere_light.pmx sphere_lighting.fx Large area diffuse lights, softboxes.

2. Setting Up Lights in MMD

  1. Load the respective .pmx from the Lighting/ directory.
  2. Open the MMEffect window -> LightMap tab:
    • Right-click the light model and assign the matching .fx shader.
  3. Position and rotate the light bone in MMD:
    • Bones: Control position and orientation.
    • Morph Sliders on Light Model: Adjust color (R/G/B), intensity (Range, Attenuation), and shadow softness.

3. Shadow Systems

Cascaded Shadow Maps (CSM) & Next-Gen PCSS Soft Shadows

  • Configured via SUN_SHADOW_QUALITY (default: 2 - 2048×2048) and SUN_SHADOW_PCSS in ray.conf.
  • Splits the camera frustum into up to 4 depth cascades, maintaining high shadow resolution near the camera while seamlessly covering distant landscapes.
  • Percentage-Closer Soft Shadows (PCSS) (Shader/Shadows/PCSS.fxsub):
    • Physically Based Contact-Hardening: Replaced legacy VSM with true contact-hardening PCSS. Dynamically evaluates blocker search depth and calculates penumbra softness based on occluder-to-receiver distance and the physical angular diameter of the sun (SUN_LIGHT_RADIUS = 0.015f / $0.53^\circ$).
    • Shadows cast near the contact base (feet touching ground, fingers against clothes) remain razor-sharp, while distant occluder shadows (tree foliage, outstretched arms) naturally diffuse into realistic soft penumbras.
    • Adaptive Close-Up Anti-Staircasing: Dynamically scales shadow depth bias and Poisson sampling at close range (lerp(1e-4, 5e-4, cascadeRatio)), completely eliminating macro staircasing, jagged shadow edges, and acne during extreme close-ups on character faces and bodies.
    • Seamless 4-Cascade Cross-Blending: Smooth analytical cascade boundary interpolation (CascadeCrossBlend) across all 4 orthogonal cascades, eliminating hard cutoff seams and popping when the camera orbits or zooms.
    • Cross-Bilateral Shadow Filtering (Shader/Shadows/ShadowBilateralBlur.fxsub): Edge-preserving cross-bilateral filter denoises Poisson jitter while strictly preserving crisp contact silhouettes along depth and surface normal discontinuities.
    • Castaño 4-Tap PCF 3x3 Filter (SUN_SHADOW_QUALITY 1): Ignacio Castaño's (2013) ultra-fast bilinear reconstruction filter delivers smooth, artifact-free shadows on lower-tier hardware without performance overhead.
    • Two-Sided Shadow Casting: Employs CullMode = NONE on shadow casters with G-buffer normal alignment, preventing light leaks on paper-thin geometry (hair bangs, ribbons, clothing skirts, leaves).

Screen-Space Contact Cone Tracing (SSCT) (Shader/Shadows/ContactShadow.fxsub)

  • Configured via CONTACT_SHADOW_QUALITY in ray.conf (1 to 3 steps).
  • Solves shadow detachment (peter-panning) with a short screen-space cone march towards the light source.
  • Key Features:
    • Expanding Cone Tracing: Raymarching radius expands dynamically with travel distance, simulating natural contact penumbra softening instead of a hard pixel line.
    • Distance Attenuation & Soft Falloff: Soft exponential falloff smoothly grounds characters without harsh geometric silhouettes.
    • Dual-Hemisphere Terminator Fade: Eliminates false wall / silhouette shadow detachment artifacts on curved surfaces.
    • Slope-Scaled Normal Bias: Completely prevents self-shadow acne on thin geometry.
  • Grounds characters and creates sharp sub-millimeter contact occlusion under eyelashes, nostrils, hair strands over the forehead, clothing creases, and shoes on the ground.

Screen-Space Global Shadows (SSGS)

  • Configured via SSGS_QUALITY in ray.conf (16 to 32 steps, up to 15m world range).
  • Long-range directional raymarched shadows toward the sun with distance-adaptive soft penumbra expansion, grounding characters and geometry independently of shadow map resolution.

4. Physical Volumetric Fog & Atmospheric Godrays (FogController.pmx)

Ray-MMD ReForge v1.22.0 introduces a comprehensive physical volumetric fog and atmospheric scattering engine (Shader/Fog/*), fully integrated into the deferred lighting pipeline. Configured via FOG_ENABLE in ray.conf:

  • 1 : Analytical Dual-Layer Exponential Height Fog (Ultra-fast closed-form solution for base atmosphere and ground mist).
  • 2 : Volumetric Fog + Godrays (16-step raymarching with cross-bilateral edge-preserving filtering).
  • 3 : Cinematic Volumetric Godrays (24-step raymarching for high-density light shafts).

Key Architectural Features

  • Closed-Form Dual-Layer Height Fog: Evaluates ground mist and sky haze independently with individual height falloffs and vertical base planes.
  • Sun Zenith-Coupled Godrays: Atmospheric light shafts automatically compute solar extinction and Mie scattering phase based on directional sun angle and Cascaded Shadow Maps (CSM).
  • Mist Turbulence & Wind Drift: 3D procedural noise creates rolling fog banks and wind-swept mist across the ground.
  • Cross-Bilateral Edge Denoising: Prevents slicing steps from showing against character hair and silhouettes.

FogController.pmx Morph Reference (42 Morphs)

Panel Tab Morph Sliders Description
Eyebrows (眉) FogDensity+/-, GroundDensity+/-, MaxOpacity+/- Overall atmospheric fog density, ground mist layer density, and maximum fog opacity clamp.
Eyes (目) FogR/G/B+/-, SunR/G/B+/-, SunIntensity+/-, MiePhase+/- Fog albedo color, directional sun scatter tint, godray brightness, and Mie forward scattering asymmetry.
Mouth (口) FogHeight+/-, HeightFalloff+/-, GroundHeight+/-, GroundFalloff+/-, StartDistance+/-, CutoffDistance+/- Base height altitudes, vertical thickness falloffs, and radial start/cutoff camera distances.
Other (他) Godrays+/-, RayDensity+/-, MistNoise+/-, WindSpeed+/- Direct godray shaft intensity, light shaft sample density, ground mist noise swirl, and wind animation speed.

5. Directional Water Caustics (CausticsController.pmx)

Ray-MMD ReForge features real-time screen-space directional water caustics (WATER_CAUSTICS_ENABLE 1 in ray.conf):

  • Back-projects scene depth points along the directional sun ray to the analytical water plane ($Y = \text{WATER_CAUSTICS_SURFACE_Y}$).
  • Computes analytical wave curvature and Jacobian flux concentration, creating sharp dynamic light ribbons on submerged surfaces, pool bottoms, and character skin underwater.
  • Includes chromatic dispersion across wave refraction wavelengths for iridescent caustic edges.
  • CausticsController.pmx Controls:
    • WaterHeight+ / WaterHeight-: Adjusts world-space water plane elevation ($Y$).
    • Caustics+ / Caustics-: Fine-tunes underwater light focus and brightness.
    • Speed+ / Speed- / Scale+: Modulates wave ripple frequency and scale.

6. Top-Down Sky Visibility & Macro Heightfield AO (Snowdrop Engine)

Ray-MMD ReForge introduces real-time directional sky visibility and heightfield macro ambient occlusion inspired by Ubisoft's Snowdrop Engine (GDC 2016):

The Problem It Solves

In standard MMD / Ray-MMD setups, environment IBL and ambient skylight diffuse uniformly illuminate all surfaces regardless of overhead geometry. Characters standing under canopies, roofs, bridges, porches, or inside open doorways suffer from severe ambient light leaking, glowing unnaturally in covered spaces.

  • The Crude Hack (EnvDiffLight-): Often attempted in the community, this morph acts as a global dimmer that kills sky diffuse lighting everywhere across the entire scene, plunging distant open-sky buildings and roads into flat, pitch-black darkness.
  • The Snowdrop Solution (SkyVisibility): Evaluates spatial overhead occlusion directly from scene depth using directional horizon search and cone tracing. Surfaces with clear sky exposure retain full vibrant daylight, while surfaces under overhead geometry receive realistic macro ambient shadowing.

Configuration (ray.conf)

// Top-Down Sky Visibility / Heightfield Ambient Occlusion (Snowdrop Engine / GDC 2016)
// 0 : Disabled
// 1 : Enabled (Fast 4-direction horizon search)
// 2 : Enabled (Cinematic 8-direction cone-tracing)
#define SKY_VISIBILITY_ENABLE 2

Dedicated Controller (SkyVisibilityController.pmx)

Load SkyVisibilityController.pmx into your scene to dynamically balance sky occlusion:

  • Intensity+ / Intensity- (alias: SkyVis+ / SkyVis-): Amplifies macro sky occlusion up to 3× or attenuates it down to 0.
  • Radius+ / Radius-: Modulates the overhead occluder search footprint (up to 2.5× wider or 0.25× narrower; coverage extends up to 400 world units with seamless distance falloff).
  • Floor+ / Floor-: Raises minimum ambient floor up to 0.6 or drops it to 0.0 to allow pitch-black occlusion in deep tunnels and interior rooms.
  • Contrast+ / Contrast-: Adjusts the occlusion power curve exponent (up to 2.5× sharper or 0.4× softer).
  • Position (Center Bone): World-space bone allowing you to explicitly anchor the 400-unit heightfield map center over any character, vehicle, or point of interest.

7. Screen-Space Reflections — Per-Material Mask Tabs

Ray-MMD ReForge exposes four SSR masks as dedicated MME render-target tabs (visible when ray_controller.pmx is selected in the MMEffect panel). Each mask is scoped to its own tab, so assignments never conflict:

Tab (RT) Controls Default Preset files
SSRMap How much a material reflects (receiver side) 1.0 Shadow/SSR visibility 0.0–1.0.fx
SSRReflectMap How strongly a material appears in other materials' reflections (source side) 1.0 Shadow/SSR reflect visibility 0.0–1.0.fx
SSRSelfMap Self-reflection suppression: flagged materials never bounce SSR between each other 0.0 Shadow/SSR self visibility 0.0–1.0.fx
SSRBlurMap Receiver blur override: selective roughness/blur boost per subset/material 0.0 Shadow/SSR blur 0.0–1.0.fx

How to Use

  1. Open the MMEffect window and select ray_controller.pmx (the object carrying ray.fx).
  2. Switch to the mask tab you need (SSRMap, SSRReflectMap, SSRSelfMap, or SSRBlurMap).
  3. Expand your model in the object tree and select the target materials (Ctrl+click for multi-select).
  4. Right-click and assign the matching preset, e.g. Shadow/SSR self visibility 1.0.fx or Shadow/SSR blur 1.0.fx.

Materials without a manual assignment keep the default routed preset, so nothing needs to be attached for standard behavior.

Typical Recipes

  • Face close-up self-smudging: assign SSR self visibility 1.0.fx to the skin and hair materials on the SSRSelfMap tab. They stop reflecting each other and themselves, but keep reflecting the floor, sky and unflagged objects — and remain fully visible in those objects' reflections.
  • Hide an object from mirror reflections only: assign SSR reflect visibility 0.0.fx on the SSRReflectMap tab; the object still reflects its surroundings normally.
  • Dull a material's own reflectivity: assign a partial SSR visibility N.fx on the SSRMap tab.
  • Per-material reflection roughness boost (frosted glass, satin metals, worn surfaces): assign SSR blur 1.0.fx (or intermediate 0.1–0.9) on the SSRBlurMap tab to selectively blur SSR reflections on specific model subsets without having to edit the underlying PBR smoothness map.

All four masks are preset-driven constants (nothing is clipped), so partial values (0.1–0.9) give proportional control and work on additive and semi-transparent materials alike.

Disabled (CONTACT_SHADOW_QUALITY 0) Enabled (CONTACT_SHADOW_QUALITY 2) Debug Raymarch Buffer
Contact Shadows Off Contact Shadows On Contact Shadows Debug