Configuration Guide (ray.conf) - ReForge-MMD/ray-mmd-reforge GitHub Wiki

Configuration Guide (ray.conf)

ray.conf is the master configuration file located in the root directory of Ray-MMD ReForge. It controls the engine's core features, shader compilation passes, quality presets, and default tonemappers.

In v1.21.0+, ray.conf is organized into 11 domain sections with an indexed Table of Contents:

  1. 01. SUN & DIRECTIONAL LIGHTING (SUN_LIGHT_ENABLE, SUN_SPECULAR_DISK_ENABLE, SUN_BACKLIGHT_TRANSLUCENCY)
  2. 02. SHADOWS & CONTACT SHADOWS (SUN_SHADOW_QUALITY, SUN_SHADOW_PCSS, SUN_LIGHT_RADIUS, SUN_SHADOW_BLUR, CONTACT_SHADOW_QUALITY, SSGS_QUALITY)
  3. 03. ENVIRONMENT & ATMOSPHERE (IBL_QUALITY, FOG_ENABLE, MULTI_LIGHT_ENABLE, VOLUMETRIC_FOG_ENABLE)
  4. 04. BRDF & MATERIAL MODELS (DIFFUSE_BRDF_TYPE, BRDF_FRESNEL_TYPE, BRDF_CLOTH_VIS_CHARLIE)
  5. 05. SKIN & SUBSURFACE SCATTERING (SKIN_BACKLIT_*, SKIN_SPEC_*, SSSS_QUALITY, SSSS_TEXSPACE)
  6. 06. TOON & STYLIZATION (TOON_ENABLE, TOON_DIFFUSE_RAMP_STEPS, TOON_OUTLINE_*)
  7. 07. AMBIENT OCCLUSION (SSAO_TYPE, SSDO_QUALITY, AO_TEMPORAL_DENOISE, SKY_VISIBILITY_ENABLE)
  8. 08. REFLECTIONS & REFRACTION (SSR_QUALITY, SSR_DEBUG, GLASS_REFRACTION, WATER_CAUSTICS_ENABLE)
  9. 09. GLOBAL ILLUMINATION (GI_ENABLE, GI_QUALITY, SSPT_*, SSGI_SPECULAR_GI)
  10. 10. OPTICAL & CAMERA EFFECTS (BOKEH_QUALITY, HDR_BLOOM_*, FILMIC_HALATION_MODE, HDR_STAR_MODE)
  11. 11. FINAL COLOR & POST-PROCESSING (HDR_TONEMAP_OPERATOR, AA_QUALITY, POST_SHARPEN_ENABLE, FILM_GRAIN_*)

1. Global Illumination (SSPT / RTGI & SSGI 3.0)

// Global Illumination (Screen-Space Raytraced GI)
// 0 : Disabled
// 1 : Accent    // Clean, focused local contact bounces & emissive glow
// 2 : Indirect  // UE5-style Multi-Bounce Global Illumination & ambient room radiance
// 3 : RTGI      // qUINT-style Screen-Space Path Tracing (SSPT) & multi-bounce irradiance (Default)
#define GI_ENABLE 3

// GI Quality (Unified ray count and step presets for both SSGI and SSPT)
// 1 : Low       (Ray Steps: 12; Ray Count: 4)  - Fast preview, minimum performance cost
// 2 : Medium    (Ray Steps: 12; Ray Count: 8)  - Balanced real-time viewport performance
// 3 : High      (Ray Steps: 14; Ray Count: 12) - Rich indirect bounce for complex scenes
// 4 : Cinematic (Ray Steps: 16; Ray Count: 16) - Maximum fidelity for high-resolution renders
#define GI_QUALITY 1

// SSPT / RTGI Specific Parameters (Active when GI_ENABLE == 3)
// Maximum path-tracing ray search distance in world space units
#define SSPT_SAMPLE_RADIUS 16.0f

// Geometry Z-thickness threshold: eliminates light leaking through thin walls, hair, fingers
#define SSPT_Z_THICKNESS 1.0f

// Indirect lighting bounce intensity multiplier
#define SSPT_IL_AMOUNT 2.0f

// Ambient occlusion intensity power curve
#define SSPT_AO_AMOUNT 1.0f

// Direct solar shadow retention factor: prevents SSPT from overriding shadows from ShadowMap.fxsub
// 0.0 : Deep shadows fully protected (no GI penetration into direct sun shadow)
// 0.4 : Balanced cinematic (distinct shadows with rich path-traced color bounce)
// 1.0 : Unconstrained (full GI in shadows)
#define SSPT_SHADOW_RETENTION 0.40f

