Skip to content

Troubleshooting

Jump to bottom
desuqcafe edited this page Nov 23, 2025 · 1 revision

Troubleshooting

This page covers common issues and solutions when using Off World Live's VRM4U fork for non-VRM skeleton support.

Auto-Populate Issues

No Bones Mapped After Auto-Populate

Symptoms:

  • Clicking "Auto Populate" doesn't map any bones
  • Output Log shows "No bones detected"
  • Character doesn't respond to VMC data

Solutions:

  1. Check Skeleton Type Setting

    • Make sure you selected the correct skeleton type
    • Try setting it manually instead of using "Auto"
    • Common types: Metahuman, Mixamo, Daz, VRM

  2. Verify Target Skeletal Mesh

    • Ensure the Target Skeletal Mesh field is set
    • The skeletal mesh must have a valid skeleton asset

  3. Check Bone Naming

    • Your skeleton must use relatively standard humanoid bone names
    • Open your skeleton asset and verify bone names match common conventions

Critical Bones Missing

Symptoms:

  • Some bones mapped but important ones are missing (spine, head, hands, etc.)
  • Character motion is partially working but incomplete

Solutions:

  1. Use Custom Bone Overrides

    • In the Vrm Meta Object, add manual bone mappings
    • Format: Humanoid Bone Name → Your Model's Bone Name
    • Example: leftHand → hand_l

  2. Check Output Log

    • Look for warnings about which bones failed to map
    • This tells you exactly which bones need manual override

  3. Verify Bone Hierarchy

    • Ensure your skeleton has a complete humanoid hierarchy
    • Missing parent bones can cause child bones to fail

Wrong Skeleton Type Detected

Symptoms:

  • Auto mode detects the wrong skeleton type
  • Bone mapping is incorrect or incomplete

Solutions:

  1. Set Skeleton Type Manually

    • Don't use "Auto" - select the specific type
    • Choose from: VRM, Metahuman, Mixamo, Daz, or Other

  2. Use Custom Bone Overrides

    • Manually specify the correct bone mappings
    • This overrides the automatic detection

Performance Issues

Low Frame Rate / Stuttering

Symptoms:

  • Game runs slowly when mocap is active
  • Stuttering or hitching during motion capture
  • High CPU usage

Solutions:

  1. Lower Update Mode

  2. Check Multiple Characters

    • If you have multiple VMC receivers, lower their update rates
    • Use Performance mode for background characters

  3. Monitor System Resources

    • Use stat fps and stat unit console commands
    • Check CPU and GPU usage
    • Close unnecessary applications

Motion Looks Choppy

Symptoms:

  • Motion capture looks jerky or stuttery
  • Updates appear to skip frames
  • Character movement isn't smooth

Solutions:

  1. Increase Update Rate

    • Switch from Performance → Balanced
    • Or Balanced → Streaming
    • Try Custom mode with higher FPS

  2. Check Source Frame Rate

    • Ensure XR Animator is sending at a high enough rate
    • VMC sender should match or exceed your update mode

  3. Verify Network Connection

    • VMC protocol uses UDP networking
    • Check for packet loss or network congestion
    • Try using localhost (127.0.0.1) if both apps are on the same machine

Bone Mapping Issues

Character Not Moving at All

Symptoms:

  • VMC data is being received but character doesn't move
  • No error messages in Output Log

Solutions:

  1. Check Animation Blueprint Assignment

    • Verify your Animation Blueprint is assigned to the character's Skeletal Mesh Component
    • In the character's details: Mesh → Anim Class

  2. Verify VrmVMC Node Connection

    • Open the Animation Blueprint
    • Check that VrmVMC output pin is connected to Result node

  3. Confirm Vrm Meta Object Assignment

    • Select the VrmVMC node
    • Verify Vrm Meta Object field is set in Details Panel

  4. Check VMC Port

    • Default is 39539
    • Make sure XR Animator is sending to the correct port
    • Check firewall isn't blocking UDP traffic

Specific Bones Not Moving Correctly

Symptoms:

  • Most bones work but some don't move or move incorrectly
  • Hands, feet, or spine behaving strangely

Solutions:

  1. Use Transform (Modify) Bone Nodes

    • Add these after the VrmVMC node
    • Manually adjust problematic bone transforms
    • Good for fine-tuning offsets

  2. Check Custom Bone Overrides

    • Verify the bone name mapping is correct
    • Bone names are case-sensitive
    • Check for typos

  3. Review Skeleton Structure

    • Some skeletons have non-standard hierarchies
    • Extra bones or missing bones can cause issues

