Skip to content

Uploading your own robot

Sim2Bot accepts a MuJoCo MJCF folder or ZIP. URDF and Xacro entry files can also be converted into a basic controllable MJCF model during import. The complete model is compiled locally before it is added to the scene.

For URDF packages, define the grasp frame as a meshless fixed link named tcp, tcp_site, tool_center_point, end_effector, pinch_site, grasp_site, or attachment_site. Sim2Bot preserves that link as a MuJoCo site, including its fixed-joint translation and rotation, so IK and frame visualization use the authored grasp point without adding visible test geometry.

Keep every referenced file inside one folder and use relative paths:

my_robot/
├── scene.xml
├── my_robot.xml
├── sim2bot.robot.json
├── preview.png
├── README.md
├── LICENSE
├── meshes/
│   ├── base.stl
│   └── link_1.stl
└── textures/
    └── body.png

scene.xml is preferred as the entry point. If it is absent, Sim2Bot chooses the shallowest XML, URDF, or Xacro file it can find.

What my_robot.xml contains

my_robot.xml is the actual MuJoCo MJCF model, not a JSON metadata file. It defines the robot's bodies, joints, geometry, actuators, sites, cameras, sensors, and optional keyframes using XML.

A deliberately small two-joint example looks like this:

<mujoco model="my_robot">
  <compiler angle="radian" meshdir="meshes"/>
  <option timestep="0.002" gravity="0 0 -9.81"/>

  <default>
    <joint limited="true" damping="1"/>
    <geom type="capsule" size="0.04" rgba="0.35 0.55 0.9 1"/>
  </default>

  <worldbody>
    <body name="base" pos="0 0 0">
      <geom type="cylinder" size="0.1 0.05"/>

      <body name="link1" pos="0 0 0.1">
        <joint name="joint1" type="hinge" axis="0 0 1" range="-3.14 3.14"/>
        <geom fromto="0 0 0 0 0 0.4"/>

        <body name="link2" pos="0 0 0.4">
          <joint name="joint2" type="hinge" axis="0 1 0" range="-2 2"/>
          <geom fromto="0 0 0 0 0 0.3"/>
          <site name="tool_center_point" pos="0 0 0.3" size="0.015"/>
        </body>
      </body>
    </body>
  </worldbody>

  <actuator>
    <position name="joint1" joint="joint1" kp="80"/>
    <position name="joint2" joint="joint2" kp="80"/>
  </actuator>

  <keyframe>
    <key name="home" qpos="0 0" ctrl="0 0"/>
  </keyframe>
</mujoco>

This example is only a structural starting point. A production robot should use correct masses, inertias, collision geometry, joint limits, actuator limits, damping, friction, meshes, and stable home configuration from the real model.

scene.xml normally includes the robot model and adds shared scene elements:

<mujoco model="my_robot_scene">
  <include file="my_robot.xml"/>

  <worldbody>
    <light pos="0 0 3"/>
    <geom name="floor" type="plane" size="0 0 0.05"/>
  </worldbody>
</mujoco>

Optional package manifest

sim2bot.robot.json is a versioned metadata file that Sim2Bot reads during import. It is separate from the MJCF: XML defines the physics and geometry; JSON tells Sim2Bot how the authored model should be presented and controlled.

{
  "version": 1,
  "name": "My Robot",
  "manufacturer": "Example Robotics",
  "category": "arm",
  "license": "Apache-2.0",
  "sourceUrl": "https://example.com/my-robot",
  "sourceRevision": "v1.2.0",
  "packageVersion": "1.2.0",
  "entry": "scene.xml",
  "dof": 6,
  "tcpSites": ["tool_center_point"],
  "endEffectorBodies": ["tool0"],
  "armActuators": ["joint1", "joint2", "joint3", "joint4", "joint5", "joint6"],
  "gripperActuators": ["gripper"],
  "preview": "preview.png"
}

