Why Does My VRM File Not Load?

We’ve all been there. You’re super excited to load your very own custom model or your original character in MateEngine, and... boom — nothing happens. The model doesn’t show up at all.

You’re probably thinking:

• “But it worked in App X and App Y!”
• “MateEngine is trash, it doesn’t even load my model!”

But here’s the truth:

MateEngine is not at fault when your VRM doesn't load.
Other apps (like those using MelonLoader) may force-load your model with fallback shaders or error-skipping logic. MateEngine does not do this — and that’s on purpose.

MateEngine is lightweight and strict on purpose. It will never load broken models with fallback shaders or fake compatibility. Why?
Because the goal is to encourage clean models and help creators fix their own bugs the right way.

---

What Could Cause My VRM to Not Load?

There are a few common reasons why your VRM might not load in MateEngine:

• Incorrect Humanoid Bone Structure
• Unsupported or Wrong Shaders

Let’s break both of these down:

---

Humanoid Bone Structure

Let’s talk Unity's humanoid system.
VRM0.X and VRM1.0 files require a very specific bone setup to be valid.

If you converted an MMD file (common mistake!) without properly adjusting the bones, the structure is likely invalid.
MMD bone structures are not the same as Unity’s Humanoid system — and that’s a problem.

Here’s what a correct Humanoid hierarchy looks like:

VRMModel (GameObject)
├── Armature
│   └── Hips (Root bone in Humanoid setup)
│       ├── Spine
│       │   ├── Chest
│       │   │   ├── UpperChest (optional)
│       │   │   │   ├── Neck
│       │   │   │   │   └── Head
│       │   │   │   │       ├── LeftEye
│       │   │   │   │       ├── RightEye
│       │   │   │   │       └── Jaw (optional)
│       │   │   ├── LeftShoulder → LeftUpperArm → LeftLowerArm → LeftHand → Fingers
│       │   │   └── RightShoulder → RightUpperArm → RightLowerArm → RightHand → Fingers
│       ├── LeftUpperLeg → LeftLowerLeg → LeftFoot → LeftToes (optional)
│       └── RightUpperLeg → RightLowerLeg → RightFoot → RightToes (optional)
├── Meshes (SkinnedMeshRenderer)
├── Animator (on root or child GameObject)
├── VRMMeta (for VRM0.x)
├── Vrm10Instance (for VRM1.0)
├── VRMBlendShapeProxy (for blendshape control)
├── Other components...

Use this structure as a reference to debug your own model!
Even one missing or misnamed bone can break the import.

---

The Materials and Shaders

• VRM0.X requires the MToon shader.
• VRM1.0 requires MToon10 shaders.

If you use a custom shader and export a VRM, it might load in some other apps that replace the shader behind the scenes (fallback loaders).
But MateEngine will not do that.

MateEngine loads VRM files natively, just as they’re defined.
So if your shader isn’t correct or missing — the model won’t show up.

Tip: Use the MateSDK VRM Validator to quickly check if your model meets VRM specs.

---

Want to Use Custom Shaders?

If you want to use shaders like Liltoon, Poiyomi, or others — then don’t use VRM!
Instead, convert your VRM to a .me model, which supports any shader you want (as long as it’s included in the prefab).