MATRiX Python SDK

Python SDK for loading MuJoCo scenes, running user control code, and synchronizing MuJoCo state to Unreal Engine over UDP.

完整接入教程见：docs/development_tutorial.md

The UE packet format is compatible with jszr_sdk_bridge.cc:

double time
uint32 nq
double qpos[nq]
uint32 nv
double qvel[nv]
uint32 nu
double act[nu]

All values are little-endian. If MuJoCo exposes fewer activation values than nu, the Python SDK pads the activation array with zeros so the packet shape remains compatible with the C++ bridge.

Install

pip install -e .

Run the XGB Unreal scene

python examples/xgb_unreal_sync.py

By default it loads model/xgb/unreal.xml, opens the MuJoCo viewer, and sends state packets to 127.0.0.1:9999.

Run without the local MuJoCo window:

python examples/xgb_unreal_sync.py --no-viewer

Some legacy binary STL files start with solid or exceed MuJoCo 3.8's STL triangle limit. When that happens, the SDK loads a temporary patched copy of the model directory. If a mesh is still rejected, mesh geoms are stripped only in the temporary copy so simulation and UE state synchronization can continue without modifying the original assets.

Minimal Usage

from matrix_sdk import MujocoUESyncSDK

sdk = MujocoUESyncSDK(
    "model/xgb/unreal.xml",
    ue_host="127.0.0.1",
    ue_port=9999,
    sync_hz=100,
    viewer=True,
)

def controller(state):
    # Return an array with shape (sdk.model.nu,), or None to leave ctrl unchanged.
    return [0.0] * sdk.model.nu

sdk.run(controller=controller, duration=10.0)
sdk.close()

For integration with an external control program, build your own socket, shared-memory, ROS, eCAL, or IPC logic inside the controller callback and return the latest MuJoCo control vector.

External UDP Control

The SDK also includes a simple non-blocking control receiver. Your external program sends nu little-endian float64 values to port 10001.

from matrix_sdk import MujocoUESyncSDK, UdpControlReceiver

with MujocoUESyncSDK("model/xgb/unreal.xml") as sdk:
    with UdpControlReceiver(sdk.model.nu, port=10001) as controls:
        sdk.run(controller=controls.controller)