// Multi-bounce indirect reflection feedback (0: off, 1: on)
#define SSPT_BOUNCES 1

// Weight of secondary bounce feedback
#define SSPT_BOUNCE_WEIGHT 0.35f

// Sensitivity of the À-Trous cross-bilateral wavelet edge-preserving denoiser
#define SSPT_FILTER_SENSITIVITY 1.0f

// Specular GI: reuses the denoised GI radiance as a local indirect specular term (Fresnel-weighted).
// Fills colored indirect reflections on rough surfaces where mirror SSR misses and the IBL cubemap is too blurry.
// 0 : Disabled
// 1 : Enable
#define SSGI_SPECULAR_GI 1
  • GI_ENABLE 3 (RTGI - Default): Full Screen-Space Path Tracing inspired by Marty McFly's qUINT RTGI. Employs golden spiral Monte Carlo sampling, progressive quadratic stepping, thickness gating, secondary bounce feedback, escaped ray sky radiance, and dielectric glass bypass.
  • GI_ENABLE 2 (Indirect): UE5 Lumen-style 3D hemisphere raymarching with wide diffuse bouncing across the environment.
  • GI_ENABLE 1 (Accent): Focused local contact micro-bounces and emissive neon glow with strict angle gating.
  • GI_QUALITY: Configures unified ray count and step density. Level 1–2 is recommended for interactive viewport playback; Level 3–4 is recommended for final offline video export.
  • SSPT_SHADOW_RETENTION 0.40f: Direct solar shadow retention factor. Gates indirect diffuse and specular GI against ShadowMapSamp with a quadratic penumbra response curve, keeping cast shadows deep and distinct without losing rich color bleeding.
  • SSGI_SPECULAR_GI 1: Fills colored indirect reflections on rough surfaces where mirror SSR misses and the IBL cubemap is too blurry. Includes subtle specular sheen on skin (0.25f), while automatically disabled for glass and emissive materials.

2. Ambient Occlusion & Directional Occlusion

// Method for Ambient Occlusion
// 0 : SSAO / SSDO (Original Ray-MMD)
// 1 : HBSSDO (Horizon-Based Screen-Space Directional Occlusion, Reforge Edition)
// 2 : GTAO (Ground-Truth Ambient Occlusion + GTSO, Jimenez / Activision)
#define SSAO_TYPE 2

// Screen Space Directional Occlusion Samples
// 0 : None
// 1 :  8 samples
// 2 : 12 samples
// 3 : 16 samples
// 4 : 20 samples
// 5 : 24 samples
// 6 : 28 samples
#define SSDO_QUALITY 6

// Temporal Denoising for Ambient Occlusion (HBAO / SSDO / GTAO)
// Reprojects ambient occlusion history across frames to eliminate micro-shimmering
// 0 : Disabled
// 1 : Enabled (Rock-solid stabilized contact occlusion)
#define AO_TEMPORAL_DENOISE 1

// Top-Down Sky Visibility / Heightfield Ambient Occlusion (Snowdrop Engine / GDC 2016)
// Captures long-range macro ambient occlusion from large overhead structures (bridges, roofs, canopies, tunnels)
// preventing outdoor skylight / ambient IBL from leaking into covered spaces.
// 0 : Disabled
// 1 : Enabled (Fast 4-direction horizon search)
// 2 : Enabled (Cinematic 8-direction cone-tracing)
#define SKY_VISIBILITY_ENABLE 2
  • SSAO_TYPE 2 (GTAO): Upgraded to reference XeGTAO architecture with cosine horizon integration and Jimenez multi-bounce color approximation.
  • AO_TEMPORAL_DENOISE 1: Stabilizes occlusion by accumulating temporal history across frames using view-projection reprojection and 3x3 neighborhood box clamping.
  • SKY_VISIBILITY_ENABLE: Snowdrop Engine heightfield macro occlusion. Level 1 provides high-performance 4-direction horizon testing; Level 2 provides 8-direction cinematic cone tracing. Controlled dynamically in MMD via SkyVisibilityController.pmx.

3. Screen Space Reflections (SIMD Vectorized SSRT) & Refraction

// Screen Space Reflection (SSRT ray-marching with SIMD batching)
// High-performance screen-space ray tracing using vectorized linear SIMD marching.
// Uses SIMD 4-sample texture batching, dynamic slope-based tolerance, and sub-texel precision.
// The value controls the ray sample budget:
// 0 : Disabled
// 1 : Low    (128 steps, 32 SIMD batches)
// 2 : Medium (256 steps, 64 SIMD batches)
// 3 : High   (384 steps, 96 SIMD batches)
// 4 : Ultra  (512 steps, 128 SIMD batches, cinematic fidelity)
#define SSR_QUALITY 2