One folder can expose multiple compatible model entries, such as optional end effectors. Add variants while keeping entry as the default:

{
  "version": 1,
  "name": "My Robot",
  "category": "arm",
  "entry": "scene_msg.xml",
  "dof": 6,
  "variants": [
    {
      "id": "flange",
      "label": "Flange only",
      "entry": "scene_flange.xml",
      "gripperActuators": []
    },
    {
      "id": "msg",
      "label": "MSG gripper",
      "entry": "scene_msg.xml",
      "gripperActuators": ["gripper"]
    }
  ]
}

The import review displays a selector and compiles the selected entry before adding it. A variant may override its preview, TCP sites, end-effector bodies, and arm/gripper actuator names. Empty arrays intentionally remove an inherited declaration—for example, the flange variant has no gripper actuator.

After installation, the same End effector selector is available under the robot inspector's Actuation section. Changing it recompiles the uploaded package and updates its live scene instances while preserving the installed package identity used by saved scenes.

version, name, category, and dof are required. Variant IDs must be unique safe identifiers. All paths must be safe, package-relative paths; sourceUrl must use HTTP or HTTPS. Sim2Bot compiles the model and verifies declared actuator, TCP, end-effector, and DOF information instead of blindly trusting the manifest. A mismatch stops the import with an actionable error.

Supported uploaded categories

arm and custom packages are currently accepted. The schema reserves categories such as quadruped, humanoid, and mobile-manipulator, but Sim2Bot rejects them until their controller and telemetry contracts are implemented. This prevents a model that merely renders from being advertised as controllable.

The manifest is optional. Without it, the guided wizard infers a conservative starting point from the compiled MJCF. You can review the result and select Manifest to download a ready-to-include sim2bot.robot.json for the next version of your package.

Include preview.png

A root-level preview.png, preview.jpg, thumbnail.png, or thumb.webp is detected automatically. Sim2Bot resizes it to at most 480 × 320 and encodes a compact WebP thumbnail. You can replace it in the import wizard.

If the package has no preview, Sim2Bot renders the compiled robot on the same blue checker floor, cool backdrop, and soft-shadow treatment used by the built-in MuJoCo Menagerie catalog cards. It frames the robot automatically and generates a compact 480 × 320 WebP image. This is a real 3D render of the uploaded model, not a generic icon.

Import workflow

  1. Open Scene → Robots.
  2. Drop the folder or ZIP into Load a MuJoCo robot, or use Folder or .zip.
  3. Wait for MuJoCo compilation. Compilation errors are shown before the scene is changed.
  4. Review the detected model in the import wizard.
  5. Confirm the display name, category, arm DOF, and TCP site.
  6. Add manufacturer, licence, and source URL before sharing. Review the supplied or automatically rendered preview.
  7. Select Add robot.

The wizard detects likely arm/gripper actuators, common TCP names, keyframes, model cameras, and sensors. Detection is conservative and must be reviewed.

Manage uploaded robots

Open Scene → Robots → My uploaded robots to manage packages stored in the current browser. Select a robot to open its larger preview and package details. From this view you can:

  • edit its display name, manufacturer, category, SPDX licence, source URL, upstream revision, and package version;
  • inspect its detected actuators, TCP sites, cameras, sensors, authored poses, and exact package snapshot;
  • regenerate the compact Menagerie-style 3D thumbnail;
  • export a ZIP containing the robot files, current metadata manifest, and any generated preview;
  • export only sim2bot.robot.json;
  • see how many current robot instances and named saved scenes use the package;
  • delete the browser-local package or its account cloud copy independently.

Package version, source revision, and snapshot

These identify different things. packageVersion is the author's release label, such as 1.2.0. sourceRevision pins the upstream tag, commit, or archive checksum. Sim2Bot also calculates snapshotDigest, a SHA-256 digest of the exact uploaded bytes. If no package version is supplied, Sim2Bot uses a deterministic snapshot-xxxxxxxxxxxx version so changed uploads can still be detected.

