Quick Start Guide - ReForge-MMD/ray-mmd-reforge GitHub Wiki

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 (LightingController.pmx, CameraController.pmx, etc.):

    • In Ray-MMD ReForge v1.21.0+, the monolithic ray_controller.pmx has been completely decommissioned in favor of a specialized Modular PMX Controller Suite. Load the controllers you need via Model Manipulation -> Load:
      • LightingController.pmx: Direct sunlight, ambient multi-light scaling, SSAO, SSDO, SSSS, and SSGI multipliers.
      • CameraController.pmx: Cinematic lens Depth of Field (aperture F-stop, focal length, focus distance, iris blade count), optical dispersion, and vignette.
      • BloomController.pmx: Independent bloom threshold, radius, and HSV grading.
      • FogController.pmx: Physical dual-layer exponential height fog, volumetric godrays, mist noise, and wind dynamics.
    • (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.