// SSR debug overlay: diagnostic visualization of the SSR pass.
// Requires SSRDebugController.pmx loaded in the scene.
// 0 : Disabled (normal rendering)
// 1 : Enabled (compile the debug modes in)
#define SSR_DEBUG 0

// Screen-Space Refraction for glass & water materials (SHADINGMODELID_GLASS).
// Traces the refracted ray using Newton's root-finding method (Mayer et al. 2026)
// to find the true 3D background intersection instead of a flat screen offset.
// 0 : Disabled (flat screen-offset refraction)
// 1 : Enable (Newton's Method)
#define GLASS_REFRACTION 1
  • SSR_QUALITY: Vectorized linear screen-space ray tracing with SIMD 4-sample texture batching and slope-adaptive depth tolerance. Eliminates GPU warp divergence while ensuring high-precision contact grounding and far reflections at stable 60+ FPS.
  • SSR_DEBUG 1: Diagnostic visualization overlay controlled via SSRDebugController.pmx (supports Trace raymarch step analysis, Confidence heatmap, Distance visualization, Surface Normals, and Material Roughness).
  • GLASS_REFRACTION 1: Traces refracted rays directly against native G-buffer depth using Mayer et al. (2026) Newton's method root-finding in 3–4 iterations with wavelength chromatic dispersion.

4. Diffuse BRDF Model, Specular Softening & Subsurface Scattering

// Diffuse BRDF Model
// 0 : Disney / Burley (Empirical diffuse retroreflection)
// 1 : EON (Energy-preserving Oren-Nayar, Portsmouth et al. JCGT 2025)
#define DIFFUSE_BRDF_TYPE 1

// Specular highlight softening / geometric anti-aliasing (SphereMaxNoH, de Carpentier 2017)
// 0    : Disabled (exact analytic half-vector)
// 0.05 : Subtle AA of highlight edges (recommended for screenshots)
#define SPEC_LIGHT_SIN_ALPHA 0

// Fresnel kernel for GGX speculars
// 0 : Schlick (classic, default)
// 1 : Adobe F82 (Kutz et al. 2021 - preserves hue variation of colored speculars)
#define BRDF_FRESNEL_TYPE 1

// Cloth sheen visibility model (Cloth / microfiber materials)
// 0 : Neubelt / Pettineo approximation (cheap, default)
// 1 : Full Estevez & Kulla 2017 exponential fit
#define BRDF_CLOTH_VIS_CHARLIE 1

// Screen Space Subsurface Scattering
// 0 : None
// 1 : Enable
#define SSSS_QUALITY 1

// Texture-space SSS diffusion for opaque skin (SSSS_QUALITY required).
// Convolves direct irradiance in model UV space, eliminating distance scaling & silhouette bleeding
// 0 : Screen-space separable SSSS (baseline)
// 1 : Texture-space diffusion (opaque skin)
#define SSSS_TEXSPACE 1

// Authorable Skin / SSS Knobs
#define SKIN_BACKLIT_STRENGTH 0      // Henyey-Greenstein backlit glow (0: off, ~1: subtle, ~3: rim)
#define SKIN_BACKLIT_G        0.76   // Forward scattering anisotropy
#define SKIN_BACKLIT_IOR      1.4    // Skin index of refraction
#define SKIN_SPEC_LOBE0_SCALE 1.15   // Broad dermal lobe scale
#define SKIN_SPEC_LOBE0_ADD   0.05   // Broad dermal lobe roughness add
#define SKIN_SPEC_LOBE1_SCALE 0.35   // Tight epidermal lobe scale
#define SKIN_SPEC_LOBE1_ADD   0.02   // Tight epidermal lobe roughness add
#define SKIN_SPEC_LOBE0_MIX   0.70   // Dermal/epidermal mix (70/30)
#define SKIN_SPEC_LOBE1_MIX   0.30
#define SKIN_SSS_MFP_SCALE    1.0    // Global SSS mean-free-path multiplier
  • DIFFUSE_BRDF_TYPE 1 (EON): Portsmouth, Kutz & Hill (JCGT 2025) energy-preserving diffuse BRDF preserving bounce energy across high roughness angles.
  • BRDF_FRESNEL_TYPE 1 (Adobe F82): Preserves colored specular highlights across mid-angles without washing out.
  • SSSS_TEXSPACE 1: Texture-space UV irradiance diffusion for opaque skin, eliminating screen-space distance variance and silhouette halo bleeding into hair/background.
  • Unified UE Skin Pipeline: Runs the UE artist cheat toolchain (WrappedDiffuse, BackScatter, InScatter, Beer-Lambert HSV transmission, backlit glow). Pre-integrated LUT and Penner paths are completely removed.