Uploading the same source/name and exact snapshot reuses the installed package. Uploading a different snapshot offers to replace it while preserving its local identity and saved-scene references. If its cloud snapshot differs, the detail view marks the cloud copy as older until it is saved again.

Remove an uploaded robot

Open Scene → Robots → My uploaded robots, select the package, and choose Delete local package. The smaller catalog card also retains a quick red trash action.

Sim2Bot asks for confirmation and reports whether the package is used by the current scene or by a named saved scene:

  • Current-scene instances are removed with the uploaded package. If it was the only robot, Sim2Bot places the default Franka robot at the same base pose so the scene remains valid.
  • Named saved scenes are not silently rewritten. A scene that still references the deleted package will report that model as missing when opened.
  • The locally persisted package and unreferenced bundle bytes are removed.
  • A separately saved cloud copy is deliberately left alone. Choose Delete cloud copy separately when you also want to remove the account copy.

Built-in catalog robots do not have this delete action.

Authored poses

Every named MJCF <key> is discovered during compilation. The robot inspector shows these as Authored poses buttons and sends the selected pose through the normal robot target/controller path. Include a safe home keyframe whenever possible; names such as rest, retract, and ready become equally actionable.

The qpos vector must match the model's MuJoCo state layout. Sim2Bot does not invent pose values when the XML contains no keyframe.

Arm DOF and actuators

The Arm DOF value is the number of independently controlled arm axes—not the total number of MuJoCo actuators. Do not count a gripper, finger tendon, mobile base, or auxiliary mechanism as another arm axis.

For a six-axis arm with one gripper actuator, use 6, not 7.

TCP site

A TCP is an MJCF <site> placed at the tool centre point. Clear, conventional names improve automatic detection:

<site name="tcp" pos="0 0 0.12" size="0.01"/>

Sim2Bot recognizes common names such as tcp, tcp_site, link_tcp, end_effector, pinch_site, grasp_site, and attachment_site. Enter an authored custom name in the wizard when necessary. Leave the field empty when the model does not have a verified TCP.

A compiled model is not automatically a correct robot

MuJoCo can compile a model whose actuator order, TCP, joint limits, or gripper split is unsuitable for Sim2Bot control. Test joint motion, reset, IK/TCP behavior, cameras, and telemetry before publishing or relying on it.

Thumbnail size and storage

The thumbnail is presentation data, not a texture used by the robot model. Sim2Bot stores uploaded thumbnails as compressed WebP data with the robot definition so they survive local persistence, scene export, and cloud sync. At 480 × 320 they are normally approximately 15–80 KB, depending on image detail. The original image inside the uploaded bundle is retained as part of the model archive, so removing unnecessarily large originals still reduces cloud storage.

Built-in catalog thumbnails use dedicated 480-pixel JPEG card images, generally about 25–40 KB each. Their larger upstream Menagerie preview images remain in the source packages for provenance but are not loaded by the catalog cards.

Licence and provenance

Only upload or share a model when its licence permits it. Keep the original LICENSE, README, attribution, and source link in the package. Use a valid SPDX identifier when possible—for example Apache-2.0, BSD-3-Clause, or MIT.

Do not remove copyright notices or claim an upstream model as your own. Private local testing does not automatically grant redistribution rights.

Before sharing a robot

  • The ZIP opens without relying on files outside the folder.
  • The entry XML compiles with no MuJoCo warnings.
  • Arm DOF and actuator order are correct.
  • Home/reset has a safe pose.
  • TCP and end-effector frame are correct.
  • Gripper behavior is correct.
  • Mesh units and orientations are correct.
  • Joint limits and actuator limits are physically meaningful.
  • Licence, attribution, manufacturer, and source URL are present.
  • The preview is clear at small card size.

For built-in catalog maintenance and automated validation, see the repository's docs/robot-model-catalog.md.