Unity Mujoco

[HWork-git]

Intro

Hi!

I am a ([graduate / undergrad] student / professor / researcher) at XYZ, I use MuJoCo for my research on ABC.

My setup

MuJoCo ：mujoco-3.8.1-windows-x86_64
unity :2022.3.62f2c1

My question

When I imported the XML file exported by Mujoco using Unity-related plugins, it worked normally. However, when I ran it, it collapsed and flew randomly everywhere. What was the cause of this?

Minimal model and/or code that explain my question

If you encountered the issue in a complex model, please simplify it as much as possible (while still reproducing the issue).

Model:

minimal XML

<mujoco>
  <worldbody>
    <light pos="0 0 1"/>
    <geom type="sphere" size="1" rgba="1 0 0 1"/>
  </worldbody>
</mujoco>

Code:

import mujoco
import mediapy as media
model = mujoco.MjModel.from_xml_string(xml)
data = mujoco.MjData(model)

with mujoco.Renderer(model) as renderer:
  mujoco.mj_forward(model, data)
  renderer.update_scene(data)

  media.show_image(renderer.render())

Confirmations

• I searched the latest documentation thoroughly before posting.
• I searched previous Issues and Discussions, I am certain this has not been raised before.

[salou07]

Hi,

The "collapse & fly" behavior usually happens during MuJoCo → Unity export due to one of these:

1. Coordinate mismatch: MuJoCo is Z-up, Unity is Y-up. Without proper rotation/translation, collision geometries self-intersect.
2. Missing or inaccurate mass/inertia on bodies → physics solver accumulates energy until instability.
3. Joint axes misaligned or lacking damping/friction → unnatural torque buildup.

I've dealt with the exact same instability in a biomechanical hand model. I manually aligned the joint axes to match anatomical motion vectors, added proper damping, and validated inertia tensors. The result is a stable simulation without collapsing or flying.

You can see the stable behavior here:
👉 https://salou07.github.io/Hand-Simulation/

[Balint-H]

@HWork-git

The number one reason for stability mismatch is the timestep. The physics timestep of Unity and the underlying mujoco sim is matched. When you import a scene the Unity timestep is not updated (a warning is issued), since that is global for all scenes in Unity. Since the Unity timestep is usually much larger than the MuJoCo one, this often leads to instability. A simple fix is opening up the settings of your Unity, and changing the Physics dt to match the intended one from Unity.

@salou07's suggestions are indeed good things to double check in general for a model. However, in general you are not expecting to see a mismatch in joint axes, masses or translations. If you do end up seeing an issue like that, then it is (most likely) a bug in the importer, please report it!