5. Shadow Quality, PCSS Soft Shadows & Water Caustics

// Sun Cascaded Shadow Map Quality
// 0 : Disabled
// 1 : Low       (1024x1024)
// 2 : Medium    (2048x2048) (Default)
// 3 : High      (4096x4096)
// 4 : Cinematic (8192x8192)
#define SUN_SHADOW_QUALITY 2

// Percentage-Closer Soft Shadows (PCSS) for Sun Light
// Physically based contact-hardening soft shadows with blocker search & penumbra estimation.
// 0 : Uniform Soft Shadows (High-Quality Poisson PCF)
// 1 : Contact-Hardening PCSS (Sharp contact, physically expanding penumbra)
#define SUN_SHADOW_PCSS 1

// Physical Angular Sun Diameter (determines penumbra softness in PCSS)
// 0.005 : Sharp direct sun
// 0.015 : Natural earth sun (~0.53° angular diameter, default)
// 0.030 : Soft overcast / hazy sun
#define SUN_LIGHT_RADIUS 0.015f

// Edge-preserving cross-bilateral filter for soft penumbra denoising
// 0 : Disabled
// 1 : Enabled
#define SUN_SHADOW_BLUR 1

// Contact Shadows (Screen-Space Contact Shadows)
// 0 : Disabled
// 1 : Low    ( 8 steps)
// 2 : Medium (12 steps)
// 3 : High   (16 steps)
#define CONTACT_SHADOW_QUALITY 3

// Screen-Space Global Shadows (SSGS)
// 0 : Disabled
// 1 : Low    (16 steps, ~3m range)
// 2 : Medium (24 steps, ~8m range)
// 3 : High   (32 steps, ~15m range)
#define SSGS_QUALITY 3

// Screen-Space Directional Water Caustics
// 0 : Disabled
// 1 : Enabled
#define WATER_CAUSTICS_ENABLE 1
  • SUN_SHADOW_QUALITY 2: Defaults to Medium (2048×2048 per cascade) for balanced, high-FPS viewport performance while keeping PCSS filtering crisp. Level 1 employs Castaño (2013) 4-tap PCF 3x3 filtering for ultra-fast performance.
  • SUN_SHADOW_PCSS 1 & SUN_LIGHT_RADIUS 0.015f: True physically based contact-hardening soft shadows with adaptive Poisson blocker search, penumbra dilation, dynamic close-up anti-staircasing, and seamless 4-cascade cross-blending.
  • SUN_SHADOW_BLUR 1: Cross-bilateral shadow edge filter denoises Poisson jitter while preserving sharp silhouettes.
  • CONTACT_SHADOW_QUALITY 3: Screen-Space Contact Cone Tracing (SSCT) grounding characters with expanding cone penumbra and soft distance falloff under feet, clothes, and facial contours.
  • WATER_CAUSTICS_ENABLE: Directional wave curvature caustics on submerged surfaces with CausticsController.pmx.

6. Volumetric Fog & Atmospheric Godrays

// Volumetric Fog & Atmospheric Godrays (ReForge)
// 0 : Disabled
// 1 : Analytical Dual-Layer Exponential Height Fog (UE5/Filament, ultra-fast closed-form)
// 2 : Volumetric Fog + Godrays (16-step raymarching + cross-bilateral filter)
// 3 : Cinematic Volumetric Godrays (24-step raymarching + cross-bilateral filter)
#define FOG_ENABLE 2
  • FOG_ENABLE 1: Closed-form dual-layer exponential fog model calculating ground mist and atmospheric haze with zero raymarching overhead.
  • FOG_ENABLE 2 / 3: Physically raymarched volumetric godrays coupled to directional sun zenith angle and Cascaded Shadow Maps (CSM), featuring Henyey-Greenstein forward phase scattering, 3D procedural mist turbulence noise, and cross-bilateral edge-preserving filtering. Controlled dynamically via FogController.pmx.

7. HDR Tonemapping Operators

