Troubleshooting & FAQ

Frequently asked questions and solutions for common setup issues in Ray-MMD ReForge.

---

1. Common Issues & Solutions

Q: The screen is completely black after loading ray.x.

• Cause: Ray-MMD requires an active Image-Based Lighting (IBL) environment or sun light to illuminate the scene.
• Solution: Load a skybox from the Skybox/ folder (e.g. Helipad GoldenHour.pmx) and assign its lighting shader in MME -> EnvLightMap tab.

Q: Models look grey or lack reflections.

• Cause: The model does not have main.fx or material shaders assigned in MME.
• Solution: Open MME:
  • Assign Main/main.fx to the model in the Main tab.
  • Assign appropriate material shaders (e.g. material_skin.fx, material_cloth.fx) in the MaterialMap tab.

Q: Anime eyes look dark or reflections curve inward (sunken look).

• Cause: Anime eye meshes are typically modeled with concave geometry.
• Solution: Assign Materials/Eye/material_eye_anime.fx to the eye material subset. This shader enables CONVEX_NORMAL 1, which mathematically inverts the curvature into a convex reflective dome.

Q: Low FPS or performance stutter.

• Solutions:
  1. In ray.conf, set SUN_SHADOW_QUALITY 2 or SUN_SHADOW_QUALITY 1.
  2. Set GI_QUALITY 2 or switch to GI_ENABLE 1 (Accent mode).
  3. Ensure MMD is running on your dedicated GPU (Nvidia/AMD) rather than integrated graphics (Intel HD/UHD).

Q: Transparent accessories (glasses, veils, ribbons) disappear or render black.

• Solution:
  • Assign Main/main_alpha.fx instead of main.fx in the MME Main tab.
  • In MMD's model order list (Model Manipulation), ensure transparent models are loaded after opaque models.

Q: Looking through car windshields or glass from an interior cockpit camera causes dark borders, distorted background, or missing skybox.

• Cause: Automotive models in MMD typically contain nested, multi-layered, or single-sided window geometry (tint mesh, inner glass, outer glass). In deferred rendering, refractive alpha passes cannot resolve complex interior-to-exterior nested transparency without forward depth peeling.
• Solution: For interior cockpit shots, in MME -> MaterialMap tab, right-click the vehicle's window material subsets and assign a transparent null material, hide the subsets in MME, or set their alpha to 0 in PMX Editor. This removes nested occlusion artifacts and gives crystal-clear interior views with complete SSGI, atmospheric fog, and Time of Day clouds.

---

2. Frequently Asked Questions

Where is ray_controller.pmx? Which controllers should I load for a basic setup?

• Why the change: In Ray-MMD ReForge, the monolithic ray_controller.pmx was decentralized into modular controllers. Distributing functionality across dedicated controllers ensures that when new shader features are added, they receive dedicated controls without cluttering or destabilizing a single massive controller.
• Basic Setup: You do not need to load all 9 controllers. For a complete standard setup, load only these four controllers:
  1. LightingController.pmx (Sunlight, SSAO/SSDO, SSGI/SSPT, SSSS, MultiLight)
  2. CameraController.pmx (Depth of Field, Vignette, Chromatic Aberration)
  3. ColorGradingController.pmx (Exposure, White Balance, Lift/Gamma/Gain)
  4. FogController.pmx (Atmospheric & Ground Fog, Volumetric Godrays)
• Optional Controllers: BloomController.pmx (if bloom needs fine-tuning), SkyVisibilityController.pmx (for covered macro AO), and CausticsController.pmx (for water caustics) can be loaded as needed.

Is Ray-MMD ReForge compatible with materials from Ray-MMD 1.5.2?

Yes, 100%. All existing .fx and .fxsub material files, maps, and texture sets designed for Ray-MMD 1.5.2 work out-of-the-box in ReForge without any modifications.

How do I update my existing scene to ReForge?

Simply replace your old Ray-MMD folder with the Ray-MMD ReForge folder, or point your MMD accessories/shaders to the ReForge directory.