Rotation Offsets / T-Pose Issues

Symptoms:

  • Character is in T-pose or A-pose when it should be neutral
  • Bones are rotated incorrectly
  • Arms or legs pointing wrong direction

Solutions:

  1. Enable "Ignore Local Rotation"

    • In VrmVMC node details
    • This helps with skeleton compatibility

  2. Check Reference Pose

    • Your skeleton's reference pose should match VMC expectations
    • Most VMC data expects T-pose or A-pose reference

  3. Add Rotation Offsets

    • Use Transform (Modify) Bone nodes
    • Add rotation offsets to correct bone orientations

XR Animator / VMC Connection Issues

Not Receiving Data from XR Animator

Symptoms:

  • Character doesn't move when XR Animator is running
  • No connection between apps

Solutions:

  1. Verify IP Address and Port

    • XR Animator should send to your PC's IP address
    • Use 127.0.0.1 if both apps are on the same machine
    • Default port: 39539

  2. Check Firewall

    • Windows Firewall may block UDP traffic
    • Add exception for Unreal Engine
    • Or temporarily disable firewall to test

  3. Confirm VMC Output Enabled

    • In XR Animator settings, enable VMC Protocol output
    • Make sure it's actually sending data (check XR Animator's status)

  4. Test with Different Port

    • Try a different port number
    • Some ports may be blocked or in use

Delayed or Laggy Motion

Symptoms:

  • Motion appears with noticeable delay
  • Character lags behind real movements

Solutions:

  1. Network Latency

    • Use localhost (127.0.0.1) when possible
    • Check network connection if using different machines
    • Close bandwidth-heavy applications

  2. Lower Update Rate Temporarily

    • Test if network can't keep up with high update rates
    • Try Performance mode to reduce network traffic

  3. Check System Performance

    • High CPU usage can cause processing delays
    • Monitor with stat unit console command

Build and Compilation Issues

Plugin Won't Load

Symptoms:

  • "Plugin requires modules that are missing" error
  • Plugin checkbox is grayed out

Solutions:

  1. Blueprint Projects

    • This warning is normal for Blueprint projects
    • Click "Yes" to continue - plugin should still work

  2. C++ Projects

    • Rebuild the solution in Visual Studio
    • Right-click .uproject → Generate Visual Studio Project Files
    • Clean and rebuild

  3. Check Plugin Structure

    • Verify VRM4U folder structure is correct
    • VRM4U.uplugin should be in Plugins/VRM4U/

Compilation Errors

Symptoms:

  • Build fails in Visual Studio
  • Compilation errors in Output Log

Solutions:

  1. Update Visual Studio

    • Make sure you have the correct Visual Studio version for your Unreal Engine version
    • UE 5.3+ requires VS 2022

  2. Clean and Rebuild

    • In Visual Studio: Build → Clean Solution
    • Then: Build → Rebuild Solution

  3. Check Unreal Engine Version

    • Verify plugin version matches your UE version
    • Download the correct release from GitHub

General Debugging Tips

Enable Detailed Logging

  1. Open DefaultEngine.ini in your project's Config folder
  2. Add these lines:
[Core.Log]
LogVRM4U=Verbose
LogAnimation=Verbose
  1. Restart editor and check Output Log for detailed information

Check Output Log

  • Window → Developer Tools → Output Log
  • Look for warnings or errors related to VRM4U
  • Search for "VRM4U" or "VrmVMC"

Test with Sample Content

  • Try the included VRM4U sample maps first
  • If samples work but your setup doesn't, compare configurations
  • Helps isolate whether issue is with plugin or your setup

Verify Prerequisites

  • Plugin content is enabled (Show Plugin Content in Content Browser)
  • OSC plugin is enabled (required for VMC protocol)
  • XR Animator is properly configured and running

Still Having Issues?

If you've tried the solutions above and still have problems:

  1. Check Original VRM4U Documentation

    • Many core features are documented there: VRM4U Docs

  2. Open a GitHub Issue

    • Visit our GitHub Issues
    • Include:
      • Your Unreal Engine version
      • Skeleton type you're using
      • Steps to reproduce the problem
      • Screenshots of your setup
      • Relevant error messages from Output Log

  3. Check Existing Issues

    • Someone may have already reported and solved your issue
    • Search closed issues as well as open ones

Additional Resources

Clone this wiki locally