// Tonemap Operator
// 0 : Linear       (None / Unmapped)
// 1 : Reinhard     (Luminance-preserving Reinhard)
// 2 : Hable        (Uncharted 2 Filmic Curve, White Point = 4)
// 3 : Uncharted2   (Extended Range Filmic Curve, White Point = 8)
// 4 : Hejl 2015    (Modern Film Curve without toe desaturation)
// 5 : ACES-sRGB    (Standard ACES fit by Krzysztof Narkowicz)
// 6 : Naughty Dog  (Cinematic Tone Curve)
// 7 : ACES-Fitted  (Stephen Hill exact ACES RRT/ODT fit without hue shifting)
// 8 : AgX Base     (Blender 4.0 standard filmic curve by Troy Sobotka - pure highlights)
// 9 : AgX Punchy   (Blender 4.0 / Troy Sobotka Punchy look - vibrant & high contrast)
// 10: PBR Neutral  (Khronos Group 2024 - preserves exact material albedo and skin tones)
// 11: GT7          (Gran Turismo 7 SIGGRAPH 2025 - physically based curve by Polyphony Digital)
// 12: AgX Golden   (Filmic warm golden cinematography look)
#define HDR_TONEMAP_OPERATOR 8

8. Camera Optics & Post-Processing

// Spectral / Chromatic Dispersion Bloom
// 0 : None
// 1 : Subtle Cinematic Fringe
// 2 : Anamorphic Spectral Fringe
// 3 : Strong Sci-Fi Prism Bloom
#define HDR_BLOOM_SPECTRAL_MODE 1

// Filmic Halation (Film Emulsion Red-Orange Highlight Bleed)
// 0 : None
// 1 : Subtle 35mm Cine Halation // warm Kodak Vision3 emulsion glow
// 2 : Rich Vintage Film Halation
#define FILMIC_HALATION_MODE 1

// Anamorphic Lens Flare
// 0 : None
// 1 : Panavision Anamorphic Flare Profile (Default)
// 2 : Multi-Streak Star Flare
#define HDR_STAR_MODE 1

// Camera Motion Blur (Screen-Space Velocity Blur)
// 0 : Disabled
// 1 : Camera Velocity Only
// 2 : Camera + Object Velocity (VelocityMap)
#define POST_MOTION_BLUR_ENABLE 0

// Anti-Aliasing Mode
// 0 : None (Disabled)
// 1 : FXAA HQ (Nvidia FXAA 3.11 12-sample with 0.75 subpixel filter, fastest, great for thin lines)
// 2 : SMAA Medium (Color Edge Detection, 16 search steps, dual-axis blend)
// 3 : SMAA High (Color Edge Detection, 24 search steps, dual-axis blend, 0.35 subpixel filter)
// 4 : SMAA Ultra (True Jimenez 1x Ultra, 32 search steps, dual-axis blend, 0.50 subpixel reconstruction)
// 5 : SMAA Ultra+ (Depth-predicated G-Buffer silhouettes + 32 search steps + dual-axis + 0.65 subpixel reconstruction) (Default)
// 6 : TAA (Temporal AA with Catmull-Rom history filter, best for static/smooth animations)
// 7 : G-DLAA (Hybrid Geometric & Directional AA, preserves fine texture details)
#define AA_QUALITY 5

// Contrast Adaptive Sharpening (AMD FidelityFX CAS)
// 0 : Disabled
// 1 : Enabled
#define POST_SHARPEN_ENABLE 1
#define POST_SHARPEN_INTENSITY 0.5 // 0.0 = minimal, 0.5 = balanced default, 1.0 = maximum sharp

// Cinematic Film Grain (Applied after sharpening to hide 8-bit banding)
// 0 : Disabled
// 1 : Enabled
#define FILM_GRAIN_ENABLE 0
#define FILM_GRAIN_INTENSITY 0.05
  • AA_QUALITY 5 (SMAA Ultra+ - Default): High-performance 1x Ultra SMAA pipeline with G-Buffer depth predication (Gbuffer8Map), dual-axis bilinear sample weights, and 0.65 subpixel micro-feature reconstruction. Accurately resolves fine hair tips, eyelashes, and sharp geometric edges without temporal lag or texture blurring.
  • AA_QUALITY 6 (TAA): 5-tap Catmull-Rom bicubic history reconstruction, Karis HDR luma weighting, and depth history rejection. Required for silky-smooth Hashed Alpha hair stipple resolution.
  • AA_QUALITY 7 (G-DLAA): Hybrid geometric & directional anti-aliasing preserving crisp texture details.
  • POST_SHARPEN_ENABLE 1: AMD FidelityFX Contrast Adaptive Sharpening (CAS) keeping edges crisp.