Quick Start Guide

Quick Start Guide

This guide walks you through setting up a complete Ray-MMD ReForge scene in MikuMikuDance (MMD) from scratch.

---

1. Prerequisites

1. MikuMikuDance (64-bit recommended): MMD v9.26 or higher.
2. MikuMikuEffect (MME): Ensure MMEffect_x64.dll is installed in your MMD root directory.
3. GPU Drivers: Updated graphics drivers supporting DirectX 9 / Shader Model 3.0.

---

2. Setting Up the Base Engine

1. Load the Main Effect (ray.x):

   • Drag and drop ray.x from the main Ray-MMD folder into MMD, or load it via Accessory Manipulation -> Load.
   • Note: The screen will initially appear black or flat grey until lighting and skybox are configured.

2. Load the Modular Controllers:

   • In Ray-MMD ReForge, the monolithic ray_controller.pmx has been decentralized into specialized, domain-specific controllers. This modular architecture allows new shader features to be introduced and configured independently without breaking or bloating a single monolithic file.
   • Minimal Recommended Setup for Basic Scenes (Load these 4 via Model Manipulation -> Load):
     • LightingController.pmx: Direct sunlight, ambient multi-light scaling, SSAO, SSDO, SSSS, and SSGI/SSPT bounce strength.
     • CameraController.pmx: Cinematic lens Depth of Field (aperture F-stop, focal length, focus distance, iris blade count), optical dispersion, and vignette.
     • ColorGradingController.pmx: Comprehensive studio color grading (Lift/Gamma/Gain split toning, 2D white balance, exposure, vibrance, and film looks).
     • FogController.pmx: Physical dual-layer exponential height fog, volumetric godrays, mist noise, and wind dynamics.
   • Optional Specialized Controllers (Load when needed):
     • BloomController.pmx: Independent bloom threshold, radius, star diffraction, and HSV grading.
     • SkyVisibilityController.pmx: Macro ambient occlusion under roofs, bridges, and covered geometry (Snowdrop Engine).
     • CausticsController.pmx: Real-time directional water caustics wave simulation.
   • Diagnostic Controllers:
     • DebugController.pmx: Real-time G-buffer, shadow cascade, and SSGS inspection.
     • SSRDebugController.pmx: Real-time diagnostic visualization of SIMD SSR raymarching.
   • (Note: Legacy scenes using ray_controller.pmx retain universal fallback bindings for backwards compatibility).

---

3. Setting Up the Skybox / Environment Lighting

Ray-MMD is an image-based lighting (IBL) renderer and requires a skybox for ambient reflections.

1. Open any skybox folder inside Skybox/ (for example, Skybox/Helipad GoldenHour/ or Skybox/Time of day/).
2. Load the .pmx model (e.g. Helipad GoldenHour.pmx or Sky with box.pmx).
3. Open the MMEffect window (top right button in MMD):
   • Go to the EnvLightMap tab.
   • Right-click the skybox model and select Set Effect.
   • Assign the corresponding lighting shader (e.g. Sky with box.fx or Time of day.fx).

---

4. Assigning Materials to Models

1. Load your character or stage .pmx model into MMD.
2. Open the MMEffect window:
   • Main tab: Assign Main/main.fx to your model (or Main/main_alpha.fx if the model has transparent parts).
   • MaterialMap tab: Assign appropriate materials from the Materials/ folder to each material subset of your model:
     • Skin: Materials/Skin/material_skin.fx (or material_skin_beige.fx, etc.).
     • Hair: Materials/Hair/material_hair.fx.
     • Eyes: Materials/Eye/material_eye_anime.fx or material_eye.fx.
     • Clothing / Fabric: Materials/Cloth/material_cloth.fx.
     • Metals: Materials/Metallic/material_metal.fx.
     • Glass: Materials/Transparent/material_glass.fx.

---

5. Adding Sun and Additional Lights (Optional)

1. Sun Light (Directional):
   • Inside Lighting/DirectionalLight/, load directional_light.pmx.
   • In MME -> LightMap tab, assign directional_lighting.fx.
   • Rotate the light bone in MMD to change the sun angle.
2. Point / Spot Lights:
   • Load point_light.pmx or spot_light.pmx from the Lighting/ directory.
   • Assign point_lighting.fx or spot_lighting.fx in the LightMap tab.

---

6. Adjusting Scene Parameters via Modular Controllers

Select the respective controller in MMD and use the facial morph sliders:

LightingController.pmx

• Sunlight (SunLight+ / SunLight-): Boost or attenuate direct solar irradiance.
• Multi-Light (MultiLight+ / MultiLight-): Scale analytic point/spot/area light contribution.
• SSGI (SSGI+ / SSGI-): Increase or decrease screen-space indirect diffuse bouncing.
• Ambient Occlusion (SSAO+ / SSAO-, SSDO+ / SSDO-): Adjust crevice shadowing depth.
• Subsurface Scattering (SSSS+ / SSSS-): Scale skin scattering diffusion.

CameraController.pmx

• Depth of Field (Fstop-, FocalLength+, FocalDistance+, FocalRegion+): Cinematic optical bokeh blur and focus plane calibration (TestMode, MeasureMode).
• Vignette & Dispersion (Vignette+, Dispersion+, DispersionRadius+): Lens edge darkening and chromatic aberration.

BloomController.pmx

• Bloom (BloomThreshold, BloomRadius+ / BloomRadius-): Control the soft glow around highlights.
• Color Grading Bloom (BloomColorAllH, BloomColorAllS, BloomColorAllV): Tint the bloom effect across the spectrum.

FogController.pmx

• Fog & Ground Mist Density (FogDensity+ / FogDensity-, GroundDensity+ / GroundDensity-): Scale atmospheric haze and low-altitude ground mist layers independently.
• Volumetric Godrays (Godrays+ / Godrays-, RayDensity+ / RayDensity-): Adjust directional sun light shaft intensity and raymarch sample density.
• Sun Tint & Scatter (SunR/G/B+ / -, MiePhase+ / -): Color-tint solar scattering and modulate Mie forward phase lobe asymmetry.
• Mist Noise & Wind (MistNoise+ / MistNoise-, WindSpeed+ / WindSpeed-): Add 3D procedural mist turbulence swirls and modulate animated wind drift.

Tip

Additional Specialized Controllers:

• ColorGradingController.pmx: Load into scene for full linear HDR 3-way split-toning (Lift/Gamma/Gain), 2D white balance (Temperature/Tint), Vibrance, and cinematic presets (Teal & Orange, Bleach Bypass, Cross Process, Monochrome).
• SkyVisibilityController.pmx: Load into scene to dynamically balance macro ambient occlusion under roofs, bridges, and covered geometry (Snowdrop Engine).
• SSRDebugController.pmx: Real-time diagnostic visualization of SIMD SSR raymarching (Steps, Confidence, Roughness, Normals).
• CausticsController.pmx: Directional underwater wave caustics height, intensity, and ripple speed.
• DebugController.pmx: Real-time viewport diagnostics for G-Buffer, PSSM Cascades, ShadowMap, and SSGS raymarching.