Make model editing API public, fixes #364

Still missing:

- Detailed documentation.
- Python bindings.

PiperOrigin-RevId: 641445626
Change-Id: I20e67b707cf1bebae7e0cc94d17f7b76a89171f0

CMakeLists.txt

@@ -59,6 +59,7 @@ set(MUJOCO_HEADERS
     include/mujoco/mjmodel.h
     include/mujoco/mjplugin.h
     include/mujoco/mjrender.h
+    include/mujoco/mjspec.h
     include/mujoco/mjthread.h
     include/mujoco/mjtnum.h
     include/mujoco/mjui.h

doc/APIreference/APItypes.rst

@@ -9,9 +9,11 @@ MuJoCo defines a large number of types:
 
   - Enums used in :ref:`mjModel<tyModelEnums>`.
   - Enums used in :ref:`mjData<tyDataEnums>`.
-  - Abstract :ref:`visualization enums<tyVisEnums>`.
+  - Enums for abstract :ref:`visualization<tyVisEnums>`.
   - Enums used by the :ref:`openGL renderer<tyRenderEnums>`.
   - Enums used by the :ref:`mjUI<tyUIEnums>` user interface package.
+  - Enums used by :ref:`engine plugins<tyPluginEnums>`.
+  - Enums used for :ref:`procedural model manipulation<tySpecEnums>`.
 
   Note that the API does not use these enum types directly. Instead it uses ints, and the documentation/comments state
   that certain ints correspond to certain enum types. This is because we want the API to be compiler-independent, and
@@ -31,9 +33,10 @@ MuJoCo defines a large number of types:
   - Structs for :ref:`abstract visualization<tyVisStructure>`.
   - Structs used by the :ref:`openGL renderer<tyRenderStructure>`.
   - Structs used by the :ref:`UI framework<tyUIStructure>`.
+  - Structs used for :ref:`procedural model manipulation<tySpecStructure>`.
   - Structs used by :ref:`engine plugins<tyPluginStructure>`.
 
-- Several :ref:`tyFunction` for user-defined callbacks.
+- Several :ref:`function types<tyFunction>` for user-defined callbacks.
 - :ref:`tyNotes` regarding specific data structures that require detailed description.
 
 
@@ -43,7 +46,7 @@ MuJoCo defines a large number of types:
 Primitive types
 ---------------
 
-The two types below are defined in `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`_.
+The two types below are defined in `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`__.
 
 
 .. _mjtNum:
@@ -89,13 +92,14 @@ Byte type used to represent boolean variables.
 Enum types
 ----------
 
+All enum types use the ``mjt`` prefix.
 
 .. _tyModelEnums:
 
 Model
 ^^^^^
 
-The enums below are defined in `mjmodel.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`_.
+The enums below are defined in `mjmodel.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h>`__.
 
 
 .. _mjtDisableBit:
@@ -333,7 +337,7 @@ These are the possible sensor data types, used in ``mjData.sensor_datatype``.
 Data
 ^^^^
 
-The enums below are defined in `mjdata.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_.
+The enums below are defined in `mjdata.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`__.
 
 
 
@@ -376,7 +380,7 @@ Timer types. The number of timer types is given by ``mjNTIMER`` which is also th
 Visualization
 ^^^^^^^^^^^^^
 
-The enums below are defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`_.
+The enums below are defined in `mjvisualize.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjvisualize.h>`__.
 
 
 .. _mjtCatBit:
@@ -480,7 +484,7 @@ These are the possible stereo rendering types. They are used in ``mjvScene.stere
 Rendering
 ^^^^^^^^^
 
-The enums below are defined in `mjrender.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`_.
+The enums below are defined in `mjrender.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjrender.h>`__.
 
 
 .. _mjtGridPos:
@@ -542,7 +546,7 @@ These are the possible font types.
 User Interface
 ^^^^^^^^^^^^^^
 
-The enums below are defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_.
+The enums below are defined in `mjui.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`__.
 
 
 .. _mjtButton:
@@ -574,13 +578,74 @@ Item types used in the UI framework.
 
 .. mujoco-include:: mjtItem
 
+.. _tySpecEnums:
+
+Spec
+^^^^
+
+The enums below are defined in `mjspec.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjspec.h>`__.
+
+.. _mjtGeomInertia:
+
+mjtGeomInertia
+~~~~~~~~~~~~~~
+
+Type of inertia inference.
+
+.. mujoco-include:: mjtGeomInertia
+
+.. _mjtBuiltin:
+
+mjtBuiltin
+~~~~~~~~~~
+
+Type of built-in procedural texture.
+
+.. mujoco-include:: mjtBuiltin
+
+.. _mjtMark:
+
+mjtMark
+~~~~~~~
+
+Mark type for procedural textures.
+
+.. mujoco-include:: mjtMark
+
+.. _mjtLimited:
+
+mjtLimited
+~~~~~~~~~~
+
+Type of limit specification.
+
+.. mujoco-include:: mjtLimited
+
+.. _mjtInertiaFromGeom:
+
+mjtInertiaFromGeom
+~~~~~~~~~~~~~~~~~~
+
+Whether to infer body inertias from child geoms.
+
+.. mujoco-include:: mjtInertiaFromGeom
+
+.. _mjtOrientation:
+
+mjtOrientation
+~~~~~~~~~~~~~~
+
+Type of orientation specifier.
+
+.. mujoco-include:: mjtOrientation
+
 
 .. _tyPluginEnums:
 
 Plugins
 ^^^^^^^
 
-The enums below are defined in `mjplugin.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjplugin.h>`_.
+The enums below are defined in `mjplugin.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjplugin.h>`__.
 See :ref:`exPlugin` for details.
 
 
@@ -994,6 +1059,348 @@ is initialized, others change at runtime.
 .. mujoco-include:: mjUI
 
 
+
+.. _tySpecStructure:
+
+mjSpec
+^^^^^^
+
+The strucs below are defined in `mjspec.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjspec.h>`__
+and, with the exception of the top level :ref:`mjSpec` struct, begin with the ``mjs`` prefix.
+For more details, see the :doc:`Model Editing <../programming/modeledit>` chapter.
+
+.. _mjSpec:
+
+mjSpec
+~~~~~~
+
+Model specification.
+
+.. mujoco-include:: mjSpec
+
+
+.. _mjsElement:
+
+mjsElement
+~~~~~~~~~~
+
+Special type corresponding to any element.
+
+.. mujoco-include:: mjsElement
+
+
+.. _mjsOrientation:
+
+mjsOrientation
+~~~~~~~~~~~~~~
+
+Alternative orientation specifiers.
+
+.. mujoco-include:: mjsOrientation
+
+
+.. _mjsBody:
+
+mjsBody
+~~~~~~~
+
+Body specification.
+
+.. mujoco-include:: mjsBody
+
+
+.. _mjsFrame:
+
+mjsFrame
+~~~~~~~~
+
+Frame specification.
+
+.. mujoco-include:: mjsFrame
+
+
+.. _mjsJoint:
+
+mjsJoint
+~~~~~~~~
+
+Joint specification.
+
+.. mujoco-include:: mjsJoint
+
+
+.. _mjsGeom:
+
+mjsGeom
+~~~~~~~
+
+Geom specification.
+
+.. mujoco-include:: mjsGeom
+
+
+.. _mjsSite:
+
+mjsSite
+~~~~~~~
+
+Site specification.
+
+.. mujoco-include:: mjsSite
+
+
+.. _mjsCamera:
+
+mjsCamera
+~~~~~~~~~
+
+Camera specification.
+
+.. mujoco-include:: mjsCamera
+
+
+.. _mjsLight:
+
+mjsLight
+~~~~~~~~
+
+Light specification.
+
+.. mujoco-include:: mjsLight
+
+
+.. _mjsFlex:
+
+mjsFlex
+~~~~~~~
+
+Flex specification.
+
+.. mujoco-include:: mjsFlex
+
+
+.. _mjsMesh:
+
+mjsMesh
+~~~~~~~
+
+Mesh specification.
+
+.. mujoco-include:: mjsMesh
+
+
+.. _mjsHField:
+
+mjsHField
+~~~~~~~~~
+
+Height field specification.
+
+.. mujoco-include:: mjsHField
+
+
+.. _mjsSkin:
+
+mjsSkin
+~~~~~~~
+
+Skin specification.
+
+.. mujoco-include:: mjsSkin
+
+
+.. _mjsTexture:
+
+mjsTexture
+~~~~~~~~~~
+
+Texture specification.
+
+.. mujoco-include:: mjsTexture
+
+
+.. _mjsMaterial:
+
+mjsMaterial
+~~~~~~~~~~~
+
+Material specification.
+
+.. mujoco-include:: mjsMaterial
+
+
+.. _mjsPair:
+
+mjsPair
+~~~~~~~
+
+Pair specification.
+
+.. mujoco-include:: mjsPair
+
+
+.. _mjsExclude:
+
+mjsExclude
+~~~~~~~~~~
+
+Exclude specification.
+
+.. mujoco-include:: mjsExclude
+
+
+.. _mjsEquality:
+
+mjsEquality
+~~~~~~~~~~~
+
+Equality specification.
+
+.. mujoco-include:: mjsEquality
+
+
+.. _mjsTendon:
+
+mjsTendon
+~~~~~~~~~
+
+Tendon specification.
+
+.. mujoco-include:: mjsTendon
+
+
+.. _mjsWrap:
+
+mjsWrap
+~~~~~~~
+
+Wrapping object specification.
+
+.. mujoco-include:: mjsWrap
+
+
+.. _mjsActuator:
+
+mjsActuator
+~~~~~~~~~~~
+
+Actuator specification.
+
+.. mujoco-include:: mjsActuator
+
+
+.. _mjsSensor:
+
+mjsSensor
+~~~~~~~~~
+
+Sensor specification.
+
+.. mujoco-include:: mjsSensor
+
+
+.. _mjsNumeric:
+
+mjsNumeric
+~~~~~~~~~~
+
+Custom numeric field specification.
+
+.. mujoco-include:: mjsNumeric
+
+
+.. _mjsText:
+
+mjsText
+~~~~~~~
+
+Custom text specification.
+
+.. mujoco-include:: mjsText
+
+
+.. _mjsTuple:
+
+mjsTuple
+~~~~~~~~
+
+Tuple specification.
+
+.. mujoco-include:: mjsTuple
+
+
+.. _mjsKey:
+
+mjsKey
+~~~~~~
+
+Keyframe specification.
+
+.. mujoco-include:: mjsKey
+
+
+.. _mjsDefault:
+
+mjsDefault
+~~~~~~~~~~
+
+Default specification.
+
+.. mujoco-include:: mjsDefault
+
+
+.. _mjsPlugin:
+
+mjsPlugin
+~~~~~~~~~
+
+Plugin specification.
+
+.. mujoco-include:: mjsPlugin
+
+
+.. _mjString:
+
+.. _mjStringVec:
+
+.. _mjIntVec:
+
+.. _mjIntVecVec:
+
+.. _mjFloatVec:
+
+.. _mjFloatVecVec:
+
+.. _mjDoubleVec:
+
+Array handles
+~~~~~~~~~~~~~
+
+Explain how handles work.
+
+.. code-block:: C++
+
+   #ifdef __cplusplus
+     // C++: defined to be compatible with corresponding std types
+     using mjString      = std::string;
+     using mjStringVec   = std::vector<std::string>;
+     using mjIntVec      = std::vector<int>;
+     using mjIntVecVec   = std::vector<std::vector<int>>;
+     using mjFloatVec    = std::vector<float>;
+     using mjFloatVecVec = std::vector<std::vector<float>>;
+     using mjDoubleVec   = std::vector<double>;
+   #else
+     // C: opaque types
+     typedef void mjString;
+     typedef void mjStringVec;
+     typedef void mjIntVec;
+     typedef void mjIntVecVec;
+     typedef void mjFloatVec;
+     typedef void mjFloatVecVec;
+     typedef void mjDoubleVec;
+   #endif
+
+
 .. _tyPluginStructure:
 
 Plugins
@@ -1028,8 +1435,8 @@ Function types
 --------------
 
 MuJoCo callbacks have corresponding function types. They are defined in `mjdata.h
-<https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`_ and in `mjui.h
-<https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`_. The actual callback functions are documented
+<https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h>`__ and in `mjui.h
+<https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjui.h>`__. The actual callback functions are documented
 in the :doc:`globals<APIglobals>` page.
 
 

doc/APIreference/functions_override.rst

@@ -312,7 +312,7 @@ depending on which UI item was modified and what the state of that item is after
 
 This function is called in the screen refresh loop. It copies the offscreen OpenGL buffer to the window framebuffer. If
 there are multiple UIs in the application, it should be called once for each UI. Thus ``mjui_render`` is called all the
-time, while :ref:`mjui_update` is called only when changes in the UI take place.
+time, while :ref:`mjui_update` is called only when changes in the UI take place. dsffsdg
 
 
 
@@ -545,7 +545,7 @@ Finite-differenced discrete-time transition matrices.
 
 Letting :math:`x, u` denote the current :ref:`state<gePhysicsState>` and :ref:`control<geInput>`
 vector in an mjData instance, and letting :math:`y, s` denote the next state and sensor
-values, the top-level :ref:`mj_step` function computes :math:`(x,u) \rightarrow (y,s)`.
+values, the top-level :ref:`mj_step` function computes :math:`(x,u) \rightarrow (y,s)`
 :ref:`mjd_transitionFD` computes the four associated Jacobians using finite-differencing.
 These matrices and their dimensions are:
 
@@ -623,3 +623,8 @@ to the inputs. Below, :math:`\bar q` denotes the pre-modified quaternion:
 
 Note that derivatives depend only on :math:`h` and :math:`v` (in fact, on :math:`s = h v`).
 All outputs are optional.
+
+.. _SpecManip:
+
+These functions provide high level manipulation for :ref:`mjSpec` structs, which represent an uncompiled :ref:`mjModel`.
+

doc/changelog.rst

@@ -7,16 +7,21 @@ Upcoming version (not yet released)
 
 General
 ^^^^^^^
+1. Added a new API for :doc:`procedural model manipulation<programming/modeledit>`. Fixes :github:issue:`364`.
+   Still missing:
+
+   - Detailed documentation.
+   - Python bindings.
+
+2. Added :ref:`maxhullvert<asset-mesh-maxhullvert>`, the maximum number of vertices in a mesh's convex hull.
 
-1. Added :ref:`maxhullvert<asset-mesh-maxhullvert>`, the maximum number of vertices in a mesh's convex hull.
 
 MJX
 ~~~
 
-2. Added support for :ref:`elliptic friction cones<option-cone>`.
-3. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
-4. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.
-
+3. Added support for :ref:`elliptic friction cones<option-cone>`.
+4. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
+5. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.
 
 Version 3.1.6 (Jun 3, 2024)
 ---------------------------
@@ -731,13 +736,13 @@ General
    Previously, the smooth part consisted of two stitched quadratics, once continuously differentiable.
    It is now a single quintic, twice continuously differentiable:
 
-  .. math::
-     s(x) =
-     \begin{cases}
-        0,                    &       & x \le 0  \\
-        6x^5 - 15x^4 + 10x^3, & 0 \lt & x \lt 1  \\
-        1,                    & 1 \le & x \qquad
-     \end{cases}
+   .. math::
+      s(x) =
+      \begin{cases}
+         0,                    &       & x \le 0  \\
+         6x^5 - 15x^4 + 10x^3, & 0 \lt & x \lt 1  \\
+         1,                    & 1 \le & x \qquad
+      \end{cases}
 
 17. Added optional :ref:`tausmooth<actuator-muscle-tausmooth>` attribute to muscle actuators. When positive, the
     time-constant :math:`\tau` of muscle activation/deactivation uses :ref:`mju_sigmoid` to transition smoothly

doc/css/theme_overrides.css

@@ -266,6 +266,14 @@ dt .at {
   margin-bottom: 0.3em;
 }
 
+/* Adjust margins around code blocks */
+.highlight pre {
+  margin-top: -0.3em;
+  margin-bottom: -0.3em;
+  margin-left: -0.5em;
+  margin-right: -0.5em;
+}
+
 details summary {
   font-weight: 600;
 }

doc/includes/references.h

@@ -1598,6 +1598,637 @@ struct mjrContext_ {              // custom OpenGL context
   int     readDepthMap;           // depth mapping: mjDEPTH_ZERONEAR or mjDEPTH_ZEROFAR
 };
 typedef struct mjrContext_ mjrContext;
+typedef enum mjtGeomInertia_ {     // type of inertia inference
+  mjINERTIA_VOLUME,                // mass distributed in the volume
+  mjINERTIA_SHELL,                 // mass distributed on the surface
+} mjtGeomInertia;
+typedef enum mjtBuiltin_ {         // type of built-in procedural texture
+  mjBUILTIN_NONE = 0,              // no built-in texture
+  mjBUILTIN_GRADIENT,              // gradient: rgb1->rgb2
+  mjBUILTIN_CHECKER,               // checker pattern: rgb1, rgb2
+  mjBUILTIN_FLAT                   // 2d: rgb1; cube: rgb1-up, rgb2-side, rgb3-down
+} mjtBuiltin;
+typedef enum mjtMark_ {            // mark type for procedural textures
+  mjMARK_NONE = 0,                 // no mark
+  mjMARK_EDGE,                     // edges
+  mjMARK_CROSS,                    // cross
+  mjMARK_RANDOM                    // random dots
+} mjtMark;
+typedef enum mjtLimited_ {         // type of limit specification
+  mjLIMITED_FALSE = 0,             // not limited
+  mjLIMITED_TRUE,                  // limited
+  mjLIMITED_AUTO,                  // limited inferred from presence of range
+} mjtLimited;
+typedef enum mjtInertiaFromGeom_ { // whether to infer body inertias from child geoms
+  mjINERTIAFROMGEOM_FALSE = 0,     // do not use; inertial element required
+  mjINERTIAFROMGEOM_TRUE,          // always use; overwrite inertial element
+  mjINERTIAFROMGEOM_AUTO           // use only if inertial element is missing
+} mjtInertiaFromGeom;
+typedef enum mjtOrientation_ {     // type of orientation specifier
+  mjORIENTATION_QUAT = 0,          // quaternion
+  mjORIENTATION_AXISANGLE,         // axis and angle
+  mjORIENTATION_XYAXES,            // x and y axes
+  mjORIENTATION_ZAXIS,             // z axis (minimal rotation)
+  mjORIENTATION_EULER,             // Euler angles
+} mjtOrientation;
+typedef struct mjsElement_ {       // element type, do not modify
+  mjtObj elemtype;                 // element type
+} mjsElement;
+typedef struct mjSpec_ {           // model specification
+  mjsElement* element;             // element type
+  mjString* modelname;             // model name
+
+  // compiler settings
+  mjtByte autolimits;              // infer "limited" attribute based on range
+  double boundmass;                // enforce minimum body mass
+  double boundinertia;             // enforce minimum body diagonal inertia
+  double settotalmass;             // rescale masses and inertias; <=0: ignore
+  mjtByte balanceinertia;          // automatically impose A + B >= C rule
+  mjtByte strippath;               // automatically strip paths from mesh files
+  mjtByte fitaabb;                 // meshfit to aabb instead of inertia box
+  mjtByte degree;                  // angles in radians or degrees
+  char euler[3];                   // sequence for euler rotations
+  mjString* meshdir;               // mesh and hfield directory
+  mjString* texturedir;            // texture directory
+  mjtByte discardvisual;           // discard visual geoms in parser
+  mjtByte convexhull;              // compute mesh convex hulls
+  mjtByte usethread;               // use multiple threads to speed up compiler
+  mjtByte fusestatic;              // fuse static bodies with parent
+  int inertiafromgeom;             // use geom inertias (mjtInertiaFromGeom)
+  int inertiagrouprange[2];        // range of geom groups used to compute inertia
+  mjtByte exactmeshinertia;        // if false, use old formula
+  mjLROpt LRopt;                   // options for lengthrange computation
+
+  // engine data
+  mjOption option;                 // physics options
+  mjVisual visual;                 // visual options
+  mjStatistic stat;                // statistics override (if defined)
+
+  // sizes
+  size_t memory;                   // number of bytes in arena+stack memory
+  int nemax;                       // max number of equality constraints
+  int nuserdata;                   // number of mjtNums in userdata
+  int nuser_body;                  // number of mjtNums in body_user
+  int nuser_jnt;                   // number of mjtNums in jnt_user
+  int nuser_geom;                  // number of mjtNums in geom_user
+  int nuser_site;                  // number of mjtNums in site_user
+  int nuser_cam;                   // number of mjtNums in cam_user
+  int nuser_tendon;                // number of mjtNums in tendon_user
+  int nuser_actuator;              // number of mjtNums in actuator_user
+  int nuser_sensor;                // number of mjtNums in sensor_user
+  int nkey;                        // number of keyframes
+  int njmax;                       // (deprecated) max number of constraints
+  int nconmax;                     // (deprecated) max number of detected contacts
+  size_t nstack;                   // (deprecated) number of mjtNums in mjData stack
+
+  // global data
+  mjString* comment;               // comment at top of XML
+  mjString* modelfiledir;          // path to model file
+
+  // other
+  mjtByte hasImplicitPluginElem;   // already encountered an implicit plugin sensor/actuator
+} mjSpec;
+typedef struct mjsOrientation_ {   // alternative orientation specifiers
+  mjtOrientation type;             // active orientation specifier
+  double axisangle[4];             // axis and angle
+  double xyaxes[6];                // x and y axes
+  double zaxis[3];                 // z axis (minimal rotation)
+  double euler[3];                 // Euler angles
+} mjsOrientation;
+typedef struct mjsPlugin_ {        // plugin specification
+  mjsElement* instance;            // element type
+  mjString* name;                  // name
+  mjString* instance_name;         // instance name
+  int plugin_slot;                 // global registered slot number of the plugin
+  mjtByte active;                  // is the plugin active
+  mjString* info;                  // message appended to compiler errors
+} mjsPlugin;
+typedef struct mjsBody_ {          // body specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* childclass;            // childclass name
+
+  // body frame
+  double pos[3];                   // frame position
+  double quat[4];                  // frame orientation
+  mjsOrientation alt;              // frame alternative orientation
+
+  // inertial frame
+  double mass;                     // mass
+  double ipos[3];                  // inertial frame position
+  double iquat[4];                 // inertial frame orientation
+  double inertia[3];               // diagonal inertia (in i-frame)
+  mjsOrientation ialt;             // inertial frame alternative orientation
+  double fullinertia[6];           // non-axis-aligned inertia matrix
+
+  // other
+  mjtByte mocap;                   // is this a mocap body
+  double gravcomp;                 // gravity compensation
+  mjDoubleVec* userdata;           // user data
+  mjtByte explicitinertial;        // whether to save the body with explicit inertial clause
+  mjsPlugin plugin;                // passive force plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsBody;
+typedef struct mjsFrame_ {         // frame specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* childclass;            // childclass name
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  mjString* info;                  // message appended to compiler errors
+} mjsFrame;
+typedef struct mjsJoint_ {         // joint specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjtJoint type;                   // joint type
+
+  // kinematics
+  double pos[3];                   // anchor position
+  double axis[3];                  // joint axis
+  double ref;                      // value at reference configuration: qpos0
+
+  // stiffness
+  double stiffness;                // stiffness coefficient
+  double springref;                // spring reference value: qpos_spring
+  double springdamper[2];          // timeconst, dampratio
+
+  // limits
+  int limited;                     // does joint have limits (mjtLimited)
+  double range[2];                 // joint limits
+  double margin;                   // margin value for joint limit detection
+  mjtNum solref_limit[mjNREF];     // solver reference: joint limits
+  mjtNum solimp_limit[mjNIMP];     // solver impedance: joint limits
+  int actfrclimited;               // are actuator forces on joint limited (mjtLimited)
+  double actfrcrange[2];           // actuator force limits
+
+  // dof properties
+  double armature;                 // armature inertia (mass for slider)
+  double damping;                  // damping coefficient
+  double frictionloss;             // friction loss
+  mjtNum solref_friction[mjNREF];  // solver reference: dof friction
+  mjtNum solimp_friction[mjNIMP];  // solver impedance: dof friction
+
+  // other
+  int group;                       // group
+  mjtByte actgravcomp;             // is gravcomp force applied via actuators
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to compiler errors
+} mjsJoint;
+typedef struct mjsGeom_ {          // geom specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // classname
+  mjtGeom type;                    // geom type
+
+  // frame, size
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  double fromto[6];                // alternative for capsule, cylinder, box, ellipsoid
+  double size[3];                  // type-specific size
+
+  // contact related
+  int contype;                     // contact type
+  int conaffinity;                 // contact affinity
+  int condim;                      // contact dimensionality
+  int priority;                    // contact priority
+  double friction[3];              // one-sided friction coefficients: slide, roll, spin
+  double solmix;                   // solver mixing for contact pairs
+  mjtNum solref[mjNREF];           // solver reference
+  mjtNum solimp[mjNIMP];           // solver impedance
+  double margin;                   // margin for contact detection
+  double gap;                      // include in solver if dist < margin-gap
+
+  // inertia inference
+  double mass;                     // used to compute density
+  double density;                  // used to compute mass and inertia from volume or surface
+  mjtGeomInertia typeinertia;      // selects between surface and volume inertia
+
+  // fluid forces
+  mjtNum fluid_ellipsoid;          // whether ellipsoid-fluid model is active
+  mjtNum fluid_coefs[5];           // ellipsoid-fluid interaction coefs
+
+  // visual
+  mjString* material;              // name of material
+  float rgba[4];                   // rgba when material is omitted
+  int group;                       // group
+
+  // other
+  mjString* hfieldname;            // heightfield attached to geom
+  mjString* meshname;              // mesh attached to geom
+  double fitscale;                 // scale mesh uniformly
+  mjDoubleVec* userdata;           // user data
+  mjsPlugin plugin;                // sdf plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsGeom;
+typedef struct mjsSite_ {          // site specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // frame, size
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  double fromto[6];                // alternative for capsule, cylinder, box, ellipsoid
+  double size[3];                  // geom size
+
+  // visual
+  mjtGeom type;                    // geom type
+  mjString* material;              // name of material
+  int group;                       // group
+  float rgba[4];                   // rgba when material is omitted
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to compiler errors
+} mjsSite;
+typedef struct mjsCamera_ {        // camera specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // extrinsics
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  mjtCamLight mode;                // tracking mode
+  mjString* targetbody;            // target body for tracking/targeting
+
+  // intrinsics
+  double fovy;                     // y-field of view
+  double ipd;                      // inter-pupilary distance
+  float intrinsic[4];              // camera intrinsics (length)
+  float sensor_size[2];            // sensor size (length)
+  float resolution[2];             // resolution (pixel)
+  float focal_length[2];           // focal length (length)
+  float focal_pixel[2];            // focal length (pixel)
+  float principal_length[2];       // principal point (length)
+  float principal_pixel[2];        // principal point (pixel)
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to compiler errors
+} mjsCamera;
+typedef struct mjsLight_ {         // light specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // frame
+  double pos[3];                   // position
+  double dir[3];                   // direction
+  mjtCamLight mode;                // tracking mode
+  mjString* targetbody;            // target body for targeting
+
+  // intrinsics
+  mjtByte active;                  // is light active
+  mjtByte directional;             // is light directional or spot
+  mjtByte castshadow;              // does light cast shadows
+  double bulbradius;               // bulb radius, for soft shadows
+  float attenuation[3];            // OpenGL attenuation (quadratic model)
+  float cutoff;                    // OpenGL cutoff
+  float exponent;                  // OpenGL exponent
+  float ambient[3];                // ambient color
+  float diffuse[3];                // diffuse color
+  float specular[3];               // specular color
+
+  // other
+  mjString* info;                  // message appended to compiler errorsx
+} mjsLight;
+typedef struct mjsFlex_ {          // flex specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // contact properties
+  int contype;                     // contact type
+  int conaffinity;                 // contact affinity
+  int condim;                      // contact dimensionality
+  int priority;                    // contact priority
+  double friction[3];              // one-sided friction coefficients: slide, roll, spin
+  double solmix;                   // solver mixing for contact pairs
+  mjtNum solref[mjNREF];           // solver reference
+  mjtNum solimp[mjNIMP];           // solver impedance
+  double margin;                   // margin for contact detection
+  double gap;                      // include in solver if dist<margin-gap
+
+  // other properties
+  int dim;                         // element dimensionality
+  double radius;                   // radius around primitive element
+  mjtByte internal;                // enable internal collisions
+  mjtByte flatskin;                // render flex skin with flat shading
+  int selfcollide;                 // mode for flex self colllision
+  int activelayers;                // number of active element layers in 3D
+  int group;                       // group for visualizatioh
+  double edgestiffness;            // edge stiffness
+  double edgedamping;              // edge damping
+  float rgba[4];                   // rgba when material is omitted
+  mjString* material;              // name of material used for rendering
+
+  // mesh properties
+  mjStringVec* vertbody;           // vertex body names
+  mjDoubleVec* vert;               // vertex positions
+  mjIntVec* elem;                  // element vertex ids
+  mjFloatVec* texcoord;            // vertex texture coordinates
+
+  // other
+  mjString* info;                  // message appended to compiler errors
+} mjsFlex;
+typedef struct mjsMesh_ {          // mesh specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* content_type;          // content type of file
+  mjString* file;                  // mesh file
+  double refpos[3];                // reference position
+  double refquat[4];               // reference orientation
+  double scale[3];                 // rescale mesh
+  mjtByte smoothnormal;            // do not exclude large-angle faces from normals
+  int maxhullvert;                 // maximum vertex count for the convex hull
+  mjFloatVec* uservert;            // user vertex data
+  mjFloatVec* usernormal;          // user normal data
+  mjFloatVec* usertexcoord;        // user texcoord data
+  mjIntVec* userface;              // user vertex indices
+  mjIntVec* userfacenormal;        // user normal indices
+  mjIntVec* userfacetexcoord;      // user texcoord indices
+  mjsPlugin plugin;                // sdf plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsMesh;
+typedef struct mjsHField_ {        // height field specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* content_type;          // content type of file
+  mjString* file;                  // file: (nrow, ncol, [elevation data])
+  double size[4];                  // hfield size (ignore referencing geom size)
+  int nrow;                        // number of rows
+  int ncol;                        // number of columns
+  mjFloatVec* userdata;            // user-provided elevation data
+  mjString* info;                  // message appended to compiler errors
+} mjsHField;
+typedef struct mjsSkin_ {          // skin specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* file;                  // skin file
+  mjString* material;              // name of material used for rendering
+  float rgba[4];                   // rgba when material is omitted
+  float inflate;                   // inflate in normal direction
+  int group;                       // group for visualization
+
+  // mesh
+  mjFloatVec* vert;                // vertex positions
+  mjFloatVec* texcoord;            // texture coordinates
+  mjIntVec* face;                  // faces
+
+  // skin
+  mjStringVec* bodyname;           // body names
+  mjFloatVec* bindpos;             // bind pos
+  mjFloatVec* bindquat;            // bind quat
+  mjIntVecVec* vertid;             // vertex ids
+  mjFloatVecVec* vertweight;       // vertex weights
+
+  // other
+  mjString* info;                  // message appended to compiler errors
+} mjsSkin;
+typedef struct mjsTexture_ {       // texture specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjtTexture type;                 // texture type
+
+  // method 1: builtin
+  int builtin;                     // builtin type (mjtBuiltin)
+  int mark;                        // mark type (mjtMark)
+  double rgb1[3];                  // first color for builtin
+  double rgb2[3];                  // second color for builtin
+  double markrgb[3];               // mark color
+  double random;                   // probability of random dots
+  int height;                      // height in pixels (square for cube and skybox)
+  int width;                       // width in pixels
+
+  // method 2: single file
+  mjString* content_type;          // content type of file
+  mjString* file;                  // png file to load; use for all sides of cube
+  int gridsize[2];                 // size of grid for composite file; (1,1)-repeat
+  char gridlayout[13];             // row-major: L,R,F,B,U,D for faces; . for unused
+
+  // method 3: separate files
+  mjStringVec* cubefiles;          // different file for each side of the cube
+
+  // flip options
+  mjtByte hflip;                   // horizontal flip
+  mjtByte vflip;                   // vertical flip
+
+  // other
+  mjString* info;                  // message appended to compiler errors
+} mjsTexture;
+typedef struct mjsMaterial_ {      // material specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* texture;               // name of texture (empty: none)
+  mjtByte texuniform;              // make texture cube uniform
+  float texrepeat[2];              // texture repetition for 2D mapping
+  float emission;                  // emission
+  float specular;                  // specular
+  float shininess;                 // shininess
+  float reflectance;               // reflectance
+  float metallic;                  // metallic
+  float roughness;                 // roughness
+  float rgba[4];                   // rgba
+  mjString* info;                  // message appended to compiler errors
+} mjsMaterial;
+typedef struct mjsPair_ {          // pair specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* geomname1;             // name of geom 1
+  mjString* geomname2;             // name of geom 2
+
+  // optional parameters: computed from geoms if not set by user
+  int condim;                      // contact dimensionality
+  mjtNum solref[mjNREF];           // solver reference, normal direction
+  mjtNum solreffriction[mjNREF];   // solver reference, frictional directions
+  mjtNum solimp[mjNIMP];           // solver impedance
+  double margin;                   // margin for contact detection
+  double gap;                      // include in solver if dist<margin-gap
+  double friction[5];              // full contact friction
+  mjString* info;                  // message appended to errors
+} mjsPair;
+typedef struct mjsExclude_ {       // exclude specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* bodyname1;             // name of geom 1
+  mjString* bodyname2;             // name of geom 2
+  mjString* info;                  // message appended to errors
+} mjsExclude;
+typedef struct mjsEquality_ {      // equality specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjtEq type;                      // constraint type
+  double data[mjNEQDATA];          // type-dependent data
+  mjtByte active;                  // is equality initially active
+  mjString* name1;                 // name of object 1
+  mjString* name2;                 // name of object 2
+  mjtNum solref[mjNREF];           // solver reference
+  mjtNum solimp[mjNIMP];           // solver impedance
+  mjString* info;                  // message appended to errors
+} mjsEquality;
+typedef struct mjsTendon_ {        // tendon specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // stiffness, damping, friction
+  double stiffness;                // stiffness coefficient
+  double springlength[2];          // spring resting length; {-1, -1}: use qpos_spring
+  double damping;                  // damping coefficient
+  double frictionloss;             // friction loss
+  mjtNum solref_friction[mjNREF];  // solver reference: tendon friction
+  mjtNum solimp_friction[mjNIMP];  // solver impedance: tendon friction
+
+  // length range
+  int limited;                     // does tendon have limits (mjtLimited)
+  double range[2];                 // length limits
+  double margin;                   // margin value for tendon limit detection
+  mjtNum solref_limit[mjNREF];     // solver reference: tendon limits
+  mjtNum solimp_limit[mjNIMP];     // solver impedance: tendon limits
+
+  // visual
+  mjString* material;              // name of material for rendering
+  double width;                    // width for rendering
+  float rgba[4];                   // rgba when material is omitted
+  int group;                       // group
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to errors
+} mjsTendon;
+typedef struct mjsWrap_ {          // wrapping object specification
+  mjsElement* element;             // element type
+  mjString* info;                  // message appended to errors
+} mjsWrap;
+typedef struct mjsActuator_ {      // actuator specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // gain, bias
+  mjtGain gaintype;                // gain type
+  double gainprm[mjNGAIN];         // gain parameters
+  mjtBias biastype;                // bias type
+  double biasprm[mjNGAIN];         // bias parameters
+
+  // activation state
+  mjtDyn dyntype;                  // dynamics type
+  double dynprm[mjNDYN];           // dynamics parameters
+  int actdim;                      // number of activation variables
+  int plugin_actdim;               // actuator state size for plugins
+  mjtByte actearly;                // apply next activations to qfrc
+
+  // transmission
+  mjtTrn trntype;                  // transmission type
+  double gear[6];                  // length and transmitted force scaling
+  mjString* target;                // name of transmission target
+  mjString* refsite;               // reference site, for site transmission
+  mjString* slidersite;            // site defining cylinder, for slider-crank
+  double cranklength;              // crank length, for slider-crank
+  double lengthrange[2];           // transmission length range
+  double inheritrange;             // automatic range setting for position and intvelocity
+
+  // input/output clamping
+  int ctrllimited;                 // are control limits defined (mjtLimited)
+  double ctrlrange[2];             // control range
+  int forcelimited;                // are force limits defined (mjtLimited)
+  double forcerange[2];            // force range
+  int actlimited;                  // are activation limits defined (mjtLimited)
+  double actrange[2];              // activation range
+
+  // other
+  int group;                       // group
+  mjDoubleVec* userdata;           // user data
+  mjsPlugin plugin;                // actuator plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsActuator;
+typedef struct mjsSensor_ {        // sensor specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // sensor definition
+  mjtSensor type;                  // type of sensor
+  mjtObj objtype;                  // type of sensorized object
+  mjString* objname;               // name of sensorized object
+  mjtObj reftype;                  // type of referenced object
+  mjString* refname;               // name of referenced object
+
+  // user-defined sensors
+  mjtDataType datatype;            // data type for sensor measurement
+  mjtStage needstage;              // compute stage needed to simulate sensor
+  int dim;                         // number of scalar outputs
+
+  // output post-processing
+  double cutoff;                   // cutoff for real and positive datatypes
+  double noise;                    // noise stdev
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjsPlugin plugin;                // sensor plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsSensor;
+typedef struct mjsNumeric_ {       // custom numeric field specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjDoubleVec* data;               // initialization data
+  int size;                        // array size, can be bigger than data size
+  mjString* info;                  // message appended to compiler errors
+} mjsNumeric;
+typedef struct mjsText_ {          // custom text specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* data;                  // text string
+  mjString* info;                  // message appended to compiler errors
+} mjsText;
+typedef struct mjsTuple_ {         // tuple specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjIntVec* objtype;               // object types
+  mjStringVec* objname;            // object names
+  mjDoubleVec* objprm;             // object parameters
+  mjString* info;                  // message appended to compiler errors
+} mjsTuple;
+typedef struct mjsKey_ {           // keyframe specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  double time;                     // time
+  mjDoubleVec* qpos;               // qpos
+  mjDoubleVec* qvel;               // qvel
+  mjDoubleVec* act;                // act
+  mjDoubleVec* mpos;               // mocap pos
+  mjDoubleVec* mquat;              // mocap quat
+  mjDoubleVec* ctrl;               // ctrl
+  mjString* info;                  // message appended to compiler errors
+} mjsKey;
+typedef struct mjsDefault_ {       // default specification
+  mjsElement* element;             // element type
+  mjString* name;                  // class name
+  mjsJoint* joint;                 // joint defaults
+  mjsGeom* geom;                   // geom defaults
+  mjsSite* site;                   // site defaults
+  mjsCamera* camera;               // camera defaults
+  mjsLight* light;                 // light defaults
+  mjsFlex* flex;                   // flex defaults
+  mjsMesh* mesh;                   // mesh defaults
+  mjsMaterial* material;           // material defaults
+  mjsPair* pair;                   // pair defaults
+  mjsEquality* equality;           // equality defaults
+  mjsTendon* tendon;               // tendon defaults
+  mjsActuator* actuator;           // actuator defaults
+} mjsDefault;
 typedef enum mjtTaskStatus_ {  // status values for mjTask
   mjTASK_NEW = 0,              // newly created
   mjTASK_QUEUED,               // enqueued in a thread pool
@@ -2431,10 +3062,15 @@ int mj_deleteFileVFS(mjVFS* vfs, const char* filename);
 void mj_deleteVFS(mjVFS* vfs);
 int mj_makeEmptyFileVFS(mjVFS* vfs, const char* filename, int filesize);
 mjModel* mj_loadXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
+mjSpec* mj_parseXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
+mjSpec* mj_parseXMLString(const char* xml, const mjVFS* vfs, char* error, int error_sz);
+mjModel* mj_compile(mjSpec* s, const mjVFS* vfs);
+void mj_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d);
 int mj_saveLastXML(const char* filename, const mjModel* m, char* error, int error_sz);
 void mj_freeLastXML(void);
-int mj_printSchema(const char* filename, char* buffer, int buffer_sz,
-                   int flg_html, int flg_pad);
+void mj_copyBack(mjSpec* s, const mjModel* m);
+int mj_saveXMLString(const mjSpec* s, char* xml, int xml_sz, char* error, int error_sz);
+int mj_saveXML(const mjSpec* s, const char* filename, char* error, int error_sz);
 void mj_step(const mjModel* m, mjData* d);
 void mj_step1(const mjModel* m, mjData* d);
 void mj_step2(const mjModel* m, mjData* d);
@@ -2466,6 +3102,9 @@ void mj_resetCallbacks(void);
 void mj_setConst(mjModel* m, mjData* d);
 int mj_setLengthRange(mjModel* m, mjData* d, int index,
                       const mjLROpt* opt, char* error, int error_sz);
+mjSpec* mj_makeSpec(void);
+mjSpec* mj_copySpec(const mjSpec* s);
+void mj_deleteSpec(mjSpec* s);
 void mj_printFormattedModel(const mjModel* m, const char* filename, const char* float_format);
 void mj_printModel(const mjModel* m, const char* filename);
 void mj_printFormattedData(const mjModel* m, mjData* d, const char* filename,
@@ -2474,6 +3113,8 @@ void mj_printData(const mjModel* m, mjData* d, const char* filename);
 void mju_printMat(const mjtNum* mat, int nr, int nc);
 void mju_printMatSparse(const mjtNum* mat, int nr,
                         const int* rownnz, const int* rowadr, const int* colind);
+int mj_printSchema(const char* filename, char* buffer, int buffer_sz,
+                   int flg_html, int flg_pad);
 void mj_fwdPosition(const mjModel* m, mjData* d);
 void mj_fwdVelocity(const mjModel* m, mjData* d);
 void mj_fwdActuation(const mjModel* m, mjData* d);
@@ -2695,6 +3336,8 @@ void* mju_malloc(size_t size);
 void mju_free(void* ptr);
 void mj_warning(mjData* d, int warning, int info);
 void mju_writeLog(const char* type, const char* msg);
+const char* mjs_getError(mjSpec* s);
+int mjs_isWarning(mjSpec* s);
 void mju_zero3(mjtNum res[3]);
 void mju_copy3(mjtNum res[3], const mjtNum data[3]);
 void mju_scl3(mjtNum res[3], const mjtNum vec[3], mjtNum scl);
@@ -2838,4 +3481,94 @@ void mju_threadPoolEnqueue(mjThreadPool* thread_pool, mjTask* task);
 void mju_threadPoolDestroy(mjThreadPool* thread_pool);
 void mju_defaultTask(mjTask* task);
 void mju_taskJoin(mjTask* task);
+int mjs_attachBody(mjsFrame* parent, const mjsBody* child,
+                   const char* prefix, const char* suffix);
+int mjs_attachFrame(mjsBody* parent, const mjsFrame* child,
+                    const char* prefix, const char* suffix);
+int mjs_detachBody(mjSpec* s, mjsBody* b);
+mjsBody* mjs_addBody(mjsBody* body, mjsDefault* def);
+mjsSite* mjs_addSite(mjsBody* body, mjsDefault* def);
+mjsJoint* mjs_addJoint(mjsBody* body, mjsDefault* def);
+mjsJoint* mjs_addFreeJoint(mjsBody* body);
+mjsGeom* mjs_addGeom(mjsBody* body, mjsDefault* def);
+mjsCamera* mjs_addCamera(mjsBody* body, mjsDefault* def);
+mjsLight* mjs_addLight(mjsBody* body, mjsDefault* def);
+mjsFrame* mjs_addFrame(mjsBody* body, mjsFrame* parentframe);
+void mjs_delete(mjsElement* element);
+mjsActuator* mjs_addActuator(mjSpec* s, mjsDefault* def);
+mjsSensor* mjs_addSensor(mjSpec* s);
+mjsFlex* mjs_addFlex(mjSpec* s);
+mjsPair* mjs_addPair(mjSpec* s, mjsDefault* def);
+mjsExclude* mjs_addExclude(mjSpec* s);
+mjsEquality* mjs_addEquality(mjSpec* s, mjsDefault* def);
+mjsTendon* mjs_addTendon(mjSpec* s, mjsDefault* def);
+mjsWrap* mjs_wrapSite(mjsTendon* tendon, const char* name);
+mjsWrap* mjs_wrapGeom(mjsTendon* tendon, const char* name, const char* sidesite);
+mjsWrap* mjs_wrapJoint(mjsTendon* tendon, const char* name, double coef);
+mjsWrap* mjs_wrapPulley(mjsTendon* tendon, double divisor);
+mjsNumeric* mjs_addNumeric(mjSpec* s);
+mjsText* mjs_addText(mjSpec* s);
+mjsTuple* mjs_addTuple(mjSpec* s);
+mjsKey* mjs_addKey(mjSpec* s);
+mjsPlugin* mjs_addPlugin(mjSpec* s);
+mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, int parentid, int* id);
+mjsMesh* mjs_addMesh(mjSpec* s, mjsDefault* def);
+mjsHField* mjs_addHField(mjSpec* s);
+mjsSkin* mjs_addSkin(mjSpec* s);
+mjsTexture* mjs_addTexture(mjSpec* s);
+mjsMaterial* mjs_addMaterial(mjSpec* s, mjsDefault* def);
+mjSpec* mjs_getSpec(mjsBody* body);
+mjsBody* mjs_findBody(mjSpec* s, const char* name);
+mjsBody* mjs_findChild(mjsBody* body, const char* name);
+mjsMesh* mjs_findMesh(mjSpec* s, const char* name);
+mjsFrame* mjs_findFrame(mjSpec* s, const char* name);
+mjsDefault* mjs_getDefault(mjsElement* element);
+mjsDefault* mjs_findDefault(mjSpec* s, const char* classname);
+mjsDefault* mjs_getSpecDefault(mjSpec* s);
+int mjs_getId(mjsElement* element);
+mjsElement* mjs_firstChild(mjsBody* body, mjtObj type);
+mjsElement* mjs_nextChild(mjsBody* body, mjsElement* child);
+void mjs_setString(mjString* dest, const char* text);
+void mjs_setStringVec(mjStringVec* dest, const char* text);
+mjtByte mjs_setInStringVec(mjStringVec* dest, int i, const char* text);
+void mjs_appendString(mjStringVec* dest, const char* text);
+void mjs_setInt(mjIntVec* dest, const int* array, int size);
+void mjs_appendIntVec(mjIntVecVec* dest, const int* array, int size);
+void mjs_setFloat(mjFloatVec* dest, const float* array, int size);
+void mjs_appendFloatVec(mjFloatVecVec* dest, const float* array, int size);
+void mjs_setDouble(mjDoubleVec* dest, const double* array, int size);
+void mjs_setPluginAttributes(mjsPlugin* plugin, void* attributes);
+const char* mjs_getString(const mjString* source);
+const double* mjs_getDouble(const mjDoubleVec* source, int* size);
+void mjs_setActivePlugins(mjSpec* s, void* activeplugins);
+void mjs_setDefault(mjsElement* element, mjsDefault* def);
+void mjs_setFrame(mjsElement* dest, mjsFrame* frame);
+const char* mjs_resolveOrientation(double quat[4], mjtByte degree, const char* sequence,
+                                   const mjsOrientation* orientation);
+const char* mjs_fullInertia(double quat[4], double inertia[3], const double fullinertia[6]);
+void mjs_defaultSpec(mjSpec* spec);
+void mjs_defaultOrientation(mjsOrientation* orient);
+void mjs_defaultBody(mjsBody* body);
+void mjs_defaultFrame(mjsFrame* frame);
+void mjs_defaultJoint(mjsJoint* joint);
+void mjs_defaultGeom(mjsGeom* geom);
+void mjs_defaultSite(mjsSite* site);
+void mjs_defaultCamera(mjsCamera* camera);
+void mjs_defaultLight(mjsLight* light);
+void mjs_defaultFlex(mjsFlex* flex);
+void mjs_defaultMesh(mjsMesh* mesh);
+void mjs_defaultHField(mjsHField* hfield);
+void mjs_defaultSkin(mjsSkin* skin);
+void mjs_defaultTexture(mjsTexture* texture);
+void mjs_defaultMaterial(mjsMaterial* material);
+void mjs_defaultPair(mjsPair* pair);
+void mjs_defaultEquality(mjsEquality* equality);
+void mjs_defaultTendon(mjsTendon* tendon);
+void mjs_defaultActuator(mjsActuator* actuator);
+void mjs_defaultSensor(mjsSensor* sensor);
+void mjs_defaultNumeric(mjsNumeric* numeric);
+void mjs_defaultText(mjsText* text);
+void mjs_defaultTuple(mjsTuple* tuple);
+void mjs_defaultKey(mjsKey* key);
+void mjs_defaultPlugin(mjsPlugin* plugin);
 // NOLINTEND

doc/modeling.rst

@@ -36,19 +36,19 @@ mjModel memory buffer. MJCF and URDF files are loaded with :ref:`mj_loadXML` whi
 :ref:`mj_loadModel`.
 
 When an XML file is loaded, it is first parsed into a document object model (DOM) using the TinyXML parser internally.
-This DOM is then processed and converted into a high-level mjCModel object. The conversion depends on the model format
-- which is inferred from the top-level element in the XML file, and not from the file extension. Recall that a valid
-XML file has a unique top-level element. This element must be :el:`mujoco` for MJCF, and :el:`robot` for URDF.
+This DOM is then processed and converted into a high-level :ref:`mjSpec` object. The conversion depends on the model
+format -- which is inferred from the top-level element in the XML file, and not from the file extension. Recall that a
+valid XML file has a unique top-level element. This element must be :el:`mujoco` for MJCF, and :el:`robot` for URDF.
 
 .. _Compile:
 
 Compiling models
 ~~~~~~~~~~~~~~~~
 
-Once a high-level mjCModel is created---by loading an MJCF file or a URDF file, or programmatically when such
-functionality becomes available---it is compiled into mjModel. Even though loading and compilation are presently
-combined in one step, compilation is independent of loading, meaning that the compiler works in the same way
-regardless of how mjCModel was created. Both the parser and the compiler perform extensive error checking, and abort
+Once a high-level :ref:`mjSpec` is created---by loading an MJCF file or a URDF file, or
+:doc:`programmatically<programming/modeledit>`---it is compiled into :ref:`mjModel`.
+Compilation is independent of loading, meaning that the compiler works in the same way regardless of how :ref:`mjSpec`
+was created. Both the parser and the compiler perform extensive error checking, and abort
 when the first error is encountered. The resulting error messages contain the row and column number in the XML file,
 and are self-explanatory so we do not document them here. The parser uses a custom schema to make sure that the file
 structure, elements and attributes are valid. The compiler then applies many additional semantic checks. Finally, one
@@ -72,9 +72,9 @@ binary MJB file with :ref:`mj_saveModel`. The MJB is a stand-alone file and does
 refer to any other files. It also loads faster. So we recommend saving commonly used models as MJB and loading them
 when needed for simulation.
 
-It is also possible to save a compiled mjCModel as MJCF with :ref:`mj_saveLastXML`. If any real-valued fields in the
-corresponding mjModel were modified after compilation (which is unusual but can happen in system identification
-applications for example), the modifications are automatically copied back into mjCModel before saving. Note that
+It is also possible to save a compiled :ref:`mjSpec` as MJCF with :ref:`mj_saveLastXML`. If any real-valued fields in
+the corresponding mjModel were modified after compilation (which is unusual but can happen in system identification
+applications for example), the modifications are automatically copied back into :ref:`mjSpec` before saving. Note that
 structural changes cannot be made in the compiled model. The XML writer attempts to generate the smallest MJCF file
 which is guaranteed to compile into the same model, modulo negligible numeric differences caused by the plain text
 representation of real values. The resulting file may not have the same structure as the original because MJCF has many
@@ -83,6 +83,14 @@ subset of MJCF where all coordinates are local and all body positions, orientati
 explicitly specified. In the Computation chapter we showed an `example <_static/example.xml>`__ MJCF file and the
 corresponding `saved example <_static/example_saved.xml>`__.
 
+.. _EditModel:
+
+Editing models
+~~~~~~~~~~~~~~
+
+As of MuJoCo 3.2, it is possible to create and modify models using the :ref:`mjSpec` struct and related API.
+For further documentation, please see the :doc:`Model Editing<programming/modeledit>` chapter.
+
 .. _Mechanisms:
 
 MJCF Mechanisms

doc/overview.rst

@@ -141,32 +141,30 @@ There are several entities called "model" in MuJoCo. The user defines the model
 The software can then create multiple instances of the same model in different media (file or memory) and on different
 levels of description (high or low). All combinations are possible as shown in the following table:
 
-+------------+----------------------+----------------------+
-|            | High level           | Low level            |
-+============+======================+======================+
-| **File**   | MJCF/URDF (XML)      | MJB (binary)         |
-+------------+----------------------+----------------------+
-| **Memory** | mjCModel (C++ class) | mjModel (C struct)   |
-+------------+----------------------+----------------------+
++------------+---------------------------+----------------------------+
+|            | High level                | Low level                  |
++============+===========================+============================+
+| **File**   | MJCF/URDF (XML)           | MJB (binary)               |
++------------+---------------------------+----------------------------+
+| **Memory** | :ref:`mjSpec` (C struct)  | :ref:`mjModel` (C struct)  |
++------------+---------------------------+----------------------------+
 
-All runtime computations are performed with ``mjModel`` which is too complex to create manually. This is why we have two
-levels of modeling. The high level exists for user convenience: its sole purpose is to be compiled into a low level
-model on which computations can be performed. The resulting ``mjModel`` can be loaded and saved into a binary file
+All runtime computations are performed with :ref:`mjModel` which is too complex to create manually. This is why we have
+two levels of modeling. The high level exists for user convenience: its sole purpose is to be compiled into a low level
+model on which computations can be performed. The resulting :ref:`mjModel` can be loaded and saved into a binary file
 (MJB), however those are version-specific and cannot be decompiled, thus models should always be maintained as XML
 files.
 
-The (internal) C++ class ``mjCModel`` is roughly in one-to-one correspondence with the MJCF file format. The XML parser
-interprets the MJCF or URDF file and creates the corresponding ``mjCModel``. In principle the user can create
-``mjCModel`` programmatically and then save it to MJCF or compile it. However this functionality is not yet exposed
-because a C++ API cannot be exported from a compiler-independent library. There is a plan to develop a C wrapper around
-it, but for the time being the parser and compiler are always invoked together, and models can only be created in XML.
+The :ref:`mjSpec` C struct is in one-to-one correspondence with the MJCF file format. The XML loader interprets the MJCF
+or URDF file, creates the corresponding :ref:`mjSpec` and compiles it to :ref:`mjModel`. The user can create
+:ref:`mjSpec` programmatically and then save it to MJCF or compile it. Procedural model creation and editing is
+described in the :doc:`Model Editing <programming/modeledit>` chapter.
 
-The following diagram shows the different paths to obtaining an ``mjModel`` (again, the second bullet point is not yet
-available):
+The following diagram shows the different paths to obtaining an :ref:`mjModel`:
 
--  (text editor) → MJCF/URDF file → (MuJoCo parser → mjCModel → MuJoCo compiler) → mjModel
--  (user code) → mjCModel → (MuJoCo compiler) → mjModel
--  MJB file → (MuJoCo loader) → mjModel
+-  (text editor) → MJCF/URDF file → (MuJoCo parser → mjSpec → compiler) → mjModel
+-  (user code) → mjSpec → (MuJoCo compiler) → mjModel
+-  MJB file → (model loader) → mjModel
 
 .. _Examples:
 

doc/programming/index.rst

@@ -18,7 +18,7 @@ Engine
    The simulator (or physics engine) is written in C. It is responsible for all runtime computations.
 Parser
    The XML parser is written in C++. It can parse MJCF models and URDF models, converting them into an internal mjCModel
-   C++ object which is not directly exposed to the user.
+   C++ object which is exposed to the user via mjSpec.
 Compiler
    The compiler is written in C++. It takes an mjCModel C++ object constructed by the parser, and converts it into an
    mjModel C structure used at runtime.
@@ -108,10 +108,10 @@ Building from source
 
 To build MuJoCo from source, you will need CMake and a working C++17 compiler installed. The steps are:
 
- #. Clone the ``mujoco`` repository from GitHub.
- #. Create a new build directory somewhere, and ``cd`` into it.
- #. Run ``cmake $PATH_TO_CLONED_REPO`` to configure the build.
- #. Run ``cmake --build .`` to build.
+#. Clone the ``mujoco`` repository from GitHub.
+#. Create a new build directory somewhere, and ``cd`` into it.
+#. Run ``cmake $PATH_TO_CLONED_REPO`` to configure the build.
+#. Run ``cmake --build .`` to build.
 
 MuJoCo's build system automatically fetches dependencies from upstream repositories over the Internet using CMake's
 `FetchContent <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_ module.
@@ -123,8 +123,8 @@ section of the documentation.
 Additionally, the CMake setup also implements an installation phase which will copy and organize the output files to a
 target directory.
 
- 5. Select the directory: ``cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>``
- #. After building, install with ``cmake --install .``
+5. Select the directory: ``cmake $PATH_TO_CLONED_REPO -DCMAKE_INSTALL_PREFIX=<my_install_dir>``
+#. After building, install with ``cmake --install .``
 
 When building on Windows, use Visual Studio 2019 or later and make sure Windows SDK version 10.0.22000 or later is
 installed (see `here <https://github.com/google-deepmind/mujoco/issues/862>`__ for more details).
@@ -160,6 +160,8 @@ links below, to make this documentation self-contained.
    Defines the primitive types and structures needed by the UI framework.
 `mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`__
    Defines MuJoCo's ``mjtNum`` floating-point type to be either ``double`` or ``float``. See :ref:`mjtNum`.
+`mjspec.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjspec.h>`__
+   Defines enums and structs used for :doc:`procedural model editing <modeledit>`.
 `mjmacro.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmacro.h>`__
    Defines C macros that are useful in user code.
 `mjxmacro.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`__
@@ -226,6 +228,8 @@ to which the symbol belongs. First we list the prefixes corresponding to type de
    Data structure related to OpenGL rendering, for example :ref:`mjrContext`.
 ``mjui``
    Data structure related to UI framework, for example :ref:`mjuiSection`.
+``mjs``
+   Data structure related :doc:`procedural model editing <modeledit>`, for example :ref:`mjsJoint`.
 
 Next we list the prefixes corresponding to function definitions. Note that function prefixes always end with underscore.
 
@@ -247,6 +251,8 @@ Next we list the prefixes corresponding to function definitions. Note that funct
    custom callbacks by setting these global pointers to user-defined functions.
 ``mjd_``
    Functions for computing derivatives, for example :ref:`mjd_transitionFD`.
+``mjs_``
+   Functions for :doc:`procedural model editing <modeledit>`, for example :ref:`mjs_addJoint`.
 
 .. _inOpenGL:
 
@@ -276,5 +282,6 @@ now lazily resolved at runtime after the switch to GLAD, the "nogl" libraries ar
     simulation
     visualization
     ui
+    modeledit
     samples
     extension

doc/programming/modeledit.rst

@@ -0,0 +1,44 @@
+Model Editing
+-------------
+
+.. admonition:: Unstable API
+   :class: attention
+
+   The API described below is new and unstable. There may be latent bugs and function signatures may change. Early
+   adopters are welcome (indeed, encouraged) to try it out and report any issues on GitHub.
+
+As of MuJoCo 3.2, it is possible to create and modify models using the :ref:`mjSpec` struct and related API.
+This datastructure is in one-to-one correspondence with MJCF and indeed, MuJoCo's own XML parsers (both MJCF and URDF)
+use this API when loading a model.
+
+
+.. _meOverview:
+
+Overview
+~~~~~~~~
+
+As summarized in the the :ref:`Overview chapter<Instance>`, the traditional workflow to create compiled :ref:`mjModel`
+instances is:
+
+1. Create an XML model description file (MJCF or URDF).
+2. Call :ref:`mj_loadXML` passing in the XML (and associated assets), obtain an :ref:`mjModel` instance.
+
+The new workflow looks like:
+
+1. Create an :ref:`mjSpec`, either an empty one corresponding to the XML ``<mujoco/>``, or by loading an existing XML
+   file.
+2. Modify the :ref:`mjSpec` as desired, adding, editing and removing elements.
+3. Compile the :ref:`mjSpec` at any point, obtaining an updated :ref:`mjModel` instance. After compilation, the
+   :ref:`mjSpec` remains editable, so steps 2 and 3 are interchangable.
+
+
+.. _meUsage:
+
+Usage
+~~~~~
+
+Detailed documentation is still missing. In the meantime, advanced users can refer to
+`user_api_test.cc <https://github.com/google-deepmind/mujoco/blob/main/test/user/user_api_test.cc>`__ and the MJCF
+parser in `xml_native_reader.cc <https://github.com/google-deepmind/mujoco/blob/main/src/xml/xml_native_reader.cc>`__,
+which is already using this API.
+

doc/programming/simulation.rst

@@ -585,8 +585,8 @@ corresponding to precomputed quantities when the model is in the reference confi
 
 Finally, if changes are made to mjModel at runtime, it may be desirable to save them back to the XML. The function
 :ref:`mj_saveLastXML` does that in a limited sense: it copies all real-valued parameters from mjModel back to the
-internal mjCModel, and then saves it as XML. This does not cover all possible changes that the user could have made.
-The only way to guarantee that all changes are saved is to save the model as a binary MJB file with the function
+internal :ref:`mjSpec`, and then saves it as XML. This does not cover all possible changes that the user could have
+made. The only way to guarantee that all changes are saved is to save the model as a binary MJB file with the function
 :ref:`mj_saveModel`, or even better, make the changes directly in the XML. Unfortunately there are situations where
 changes need to be made programmatically, as in system identification for example, and this can only be done with the
 compiled model. So in summary, we have reasonable but not perfect mechanisms for saving model changes. The reason for

include/mujoco/mjspec.h

@@ -0,0 +1,763 @@
+// Copyright 2024 DeepMind Technologies Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef MUJOCO_INCLUDE_MJSPEC_H_
+#define MUJOCO_INCLUDE_MJSPEC_H_
+
+#include <stddef.h>
+#include <mujoco/mjmodel.h>
+#include <mujoco/mjtnum.h>
+
+
+// this is a C-API
+#ifdef __cplusplus
+#include <string>
+#include <vector>
+
+extern "C" {
+#endif
+
+//-------------------------------- handles to strings and arrays -----------------------------------
+
+#ifdef __cplusplus
+  // C++: defined to be compatible with corresponding std types
+  using mjString      = std::string;
+  using mjStringVec   = std::vector<std::string>;
+  using mjIntVec      = std::vector<int>;
+  using mjIntVecVec   = std::vector<std::vector<int>>;
+  using mjFloatVec    = std::vector<float>;
+  using mjFloatVecVec = std::vector<std::vector<float>>;
+  using mjDoubleVec   = std::vector<double>;
+#else
+  // C: opaque types
+  typedef void mjString;
+  typedef void mjStringVec;
+  typedef void mjIntVec;
+  typedef void mjIntVecVec;
+  typedef void mjFloatVec;
+  typedef void mjFloatVecVec;
+  typedef void mjDoubleVec;
+#endif
+
+
+//-------------------------------- enum types (mjt) ------------------------------------------------
+
+typedef enum mjtGeomInertia_ {     // type of inertia inference
+  mjINERTIA_VOLUME,                // mass distributed in the volume
+  mjINERTIA_SHELL,                 // mass distributed on the surface
+} mjtGeomInertia;
+
+
+typedef enum mjtBuiltin_ {         // type of built-in procedural texture
+  mjBUILTIN_NONE = 0,              // no built-in texture
+  mjBUILTIN_GRADIENT,              // gradient: rgb1->rgb2
+  mjBUILTIN_CHECKER,               // checker pattern: rgb1, rgb2
+  mjBUILTIN_FLAT                   // 2d: rgb1; cube: rgb1-up, rgb2-side, rgb3-down
+} mjtBuiltin;
+
+
+typedef enum mjtMark_ {            // mark type for procedural textures
+  mjMARK_NONE = 0,                 // no mark
+  mjMARK_EDGE,                     // edges
+  mjMARK_CROSS,                    // cross
+  mjMARK_RANDOM                    // random dots
+} mjtMark;
+
+
+typedef enum mjtLimited_ {         // type of limit specification
+  mjLIMITED_FALSE = 0,             // not limited
+  mjLIMITED_TRUE,                  // limited
+  mjLIMITED_AUTO,                  // limited inferred from presence of range
+} mjtLimited;
+
+
+typedef enum mjtInertiaFromGeom_ { // whether to infer body inertias from child geoms
+  mjINERTIAFROMGEOM_FALSE = 0,     // do not use; inertial element required
+  mjINERTIAFROMGEOM_TRUE,          // always use; overwrite inertial element
+  mjINERTIAFROMGEOM_AUTO           // use only if inertial element is missing
+} mjtInertiaFromGeom;
+
+
+typedef enum mjtOrientation_ {     // type of orientation specifier
+  mjORIENTATION_QUAT = 0,          // quaternion
+  mjORIENTATION_AXISANGLE,         // axis and angle
+  mjORIENTATION_XYAXES,            // x and y axes
+  mjORIENTATION_ZAXIS,             // z axis (minimal rotation)
+  mjORIENTATION_EULER,             // Euler angles
+} mjtOrientation;
+
+
+//-------------------------------- attribute structs (mjs) -----------------------------------------
+
+typedef struct mjsElement_ {       // element type, do not modify
+  mjtObj elemtype;                 // element type
+} mjsElement;
+
+
+typedef struct mjSpec_ {           // model specification
+  mjsElement* element;             // element type
+  mjString* modelname;             // model name
+
+  // compiler settings
+  mjtByte autolimits;              // infer "limited" attribute based on range
+  double boundmass;                // enforce minimum body mass
+  double boundinertia;             // enforce minimum body diagonal inertia
+  double settotalmass;             // rescale masses and inertias; <=0: ignore
+  mjtByte balanceinertia;          // automatically impose A + B >= C rule
+  mjtByte strippath;               // automatically strip paths from mesh files
+  mjtByte fitaabb;                 // meshfit to aabb instead of inertia box
+  mjtByte degree;                  // angles in radians or degrees
+  char euler[3];                   // sequence for euler rotations
+  mjString* meshdir;               // mesh and hfield directory
+  mjString* texturedir;            // texture directory
+  mjtByte discardvisual;           // discard visual geoms in parser
+  mjtByte convexhull;              // compute mesh convex hulls
+  mjtByte usethread;               // use multiple threads to speed up compiler
+  mjtByte fusestatic;              // fuse static bodies with parent
+  int inertiafromgeom;             // use geom inertias (mjtInertiaFromGeom)
+  int inertiagrouprange[2];        // range of geom groups used to compute inertia
+  mjtByte exactmeshinertia;        // if false, use old formula
+  mjLROpt LRopt;                   // options for lengthrange computation
+
+  // engine data
+  mjOption option;                 // physics options
+  mjVisual visual;                 // visual options
+  mjStatistic stat;                // statistics override (if defined)
+
+  // sizes
+  size_t memory;                   // number of bytes in arena+stack memory
+  int nemax;                       // max number of equality constraints
+  int nuserdata;                   // number of mjtNums in userdata
+  int nuser_body;                  // number of mjtNums in body_user
+  int nuser_jnt;                   // number of mjtNums in jnt_user
+  int nuser_geom;                  // number of mjtNums in geom_user
+  int nuser_site;                  // number of mjtNums in site_user
+  int nuser_cam;                   // number of mjtNums in cam_user
+  int nuser_tendon;                // number of mjtNums in tendon_user
+  int nuser_actuator;              // number of mjtNums in actuator_user
+  int nuser_sensor;                // number of mjtNums in sensor_user
+  int nkey;                        // number of keyframes
+  int njmax;                       // (deprecated) max number of constraints
+  int nconmax;                     // (deprecated) max number of detected contacts
+  size_t nstack;                   // (deprecated) number of mjtNums in mjData stack
+
+  // global data
+  mjString* comment;               // comment at top of XML
+  mjString* modelfiledir;          // path to model file
+
+  // other
+  mjtByte hasImplicitPluginElem;   // already encountered an implicit plugin sensor/actuator
+} mjSpec;
+
+
+typedef struct mjsOrientation_ {   // alternative orientation specifiers
+  mjtOrientation type;             // active orientation specifier
+  double axisangle[4];             // axis and angle
+  double xyaxes[6];                // x and y axes
+  double zaxis[3];                 // z axis (minimal rotation)
+  double euler[3];                 // Euler angles
+} mjsOrientation;
+
+
+typedef struct mjsPlugin_ {        // plugin specification
+  mjsElement* instance;            // element type
+  mjString* name;                  // name
+  mjString* instance_name;         // instance name
+  int plugin_slot;                 // global registered slot number of the plugin
+  mjtByte active;                  // is the plugin active
+  mjString* info;                  // message appended to compiler errors
+} mjsPlugin;
+
+
+typedef struct mjsBody_ {          // body specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* childclass;            // childclass name
+
+  // body frame
+  double pos[3];                   // frame position
+  double quat[4];                  // frame orientation
+  mjsOrientation alt;              // frame alternative orientation
+
+  // inertial frame
+  double mass;                     // mass
+  double ipos[3];                  // inertial frame position
+  double iquat[4];                 // inertial frame orientation
+  double inertia[3];               // diagonal inertia (in i-frame)
+  mjsOrientation ialt;             // inertial frame alternative orientation
+  double fullinertia[6];           // non-axis-aligned inertia matrix
+
+  // other
+  mjtByte mocap;                   // is this a mocap body
+  double gravcomp;                 // gravity compensation
+  mjDoubleVec* userdata;           // user data
+  mjtByte explicitinertial;        // whether to save the body with explicit inertial clause
+  mjsPlugin plugin;                // passive force plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsBody;
+
+
+typedef struct mjsFrame_ {         // frame specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* childclass;            // childclass name
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  mjString* info;                  // message appended to compiler errors
+} mjsFrame;
+
+
+typedef struct mjsJoint_ {         // joint specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjtJoint type;                   // joint type
+
+  // kinematics
+  double pos[3];                   // anchor position
+  double axis[3];                  // joint axis
+  double ref;                      // value at reference configuration: qpos0
+
+  // stiffness
+  double stiffness;                // stiffness coefficient
+  double springref;                // spring reference value: qpos_spring
+  double springdamper[2];          // timeconst, dampratio
+
+  // limits
+  int limited;                     // does joint have limits (mjtLimited)
+  double range[2];                 // joint limits
+  double margin;                   // margin value for joint limit detection
+  mjtNum solref_limit[mjNREF];     // solver reference: joint limits
+  mjtNum solimp_limit[mjNIMP];     // solver impedance: joint limits
+  int actfrclimited;               // are actuator forces on joint limited (mjtLimited)
+  double actfrcrange[2];           // actuator force limits
+
+  // dof properties
+  double armature;                 // armature inertia (mass for slider)
+  double damping;                  // damping coefficient
+  double frictionloss;             // friction loss
+  mjtNum solref_friction[mjNREF];  // solver reference: dof friction
+  mjtNum solimp_friction[mjNIMP];  // solver impedance: dof friction
+
+  // other
+  int group;                       // group
+  mjtByte actgravcomp;             // is gravcomp force applied via actuators
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to compiler errors
+} mjsJoint;
+
+
+typedef struct mjsGeom_ {          // geom specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // classname
+  mjtGeom type;                    // geom type
+
+  // frame, size
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  double fromto[6];                // alternative for capsule, cylinder, box, ellipsoid
+  double size[3];                  // type-specific size
+
+  // contact related
+  int contype;                     // contact type
+  int conaffinity;                 // contact affinity
+  int condim;                      // contact dimensionality
+  int priority;                    // contact priority
+  double friction[3];              // one-sided friction coefficients: slide, roll, spin
+  double solmix;                   // solver mixing for contact pairs
+  mjtNum solref[mjNREF];           // solver reference
+  mjtNum solimp[mjNIMP];           // solver impedance
+  double margin;                   // margin for contact detection
+  double gap;                      // include in solver if dist < margin-gap
+
+  // inertia inference
+  double mass;                     // used to compute density
+  double density;                  // used to compute mass and inertia from volume or surface
+  mjtGeomInertia typeinertia;      // selects between surface and volume inertia
+
+  // fluid forces
+  mjtNum fluid_ellipsoid;          // whether ellipsoid-fluid model is active
+  mjtNum fluid_coefs[5];           // ellipsoid-fluid interaction coefs
+
+  // visual
+  mjString* material;              // name of material
+  float rgba[4];                   // rgba when material is omitted
+  int group;                       // group
+
+  // other
+  mjString* hfieldname;            // heightfield attached to geom
+  mjString* meshname;              // mesh attached to geom
+  double fitscale;                 // scale mesh uniformly
+  mjDoubleVec* userdata;           // user data
+  mjsPlugin plugin;                // sdf plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsGeom;
+
+
+typedef struct mjsSite_ {          // site specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // frame, size
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  double fromto[6];                // alternative for capsule, cylinder, box, ellipsoid
+  double size[3];                  // geom size
+
+  // visual
+  mjtGeom type;                    // geom type
+  mjString* material;              // name of material
+  int group;                       // group
+  float rgba[4];                   // rgba when material is omitted
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to compiler errors
+} mjsSite;
+
+
+typedef struct mjsCamera_ {        // camera specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // extrinsics
+  double pos[3];                   // position
+  double quat[4];                  // orientation
+  mjsOrientation alt;              // alternative orientation
+  mjtCamLight mode;                // tracking mode
+  mjString* targetbody;            // target body for tracking/targeting
+
+  // intrinsics
+  double fovy;                     // y-field of view
+  double ipd;                      // inter-pupilary distance
+  float intrinsic[4];              // camera intrinsics (length)
+  float sensor_size[2];            // sensor size (length)
+  float resolution[2];             // resolution (pixel)
+  float focal_length[2];           // focal length (length)
+  float focal_pixel[2];            // focal length (pixel)
+  float principal_length[2];       // principal point (length)
+  float principal_pixel[2];        // principal point (pixel)
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to compiler errors
+} mjsCamera;
+
+
+typedef struct mjsLight_ {         // light specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // frame
+  double pos[3];                   // position
+  double dir[3];                   // direction
+  mjtCamLight mode;                // tracking mode
+  mjString* targetbody;            // target body for targeting
+
+  // intrinsics
+  mjtByte active;                  // is light active
+  mjtByte directional;             // is light directional or spot
+  mjtByte castshadow;              // does light cast shadows
+  double bulbradius;               // bulb radius, for soft shadows
+  float attenuation[3];            // OpenGL attenuation (quadratic model)
+  float cutoff;                    // OpenGL cutoff
+  float exponent;                  // OpenGL exponent
+  float ambient[3];                // ambient color
+  float diffuse[3];                // diffuse color
+  float specular[3];               // specular color
+
+  // other
+  mjString* info;                  // message appended to compiler errorsx
+} mjsLight;
+
+
+typedef struct mjsFlex_ {          // flex specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // contact properties
+  int contype;                     // contact type
+  int conaffinity;                 // contact affinity
+  int condim;                      // contact dimensionality
+  int priority;                    // contact priority
+  double friction[3];              // one-sided friction coefficients: slide, roll, spin
+  double solmix;                   // solver mixing for contact pairs
+  mjtNum solref[mjNREF];           // solver reference
+  mjtNum solimp[mjNIMP];           // solver impedance
+  double margin;                   // margin for contact detection
+  double gap;                      // include in solver if dist<margin-gap
+
+  // other properties
+  int dim;                         // element dimensionality
+  double radius;                   // radius around primitive element
+  mjtByte internal;                // enable internal collisions
+  mjtByte flatskin;                // render flex skin with flat shading
+  int selfcollide;                 // mode for flex self colllision
+  int activelayers;                // number of active element layers in 3D
+  int group;                       // group for visualizatioh
+  double edgestiffness;            // edge stiffness
+  double edgedamping;              // edge damping
+  float rgba[4];                   // rgba when material is omitted
+  mjString* material;              // name of material used for rendering
+
+  // mesh properties
+  mjStringVec* vertbody;           // vertex body names
+  mjDoubleVec* vert;               // vertex positions
+  mjIntVec* elem;                  // element vertex ids
+  mjFloatVec* texcoord;            // vertex texture coordinates
+
+  // other
+  mjString* info;                  // message appended to compiler errors
+} mjsFlex;
+
+
+typedef struct mjsMesh_ {          // mesh specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* content_type;          // content type of file
+  mjString* file;                  // mesh file
+  double refpos[3];                // reference position
+  double refquat[4];               // reference orientation
+  double scale[3];                 // rescale mesh
+  mjtByte smoothnormal;            // do not exclude large-angle faces from normals
+  int maxhullvert;                 // maximum vertex count for the convex hull
+  mjFloatVec* uservert;            // user vertex data
+  mjFloatVec* usernormal;          // user normal data
+  mjFloatVec* usertexcoord;        // user texcoord data
+  mjIntVec* userface;              // user vertex indices
+  mjIntVec* userfacenormal;        // user normal indices
+  mjIntVec* userfacetexcoord;      // user texcoord indices
+  mjsPlugin plugin;                // sdf plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsMesh;
+
+
+typedef struct mjsHField_ {        // height field specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* content_type;          // content type of file
+  mjString* file;                  // file: (nrow, ncol, [elevation data])
+  double size[4];                  // hfield size (ignore referencing geom size)
+  int nrow;                        // number of rows
+  int ncol;                        // number of columns
+  mjFloatVec* userdata;            // user-provided elevation data
+  mjString* info;                  // message appended to compiler errors
+} mjsHField;
+
+
+
+typedef struct mjsSkin_ {          // skin specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* file;                  // skin file
+  mjString* material;              // name of material used for rendering
+  float rgba[4];                   // rgba when material is omitted
+  float inflate;                   // inflate in normal direction
+  int group;                       // group for visualization
+
+  // mesh
+  mjFloatVec* vert;                // vertex positions
+  mjFloatVec* texcoord;            // texture coordinates
+  mjIntVec* face;                  // faces
+
+  // skin
+  mjStringVec* bodyname;           // body names
+  mjFloatVec* bindpos;             // bind pos
+  mjFloatVec* bindquat;            // bind quat
+  mjIntVecVec* vertid;             // vertex ids
+  mjFloatVecVec* vertweight;       // vertex weights
+
+  // other
+  mjString* info;                  // message appended to compiler errors
+} mjsSkin;
+
+
+typedef struct mjsTexture_ {       // texture specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjtTexture type;                 // texture type
+
+  // method 1: builtin
+  int builtin;                     // builtin type (mjtBuiltin)
+  int mark;                        // mark type (mjtMark)
+  double rgb1[3];                  // first color for builtin
+  double rgb2[3];                  // second color for builtin
+  double markrgb[3];               // mark color
+  double random;                   // probability of random dots
+  int height;                      // height in pixels (square for cube and skybox)
+  int width;                       // width in pixels
+
+  // method 2: single file
+  mjString* content_type;          // content type of file
+  mjString* file;                  // png file to load; use for all sides of cube
+  int gridsize[2];                 // size of grid for composite file; (1,1)-repeat
+  char gridlayout[13];             // row-major: L,R,F,B,U,D for faces; . for unused
+
+  // method 3: separate files
+  mjStringVec* cubefiles;          // different file for each side of the cube
+
+  // flip options
+  mjtByte hflip;                   // horizontal flip
+  mjtByte vflip;                   // vertical flip
+
+  // other
+  mjString* info;                  // message appended to compiler errors
+} mjsTexture;
+
+
+typedef struct mjsMaterial_ {      // material specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* texture;               // name of texture (empty: none)
+  mjtByte texuniform;              // make texture cube uniform
+  float texrepeat[2];              // texture repetition for 2D mapping
+  float emission;                  // emission
+  float specular;                  // specular
+  float shininess;                 // shininess
+  float reflectance;               // reflectance
+  float metallic;                  // metallic
+  float roughness;                 // roughness
+  float rgba[4];                   // rgba
+  mjString* info;                  // message appended to compiler errors
+} mjsMaterial;
+
+
+typedef struct mjsPair_ {          // pair specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjString* geomname1;             // name of geom 1
+  mjString* geomname2;             // name of geom 2
+
+  // optional parameters: computed from geoms if not set by user
+  int condim;                      // contact dimensionality
+  mjtNum solref[mjNREF];           // solver reference, normal direction
+  mjtNum solreffriction[mjNREF];   // solver reference, frictional directions
+  mjtNum solimp[mjNIMP];           // solver impedance
+  double margin;                   // margin for contact detection
+  double gap;                      // include in solver if dist<margin-gap
+  double friction[5];              // full contact friction
+  mjString* info;                  // message appended to errors
+} mjsPair;
+
+
+typedef struct mjsExclude_ {       // exclude specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* bodyname1;             // name of geom 1
+  mjString* bodyname2;             // name of geom 2
+  mjString* info;                  // message appended to errors
+} mjsExclude;
+
+
+typedef struct mjsEquality_ {      // equality specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+  mjtEq type;                      // constraint type
+  double data[mjNEQDATA];          // type-dependent data
+  mjtByte active;                  // is equality initially active
+  mjString* name1;                 // name of object 1
+  mjString* name2;                 // name of object 2
+  mjtNum solref[mjNREF];           // solver reference
+  mjtNum solimp[mjNIMP];           // solver impedance
+  mjString* info;                  // message appended to errors
+} mjsEquality;
+
+
+typedef struct mjsTendon_ {        // tendon specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // stiffness, damping, friction
+  double stiffness;                // stiffness coefficient
+  double springlength[2];          // spring resting length; {-1, -1}: use qpos_spring
+  double damping;                  // damping coefficient
+  double frictionloss;             // friction loss
+  mjtNum solref_friction[mjNREF];  // solver reference: tendon friction
+  mjtNum solimp_friction[mjNIMP];  // solver impedance: tendon friction
+
+  // length range
+  int limited;                     // does tendon have limits (mjtLimited)
+  double range[2];                 // length limits
+  double margin;                   // margin value for tendon limit detection
+  mjtNum solref_limit[mjNREF];     // solver reference: tendon limits
+  mjtNum solimp_limit[mjNIMP];     // solver impedance: tendon limits
+
+  // visual
+  mjString* material;              // name of material for rendering
+  double width;                    // width for rendering
+  float rgba[4];                   // rgba when material is omitted
+  int group;                       // group
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjString* info;                  // message appended to errors
+} mjsTendon;
+
+
+typedef struct mjsWrap_ {          // wrapping object specification
+  mjsElement* element;             // element type
+  mjString* info;                  // message appended to errors
+} mjsWrap;
+
+
+typedef struct mjsActuator_ {      // actuator specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // gain, bias
+  mjtGain gaintype;                // gain type
+  double gainprm[mjNGAIN];         // gain parameters
+  mjtBias biastype;                // bias type
+  double biasprm[mjNGAIN];         // bias parameters
+
+  // activation state
+  mjtDyn dyntype;                  // dynamics type
+  double dynprm[mjNDYN];           // dynamics parameters
+  int actdim;                      // number of activation variables
+  int plugin_actdim;               // actuator state size for plugins
+  mjtByte actearly;                // apply next activations to qfrc
+
+  // transmission
+  mjtTrn trntype;                  // transmission type
+  double gear[6];                  // length and transmitted force scaling
+  mjString* target;                // name of transmission target
+  mjString* refsite;               // reference site, for site transmission
+  mjString* slidersite;            // site defining cylinder, for slider-crank
+  double cranklength;              // crank length, for slider-crank
+  double lengthrange[2];           // transmission length range
+  double inheritrange;             // automatic range setting for position and intvelocity
+
+  // input/output clamping
+  int ctrllimited;                 // are control limits defined (mjtLimited)
+  double ctrlrange[2];             // control range
+  int forcelimited;                // are force limits defined (mjtLimited)
+  double forcerange[2];            // force range
+  int actlimited;                  // are activation limits defined (mjtLimited)
+  double actrange[2];              // activation range
+
+  // other
+  int group;                       // group
+  mjDoubleVec* userdata;           // user data
+  mjsPlugin plugin;                // actuator plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsActuator;
+
+
+typedef struct mjsSensor_ {        // sensor specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* classname;             // class name
+
+  // sensor definition
+  mjtSensor type;                  // type of sensor
+  mjtObj objtype;                  // type of sensorized object
+  mjString* objname;               // name of sensorized object
+  mjtObj reftype;                  // type of referenced object
+  mjString* refname;               // name of referenced object
+
+  // user-defined sensors
+  mjtDataType datatype;            // data type for sensor measurement
+  mjtStage needstage;              // compute stage needed to simulate sensor
+  int dim;                         // number of scalar outputs
+
+  // output post-processing
+  double cutoff;                   // cutoff for real and positive datatypes
+  double noise;                    // noise stdev
+
+  // other
+  mjDoubleVec* userdata;           // user data
+  mjsPlugin plugin;                // sensor plugin
+  mjString* info;                  // message appended to compiler errors
+} mjsSensor;
+
+
+typedef struct mjsNumeric_ {       // custom numeric field specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjDoubleVec* data;               // initialization data
+  int size;                        // array size, can be bigger than data size
+  mjString* info;                  // message appended to compiler errors
+} mjsNumeric;
+
+
+typedef struct mjsText_ {          // custom text specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjString* data;                  // text string
+  mjString* info;                  // message appended to compiler errors
+} mjsText;
+
+
+typedef struct mjsTuple_ {         // tuple specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  mjIntVec* objtype;               // object types
+  mjStringVec* objname;            // object names
+  mjDoubleVec* objprm;             // object parameters
+  mjString* info;                  // message appended to compiler errors
+} mjsTuple;
+
+
+typedef struct mjsKey_ {           // keyframe specification
+  mjsElement* element;             // element type
+  mjString* name;                  // name
+  double time;                     // time
+  mjDoubleVec* qpos;               // qpos
+  mjDoubleVec* qvel;               // qvel
+  mjDoubleVec* act;                // act
+  mjDoubleVec* mpos;               // mocap pos
+  mjDoubleVec* mquat;              // mocap quat
+  mjDoubleVec* ctrl;               // ctrl
+  mjString* info;                  // message appended to compiler errors
+} mjsKey;
+
+
+typedef struct mjsDefault_ {       // default specification
+  mjsElement* element;             // element type
+  mjString* name;                  // class name
+  mjsJoint* joint;                 // joint defaults
+  mjsGeom* geom;                   // geom defaults
+  mjsSite* site;                   // site defaults
+  mjsCamera* camera;               // camera defaults
+  mjsLight* light;                 // light defaults
+  mjsFlex* flex;                   // flex defaults
+  mjsMesh* mesh;                   // mesh defaults
+  mjsMaterial* material;           // material defaults
+  mjsPair* pair;                   // pair defaults
+  mjsEquality* equality;           // equality defaults
+  mjsTendon* tendon;               // tendon defaults
+  mjsActuator* actuator;           // actuator defaults
+} mjsDefault;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // MUJOCO_INCLUDE_MJSPEC_H_

include/mujoco/mujoco.h

@@ -15,14 +15,6 @@
 #ifndef MUJOCO_MUJOCO_H_
 #define MUJOCO_MUJOCO_H_
 
-#include <mujoco/mjexport.h>
-
-
-// this is a C-API
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 // header version; should match the library version as returned by mj_version()
 #define mjVERSION_HEADER 317
 
@@ -32,15 +24,21 @@ extern "C" {
 
 // type definitions
 #include <mujoco/mjdata.h>
+#include <mujoco/mjexport.h>
 #include <mujoco/mjmodel.h>
 #include <mujoco/mjmacro.h>
 #include <mujoco/mjplugin.h>
 #include <mujoco/mjrender.h>
+#include <mujoco/mjspec.h>
 #include <mujoco/mjthread.h>
 #include <mujoco/mjtnum.h>
 #include <mujoco/mjui.h>
 #include <mujoco/mjvisualize.h>
 
+// this is a C-API
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 // user error and memory handlers
 MJAPI extern void  (*mju_user_error)(const char*);
@@ -97,6 +95,7 @@ MJAPI void mj_deleteVFS(mjVFS* vfs);
 // deprecated: use mj_copyBufferVFS.
 MJAPI int mj_makeEmptyFileVFS(mjVFS* vfs, const char* filename, int filesize);
 
+
 //---------------------------------- Parse and compile ---------------------------------------------
 
 // Parse XML file in MJCF or URDF format, compile it, return low-level model.
@@ -104,6 +103,18 @@ MJAPI int mj_makeEmptyFileVFS(mjVFS* vfs, const char* filename, int filesize);
 // If error is not NULL, it must have size error_sz.
 MJAPI mjModel* mj_loadXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
 
+// Parse spec from XML file.
+MJAPI mjSpec* mj_parseXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
+
+// Parse spec from XML string.
+MJAPI mjSpec* mj_parseXMLString(const char* xml, const mjVFS* vfs, char* error, int error_sz);
+
+// Compile spec to model.
+MJAPI mjModel* mj_compile(mjSpec* s, const mjVFS* vfs);
+
+// Recompile spec to model, preserving the state.
+MJAPI void mj_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d);
+
 // Update XML data structures with info from low-level model, save as MJCF.
 // If error is not NULL, it must have size error_sz.
 MJAPI int mj_saveLastXML(const char* filename, const mjModel* m, char* error, int error_sz);
@@ -111,9 +122,14 @@ MJAPI int mj_saveLastXML(const char* filename, const mjModel* m, char* error, in
 // Free last XML model if loaded. Called internally at each load.
 MJAPI void mj_freeLastXML(void);
 
-// Print internal XML schema as plain text or HTML, with style-padding or &nbsp;.
-MJAPI int mj_printSchema(const char* filename, char* buffer, int buffer_sz,
-                         int flg_html, int flg_pad);
+// Copy (possibly modified) model fields back into spec.
+MJAPI void mj_copyBack(mjSpec* s, const mjModel* m);
+
+// Save spec to XML string, return 1 on success, 0 otherwise.
+MJAPI int mj_saveXMLString(const mjSpec* s, char* xml, int xml_sz, char* error, int error_sz);
+
+// Save spec to XML file, return 1 on success, 0 otherwise.
+MJAPI int mj_saveXML(const mjSpec* s, const char* filename, char* error, int error_sz);
 
 
 //---------------------------------- Main simulation -----------------------------------------------
@@ -221,6 +237,15 @@ MJAPI void mj_setConst(mjModel* m, mjData* d);
 MJAPI int mj_setLengthRange(mjModel* m, mjData* d, int index,
                             const mjLROpt* opt, char* error, int error_sz);
 
+// Create empty spec.
+MJAPI mjSpec* mj_makeSpec(void);
+
+// Copy spec.
+MJAPI mjSpec* mj_copySpec(const mjSpec* s);
+
+// Free memory allocation in mjSpec.
+MJAPI void mj_deleteSpec(mjSpec* s);
+
 
 //---------------------------------- Printing ------------------------------------------------------
 
@@ -246,6 +271,10 @@ MJAPI void mju_printMat(const mjtNum* mat, int nr, int nc);
 MJAPI void mju_printMatSparse(const mjtNum* mat, int nr,
                               const int* rownnz, const int* rowadr, const int* colind);
 
+// Print internal XML schema as plain text or HTML, with style-padding or &nbsp;.
+MJAPI int mj_printSchema(const char* filename, char* buffer, int buffer_sz,
+                         int flg_html, int flg_pad);
+
 
 //---------------------------------- Components ----------------------------------------------------
 
@@ -510,7 +539,7 @@ MJAPI int mj_version(void);
 MJAPI const char* mj_versionString(void);
 
 
-//---------------------------------- Ray collisions ------------------------------------------------
+//---------------------------------- Ray casting ---------------------------------------------------
 
 // Intersect multiple rays emanating from a single point.
 // Similar semantics to mj_ray, but vec is an array of (nray x 3) directions.
@@ -852,6 +881,12 @@ MJAPI void mj_warning(mjData* d, int warning, int info);
 // Write [datetime, type: message] to MUJOCO_LOG.TXT.
 MJAPI void mju_writeLog(const char* type, const char* msg);
 
+// Get compiler error message from spec.
+MJAPI const char* mjs_getError(mjSpec* s);
+
+// Return 1 if compiler error is a warning.
+MJAPI int mjs_isWarning(mjSpec* s);
+
 
 //---------------------------------- Standard math -------------------------------------------------
 
@@ -1037,6 +1072,7 @@ MJAPI void mju_transformSpatial(mjtNum res[6], const mjtNum vec[6], int flg_forc
                                 const mjtNum newpos[3], const mjtNum oldpos[3],
                                 const mjtNum rotnew2old[9]);
 
+
 //---------------------------------- Quaternions ---------------------------------------------------
 
 // Rotate vector by quaternion.
@@ -1079,6 +1115,7 @@ MJAPI void mju_quatZ2Vec(mjtNum quat[4], const mjtNum vec[3]);
 // seq[0,1,2] must be in 'xyzXYZ', lower/upper-case mean intrinsic/extrinsic rotations.
 MJAPI void mju_euler2Quat(mjtNum quat[4], const mjtNum euler[3], const char* seq);
 
+
 //---------------------------------- Poses ---------------------------------------------------------
 
 // Multiply two poses.
@@ -1166,7 +1203,8 @@ MJAPI int mju_boxQP(mjtNum* res, mjtNum* R, int* index, const mjtNum* H, const m
 MJAPI void mju_boxQPmalloc(mjtNum** res, mjtNum** R, int** index, mjtNum** H, mjtNum** g, int n,
                            mjtNum** lower, mjtNum** upper);
 
-//---------------------- Miscellaneous -------------------------------------------------------------
+
+//---------------------------------- Miscellaneous -------------------------------------------------
 
 // Muscle active force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fvmax).
 MJAPI mjtNum mju_muscleGain(mjtNum len, mjtNum vel, const mjtNum lengthrange[2],
@@ -1252,7 +1290,7 @@ MJAPI char* mju_strncpy(char *dst, const char *src, int n);
 MJAPI mjtNum mju_sigmoid(mjtNum x);
 
 
-//---------------------- Derivatives ---------------------------------------------------------------
+//---------------------------------- Derivatives ---------------------------------------------------
 
 // Finite differenced transition matrices (control theory notation)
 //   d(x_next) = A*dx + B*du
@@ -1292,7 +1330,8 @@ MJAPI void mjd_subQuat(const mjtNum qa[4], const mjtNum qb[4], mjtNum Da[9], mjt
 MJAPI void mjd_quatIntegrate(const mjtNum vel[3], mjtNum scale,
                              mjtNum Dquat[9], mjtNum Dvel[9], mjtNum Dscale[3]);
 
-//---------------------- Plugins -------------------------------------------------------------------
+
+//---------------------------------- Plugins -------------------------------------------------------
 
 // Set default plugin definition.
 MJAPI void mjp_defaultPlugin(mjpPlugin* plugin);
@@ -1333,7 +1372,8 @@ MJAPI const mjpResourceProvider* mjp_getResourceProvider(const char* resource_na
 // If invalid slot number, return NULL.
 MJAPI const mjpResourceProvider* mjp_getResourceProviderAtSlot(int slot);
 
-//---------------------- Thread -------------------------------------------------------------------
+
+//---------------------------------- Threads -------------------------------------------------------
 
 // Create a thread pool with the specified number of threads running.
 MJAPI mjThreadPool* mju_threadPoolCreate(size_t number_of_threads);
@@ -1353,10 +1393,301 @@ MJAPI void mju_defaultTask(mjTask* task);
 // Wait for a task to complete.
 MJAPI void mju_taskJoin(mjTask* task);
 
-//---------------------- Sanitizer instrumentation helpers -----------------------------------------
-//
-// Most MuJoCo users can ignore these functions, the following comments are aimed primarily at
-// MuJoCo developers.
+
+//---------------------------------- Attachment ----------------------------------------------------
+
+// Attach child body to a parent frame, return 0 on success.
+MJAPI int mjs_attachBody(mjsFrame* parent, const mjsBody* child,
+                         const char* prefix, const char* suffix);
+
+// Attach child frame to a parent body, return 0 on success.
+MJAPI int mjs_attachFrame(mjsBody* parent, const mjsFrame* child,
+                          const char* prefix, const char* suffix);
+
+// Detach body from mjSpec, remove all references and delete the body, return 0 on success.
+MJAPI int mjs_detachBody(mjSpec* s, mjsBody* b);
+
+
+//---------------------------------- Tree elements -------------------------------------------------
+
+// Add child body to body, return child.
+MJAPI mjsBody* mjs_addBody(mjsBody* body, mjsDefault* def);
+
+// Add site to body, return site spec.
+MJAPI mjsSite* mjs_addSite(mjsBody* body, mjsDefault* def);
+
+// Add joint to body.
+MJAPI mjsJoint* mjs_addJoint(mjsBody* body, mjsDefault* def);
+
+// Add freejoint to body.
+MJAPI mjsJoint* mjs_addFreeJoint(mjsBody* body);
+
+// Add geom to body.
+MJAPI mjsGeom* mjs_addGeom(mjsBody* body, mjsDefault* def);
+
+// Add camera to body.
+MJAPI mjsCamera* mjs_addCamera(mjsBody* body, mjsDefault* def);
+
+// Add light to body.
+MJAPI mjsLight* mjs_addLight(mjsBody* body, mjsDefault* def);
+
+// Add frame to body.
+MJAPI mjsFrame* mjs_addFrame(mjsBody* body, mjsFrame* parentframe);
+
+// Delete object corresponding to the given element.
+MJAPI void mjs_delete(mjsElement* element);
+
+
+//---------------------------------- Non-tree elements ---------------------------------------------
+
+// Add actuator.
+MJAPI mjsActuator* mjs_addActuator(mjSpec* s, mjsDefault* def);
+
+// Add sensor.
+MJAPI mjsSensor* mjs_addSensor(mjSpec* s);
+
+// Add flex.
+MJAPI mjsFlex* mjs_addFlex(mjSpec* s);
+
+// Add contact pair.
+MJAPI mjsPair* mjs_addPair(mjSpec* s, mjsDefault* def);
+
+// Add excluded body pair.
+MJAPI mjsExclude* mjs_addExclude(mjSpec* s);
+
+// Add equality.
+MJAPI mjsEquality* mjs_addEquality(mjSpec* s, mjsDefault* def);
+
+// Add tendon.
+MJAPI mjsTendon* mjs_addTendon(mjSpec* s, mjsDefault* def);
+
+// Wrap site using tendon.
+MJAPI mjsWrap* mjs_wrapSite(mjsTendon* tendon, const char* name);
+
+// Wrap geom using tendon.
+MJAPI mjsWrap* mjs_wrapGeom(mjsTendon* tendon, const char* name, const char* sidesite);
+
+// Wrap joint using tendon.
+MJAPI mjsWrap* mjs_wrapJoint(mjsTendon* tendon, const char* name, double coef);
+
+// Wrap pulley using tendon.
+MJAPI mjsWrap* mjs_wrapPulley(mjsTendon* tendon, double divisor);
+
+// Add numeric.
+MJAPI mjsNumeric* mjs_addNumeric(mjSpec* s);
+
+// Add text.
+MJAPI mjsText* mjs_addText(mjSpec* s);
+
+// Add tuple.
+MJAPI mjsTuple* mjs_addTuple(mjSpec* s);
+
+// Add keyframe.
+MJAPI mjsKey* mjs_addKey(mjSpec* s);
+
+// Add plugin.
+MJAPI mjsPlugin* mjs_addPlugin(mjSpec* s);
+
+// Add default.
+MJAPI mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, int parentid, int* id);
+
+
+//---------------------------------- Assets --------------------------------------------------------
+
+// Add mesh.
+MJAPI mjsMesh* mjs_addMesh(mjSpec* s, mjsDefault* def);
+
+// Add height field.
+MJAPI mjsHField* mjs_addHField(mjSpec* s);
+
+// Add skin.
+MJAPI mjsSkin* mjs_addSkin(mjSpec* s);
+
+// Add texture.
+MJAPI mjsTexture* mjs_addTexture(mjSpec* s);
+
+// Add material.
+MJAPI mjsMaterial* mjs_addMaterial(mjSpec* s, mjsDefault* def);
+
+
+//---------------------------------- Find and get utilities ----------------------------------------
+
+// Get spec from body.
+MJAPI mjSpec* mjs_getSpec(mjsBody* body);
+
+// Find body in model by name.
+MJAPI mjsBody* mjs_findBody(mjSpec* s, const char* name);
+
+// Find child body by name.
+MJAPI mjsBody* mjs_findChild(mjsBody* body, const char* name);
+
+// Find mesh by name.
+MJAPI mjsMesh* mjs_findMesh(mjSpec* s, const char* name);
+
+// Find frame by name.
+MJAPI mjsFrame* mjs_findFrame(mjSpec* s, const char* name);
+
+// Get default corresponding to an element.
+MJAPI mjsDefault* mjs_getDefault(mjsElement* element);
+
+// Find default in model by class name.
+MJAPI mjsDefault* mjs_findDefault(mjSpec* s, const char* classname);
+
+// Get global default from model.
+MJAPI mjsDefault* mjs_getSpecDefault(mjSpec* s);
+
+// Get element id.
+MJAPI int mjs_getId(mjsElement* element);
+
+// Return body's first child of given type.
+MJAPI mjsElement* mjs_firstChild(mjsBody* body, mjtObj type);
+
+// Return body's next child of the same type; return NULL if child is last.
+MJAPI mjsElement* mjs_nextChild(mjsBody* body, mjsElement* child);
+
+
+//---------------------------------- Attribute setters ---------------------------------------------
+
+// Copy text to string.
+MJAPI void mjs_setString(mjString* dest, const char* text);
+
+// Split text to entries and copy to string vector.
+MJAPI void mjs_setStringVec(mjStringVec* dest, const char* text);
+
+// Set entry in string vector.
+MJAPI mjtByte mjs_setInStringVec(mjStringVec* dest, int i, const char* text);
+
+// Append text entry to string vector.
+MJAPI void mjs_appendString(mjStringVec* dest, const char* text);
+
+// Copy int array to vector.
+MJAPI void mjs_setInt(mjIntVec* dest, const int* array, int size);
+
+// Append int array to vector of arrays.
+MJAPI void mjs_appendIntVec(mjIntVecVec* dest, const int* array, int size);
+
+// Copy float array to vector.
+MJAPI void mjs_setFloat(mjFloatVec* dest, const float* array, int size);
+
+// Append float array to vector of arrays.
+MJAPI void mjs_appendFloatVec(mjFloatVecVec* dest, const float* array, int size);
+
+// Copy double array to vector.
+MJAPI void mjs_setDouble(mjDoubleVec* dest, const double* array, int size);
+
+// Set plugin attributes.
+MJAPI void mjs_setPluginAttributes(mjsPlugin* plugin, void* attributes);
+
+
+//---------------------------------- Attribute getters ---------------------------------------------
+
+// Get string contents.
+MJAPI const char* mjs_getString(const mjString* source);
+
+// Get double array contents and optionally its size.
+MJAPI const double* mjs_getDouble(const mjDoubleVec* source, int* size);
+
+
+//---------------------------------- Spec utilities ------------------------------------------------
+
+// Set active plugins.
+MJAPI void mjs_setActivePlugins(mjSpec* s, void* activeplugins);
+
+// Set element's default.
+MJAPI void mjs_setDefault(mjsElement* element, mjsDefault* def);
+
+// Set element's enlcosing frame.
+MJAPI void mjs_setFrame(mjsElement* dest, mjsFrame* frame);
+
+// Resolve alternative orientations to quat, return error if any.
+MJAPI const char* mjs_resolveOrientation(double quat[4], mjtByte degree, const char* sequence,
+                                         const mjsOrientation* orientation);
+
+// Compute quat and diag inertia from full inertia matrix, return error if any.
+MJAPI const char* mjs_fullInertia(double quat[4], double inertia[3], const double fullinertia[6]);
+
+
+//---------------------------------- Element initialization  ---------------------------------------
+
+// Default spec attributes.
+MJAPI void mjs_defaultSpec(mjSpec* spec);
+
+// Default orientation attributes.
+MJAPI void mjs_defaultOrientation(mjsOrientation* orient);
+
+// Default body attributes.
+MJAPI void mjs_defaultBody(mjsBody* body);
+
+// Default frame attributes.
+MJAPI void mjs_defaultFrame(mjsFrame* frame);
+
+// Default joint attributes.
+MJAPI void mjs_defaultJoint(mjsJoint* joint);
+
+// Default geom attributes.
+MJAPI void mjs_defaultGeom(mjsGeom* geom);
+
+// Default site attributes.
+MJAPI void mjs_defaultSite(mjsSite* site);
+
+// Default camera attributes.
+MJAPI void mjs_defaultCamera(mjsCamera* camera);
+
+// Default light attributes.
+MJAPI void mjs_defaultLight(mjsLight* light);
+
+// Default flex attributes.
+MJAPI void mjs_defaultFlex(mjsFlex* flex);
+
+// Default mesh attributes.
+MJAPI void mjs_defaultMesh(mjsMesh* mesh);
+
+// Default height field attributes.
+MJAPI void mjs_defaultHField(mjsHField* hfield);
+
+// Default skin attributes.
+MJAPI void mjs_defaultSkin(mjsSkin* skin);
+
+// Default texture attributes.
+MJAPI void mjs_defaultTexture(mjsTexture* texture);
+
+// Default material attributes.
+MJAPI void mjs_defaultMaterial(mjsMaterial* material);
+
+// Default pair attributes.
+MJAPI void mjs_defaultPair(mjsPair* pair);
+
+// Default equality attributes.
+MJAPI void mjs_defaultEquality(mjsEquality* equality);
+
+// Default tendon attributes.
+MJAPI void mjs_defaultTendon(mjsTendon* tendon);
+
+// Default actuator attributes.
+MJAPI void mjs_defaultActuator(mjsActuator* actuator);
+
+// Default sensor attributes.
+MJAPI void mjs_defaultSensor(mjsSensor* sensor);
+
+// Default numeric attributes.
+MJAPI void mjs_defaultNumeric(mjsNumeric* numeric);
+
+// Default text attributes.
+MJAPI void mjs_defaultText(mjsText* text);
+
+// Default tuple attributes.
+MJAPI void mjs_defaultTuple(mjsTuple* tuple);
+
+// Default keyframe attributes.
+MJAPI void mjs_defaultKey(mjsKey* key);
+
+// Default plugin attributes.
+MJAPI void mjs_defaultPlugin(mjsPlugin* plugin);
+
+
+//---------------------------------- Sanitizer instrumentation -------------------------------------
+
+// Most users can ignore these functions, the following comments are primarily for developers.
 //
 // When built and run under address sanitizer (asan), mj_markStack and mj_freeStack are instrumented
 // to detect leakage of mjData stack frames. When the compiler inlines several callees that call

introspect/codegen/generate_structs.py

@@ -123,7 +123,7 @@ class MjStructVisitor:
     """Makes a Decl object from a Clang AST RecordDecl node."""
     name = f"{node['tagUsed']} {node['name']}" if 'name' in node else ''
     fields = []
-    for child in node['inner']:
+    for child in node.get('inner', ()):
       child_kind = child.get('kind')
       if child_kind == 'FieldDecl':
         fields.append(self._make_field(child))

introspect/enums.py

@@ -686,6 +686,69 @@ ENUMS: Mapping[str, EnumDecl] = dict([
              ('mjFONT_BIG', 2),
          ]),
      )),
+    ('mjtGeomInertia',
+     EnumDecl(
+         name='mjtGeomInertia',
+         declname='enum mjtGeomInertia_',
+         values=dict([
+             ('mjINERTIA_VOLUME', 0),
+             ('mjINERTIA_SHELL', 1),
+         ]),
+     )),
+    ('mjtBuiltin',
+     EnumDecl(
+         name='mjtBuiltin',
+         declname='enum mjtBuiltin_',
+         values=dict([
+             ('mjBUILTIN_NONE', 0),
+             ('mjBUILTIN_GRADIENT', 1),
+             ('mjBUILTIN_CHECKER', 2),
+             ('mjBUILTIN_FLAT', 3),
+         ]),
+     )),
+    ('mjtMark',
+     EnumDecl(
+         name='mjtMark',
+         declname='enum mjtMark_',
+         values=dict([
+             ('mjMARK_NONE', 0),
+             ('mjMARK_EDGE', 1),
+             ('mjMARK_CROSS', 2),
+             ('mjMARK_RANDOM', 3),
+         ]),
+     )),
+    ('mjtLimited',
+     EnumDecl(
+         name='mjtLimited',
+         declname='enum mjtLimited_',
+         values=dict([
+             ('mjLIMITED_FALSE', 0),
+             ('mjLIMITED_TRUE', 1),
+             ('mjLIMITED_AUTO', 2),
+         ]),
+     )),
+    ('mjtInertiaFromGeom',
+     EnumDecl(
+         name='mjtInertiaFromGeom',
+         declname='enum mjtInertiaFromGeom_',
+         values=dict([
+             ('mjINERTIAFROMGEOM_FALSE', 0),
+             ('mjINERTIAFROMGEOM_TRUE', 1),
+             ('mjINERTIAFROMGEOM_AUTO', 2),
+         ]),
+     )),
+    ('mjtOrientation',
+     EnumDecl(
+         name='mjtOrientation',
+         declname='enum mjtOrientation_',
+         values=dict([
+             ('mjORIENTATION_QUAT', 0),
+             ('mjORIENTATION_AXISANGLE', 1),
+             ('mjORIENTATION_XYAXES', 2),
+             ('mjORIENTATION_ZAXIS', 3),
+             ('mjORIENTATION_EULER', 4),
+         ]),
+     )),
     ('mjtButton',
      EnumDecl(
          name='mjtButton',

src/user/user_api.cc

@@ -52,7 +52,7 @@ static T& operator+(T& base, std::string_view suffix) {
 
 
 // create model
-mjSpec* mjs_createSpec() {
+mjSpec* mj_makeSpec() {
   mjCModel* modelC = new mjCModel;
   return &modelC->spec;
 }
@@ -60,7 +60,7 @@ mjSpec* mjs_createSpec() {
 
 
 // copy model
-mjSpec* mjs_copySpec(const mjSpec* s) {
+mjSpec* mj_copySpec(const mjSpec* s) {
   mjCModel* modelC = new mjCModel(*static_cast<mjCModel*>(s->element));
   return &modelC->spec;
 }
@@ -68,7 +68,7 @@ mjSpec* mjs_copySpec(const mjSpec* s) {
 
 
 // copy back model
-void mjs_copyBack(mjSpec* s, const mjModel* m) {
+void mj_copyBack(mjSpec* s, const mjModel* m) {
   mjCModel* modelC = static_cast<mjCModel*>(s->element);
   modelC->CopyBack(m);
 }
@@ -76,7 +76,7 @@ void mjs_copyBack(mjSpec* s, const mjModel* m) {
 
 
 // compile model
-mjModel* mjs_compile(mjSpec* s, const mjVFS* vfs) {
+mjModel* mj_compile(mjSpec* s, const mjVFS* vfs) {
   mjCModel* modelC = static_cast<mjCModel*>(s->element);
   return modelC->Compile(vfs);
 }
@@ -84,7 +84,7 @@ mjModel* mjs_compile(mjSpec* s, const mjVFS* vfs) {
 
 
 // recompile spec into existing model and data while preserving the state
-void mjs_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d) {
+void mj_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d) {
   mjCModel* modelC = static_cast<mjCModel*>(s->element);
   modelC->SaveState(d);
   modelC->Compile(vfs, &m);
@@ -143,7 +143,7 @@ int mjs_isWarning(mjSpec* s) {
 
 
 // delete model
-void mjs_deleteSpec(mjSpec* s) {
+void mj_deleteSpec(mjSpec* s) {
   mjCModel* model = static_cast<mjCModel*>(s->element);
   delete model;
 }
@@ -151,7 +151,7 @@ void mjs_deleteSpec(mjSpec* s) {
 
 
 // delete object, it will call the appropriate destructor since ~mjCBase is virtual
-void mjs_delete(mjElement* element) {
+void mjs_delete(mjsElement* element) {
   mjCBase* object = static_cast<mjCBase*>(element);
   delete object;
 }
@@ -430,7 +430,7 @@ mjsKey* mjs_addKey(mjSpec* s) {
 mjsPlugin* mjs_addPlugin(mjSpec* s) {
   mjCModel* modelC = static_cast<mjCModel*>(s->element);
   mjCPlugin* plugin = modelC->AddPlugin();
-  plugin->spec.instance = static_cast<mjElement*>(plugin);
+  plugin->spec.instance = static_cast<mjsElement*>(plugin);
   return &plugin->spec;
 }
 
@@ -458,7 +458,7 @@ mjSpec* mjs_getSpec(mjsBody* body) {
 
 
 // get default
-mjsDefault* mjs_getDefault(mjElement* element) {
+mjsDefault* mjs_getDefault(mjsElement* element) {
   return &(static_cast<mjCBase*>(element)->def->spec);
 }
 
@@ -530,7 +530,7 @@ mjsFrame* mjs_findFrame(mjSpec* s, const char* name) {
 
 
 // set frame
-void mjs_setFrame(mjElement* dest, mjsFrame* frame) {
+void mjs_setFrame(mjsElement* dest, mjsFrame* frame) {
   if (!frame) {
     return;
   }
@@ -550,14 +550,14 @@ const char* mjs_resolveOrientation(double quat[4], mjtByte degree, const char* s
 
 
 // get id
-int mjs_getId(mjElement* element) {
+int mjs_getId(mjsElement* element) {
   return static_cast<mjCBase*>(element)->id;
 }
 
 
 
 // set default
-void mjs_setDefault(mjElement* element, mjsDefault* defspec) {
+void mjs_setDefault(mjsElement* element, mjsDefault* defspec) {
   mjCBase* baseC = static_cast<mjCBase*>(element);
   baseC->def = static_cast<mjCDef*>(defspec->element);
 }
@@ -565,7 +565,7 @@ void mjs_setDefault(mjElement* element, mjsDefault* defspec) {
 
 
 // return first child of selected type
-mjElement* mjs_firstChild(mjsBody* body, mjtObj type) {
+mjsElement* mjs_firstChild(mjsBody* body, mjtObj type) {
   mjCBody* bodyC = static_cast<mjCBody*>(body->element);
   return bodyC->NextChild(NULL, type);
 }
@@ -573,7 +573,7 @@ mjElement* mjs_firstChild(mjsBody* body, mjtObj type) {
 
 
 // return body's next child; return NULL if child is last
-mjElement* mjs_nextChild(mjsBody* body, mjElement* child) {
+mjsElement* mjs_nextChild(mjsBody* body, mjsElement* child) {
   mjCBody* bodyC = static_cast<mjCBody*>(body->element);
   return bodyC->NextChild(child);
 }

src/user/user_api.h

@@ -20,6 +20,7 @@
 #include <mujoco/mjdata.h>
 #include <mujoco/mjexport.h>
 #include <mujoco/mjmodel.h>
+#include <mujoco/mjspec.h>
 #include <mujoco/mjtnum.h>
 
 
@@ -33,749 +34,19 @@ extern "C" {
 
 #define mjNAN NAN                  // used to mark undefined fields
 
-
-//---------------------------------- C/C++ handles to strings and arrays ---------------------------
-
-#ifdef __cplusplus
-  // C++, defined to be compatible with corresponding std types
-  using mjString = std::string;
-  using mjStringVec = std::vector<std::string>;
-  using mjIntVec = std::vector<int>;
-  using mjIntVecVec = std::vector<std::vector<int>>;
-  using mjFloatVec = std::vector<float>;
-  using mjFloatVecVec = std::vector<std::vector<float>>;
-  using mjDoubleVec = std::vector<double>;
-#else
-  // C, opaque pointers
-  typedef struct mjString_ mjString;
-  typedef struct mjStringVec_ mjStringVec;
-  typedef struct mjIntVec_ mjIntVec;
-  typedef struct mjIntVecVec_ mjIntVecVec;
-  typedef struct mjFloatVec_ mjFloatVec;
-  typedef struct mjFloatVecVec_ mjFloatVecVec;
-  typedef struct mjDoubleVec_ mjDoubleVec;
-#endif
-
-
-//---------------------------------- enum types (mjt) ----------------------------------------------
-
-typedef enum mjtGeomInertia_ {     // type of inertia inference
-  mjINERTIA_VOLUME,                // mass distributed in the volume
-  mjINERTIA_SHELL,                 // mass distributed on the surface
-} mjtGeomInertia;
-
-
-typedef enum mjtBuiltin_ {         // type of built-in procedural texture
-  mjBUILTIN_NONE = 0,              // no built-in texture
-  mjBUILTIN_GRADIENT,              // gradient: rgb1->rgb2
-  mjBUILTIN_CHECKER,               // checker pattern: rgb1, rgb2
-  mjBUILTIN_FLAT                   // 2d: rgb1; cube: rgb1-up, rgb2-side, rgb3-down
-} mjtBuiltin;
-
-
-typedef enum mjtMark_ {            // mark type for procedural textures
-  mjMARK_NONE = 0,                 // no mark
-  mjMARK_EDGE,                     // edges
-  mjMARK_CROSS,                    // cross
-  mjMARK_RANDOM                    // random dots
-} mjtMark;
-
-
-typedef enum mjtLimited_ {         // type of limit specification
-  mjLIMITED_FALSE = 0,             // not limited
-  mjLIMITED_TRUE,                  // limited
-  mjLIMITED_AUTO,                  // limited inferred from presence of range
-} mjtLimited;
-
-
-typedef enum mjtInertiaFromGeom_ { // whether to infer body inertias from child geoms
-  mjINERTIAFROMGEOM_FALSE = 0,     // do not use; inertial element required
-  mjINERTIAFROMGEOM_TRUE,          // always use; overwrite inertial element
-  mjINERTIAFROMGEOM_AUTO           // use only if inertial element is missing
-} mjtInertiaFromGeom;
-
-
-typedef enum mjtOrientation_ {     // type of orientation specifier
-  mjORIENTATION_QUAT = 0,          // quaternion
-  mjORIENTATION_AXISANGLE,         // axis and angle
-  mjORIENTATION_XYAXES,            // x and y axes
-  mjORIENTATION_ZAXIS,             // z axis (minimal rotation)
-  mjORIENTATION_EULER,             // Euler angles
-} mjtOrientation;
-
-
-//---------------------------------- attribute structs (mjs) ---------------------------------------
-
-typedef struct mjElement_ {        // element type, do not modify
-  mjtObj elemtype;                 // element type
-} mjElement;
-
-
-typedef struct mjSpec_ {           // model specification
-  mjElement* element;              // element type
-  mjString* modelname;             // model name
-
-  // compiler settings
-  mjtByte autolimits;              // infer "limited" attribute based on range
-  double boundmass;                // enforce minimum body mass
-  double boundinertia;             // enforce minimum body diagonal inertia
-  double settotalmass;             // rescale masses and inertias; <=0: ignore
-  mjtByte balanceinertia;          // automatically impose A + B >= C rule
-  mjtByte strippath;               // automatically strip paths from mesh files
-  mjtByte fitaabb;                 // meshfit to aabb instead of inertia box
-  mjtByte degree;                  // angles in radians or degrees
-  char euler[3];                   // sequence for euler rotations
-  mjString* meshdir;               // mesh and hfield directory
-  mjString* texturedir;            // texture directory
-  mjtByte discardvisual;           // discard visual geoms in parser
-  mjtByte convexhull;              // compute mesh convex hulls
-  mjtByte usethread;               // use multiple threads to speed up compiler
-  mjtByte fusestatic;              // fuse static bodies with parent
-  int inertiafromgeom;             // use geom inertias (mjtInertiaFromGeom)
-  int inertiagrouprange[2];        // range of geom groups used to compute inertia
-  mjtByte exactmeshinertia;        // if false, use old formula
-  mjLROpt LRopt;                   // options for lengthrange computation
-
-  // engine data
-  mjOption option;                 // physics options
-  mjVisual visual;                 // visual options
-  mjStatistic stat;                // statistics override (if defined)
-
-  // sizes
-  size_t memory;                   // number of bytes in arena+stack memory
-  int nemax;                       // max number of equality constraints
-  int nuserdata;                   // number of mjtNums in userdata
-  int nuser_body;                  // number of mjtNums in body_user
-  int nuser_jnt;                   // number of mjtNums in jnt_user
-  int nuser_geom;                  // number of mjtNums in geom_user
-  int nuser_site;                  // number of mjtNums in site_user
-  int nuser_cam;                   // number of mjtNums in cam_user
-  int nuser_tendon;                // number of mjtNums in tendon_user
-  int nuser_actuator;              // number of mjtNums in actuator_user
-  int nuser_sensor;                // number of mjtNums in sensor_user
-  int nkey;                        // number of keyframes
-  int njmax;                       // (deprecated) max number of constraints
-  int nconmax;                     // (deprecated) max number of detected contacts
-  size_t nstack;                   // (deprecated) number of mjtNums in mjData stack
-
-  // global data
-  mjString* comment;               // comment at top of XML
-  mjString* modelfiledir;          // path to model file
-
-  // other
-  mjtByte hasImplicitPluginElem;   // already encountered an implicit plugin sensor/actuator
-} mjSpec;
-
-
-typedef struct mjsOrientation_ {   // alternative orientation specifiers
-  mjtOrientation type;             // active orientation specifier
-  double axisangle[4];             // axis and angle
-  double xyaxes[6];                // x and y axes
-  double zaxis[3];                 // z axis (minimal rotation)
-  double euler[3];                 // Euler angles
-} mjsOrientation;
-
-
-typedef struct mjsPlugin_ {        // plugin specification
-  mjElement* instance;             // element type
-  mjString* name;                  // name
-  mjString* instance_name;         // instance name
-  int plugin_slot;                 // global registered slot number of the plugin
-  mjtByte active;                  // is the plugin active
-  mjString* info;                  // message appended to compiler errors
-} mjsPlugin;
-
-
-typedef struct mjsBody_ {          // body specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* childclass;            // childclass name
-
-  // body frame
-  double pos[3];                   // frame position
-  double quat[4];                  // frame orientation
-  mjsOrientation alt;              // frame alternative orientation
-
-  // inertial frame
-  double mass;                     // mass
-  double ipos[3];                  // inertial frame position
-  double iquat[4];                 // inertial frame orientation
-  double inertia[3];               // diagonal inertia (in i-frame)
-  mjsOrientation ialt;             // inertial frame alternative orientation
-  double fullinertia[6];           // non-axis-aligned inertia matrix
-
-  // other
-  mjtByte mocap;                   // is this a mocap body
-  double gravcomp;                 // gravity compensation
-  mjDoubleVec* userdata;           // user data
-  mjtByte explicitinertial;        // whether to save the body with explicit inertial clause
-  mjsPlugin plugin;                // passive force plugin
-  mjString* info;                  // message appended to compiler errors
-} mjsBody;
-
-
-typedef struct mjsFrame_ {         // frame specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* childclass;            // childclass name
-  double pos[3];                   // position
-  double quat[4];                  // orientation
-  mjsOrientation alt;              // alternative orientation
-  mjString* info;                  // message appended to compiler errors
-} mjsFrame;
-
-
-typedef struct mjsJoint_ {         // joint specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjtJoint type;                   // joint type
-
-  // kinematics
-  double pos[3];                   // anchor position
-  double axis[3];                  // joint axis
-  double ref;                      // value at reference configuration: qpos0
-
-  // stiffness
-  double stiffness;                // stiffness coefficient
-  double springref;                // spring reference value: qpos_spring
-  double springdamper[2];          // timeconst, dampratio
-
-  // limits
-  int limited;                     // does joint have limits (mjtLimited)
-  double range[2];                 // joint limits
-  double margin;                   // margin value for joint limit detection
-  mjtNum solref_limit[mjNREF];     // solver reference: joint limits
-  mjtNum solimp_limit[mjNIMP];     // solver impedance: joint limits
-  int actfrclimited;               // are actuator forces on joint limited (mjtLimited)
-  double actfrcrange[2];           // actuator force limits
-
-  // dof properties
-  double armature;                 // armature inertia (mass for slider)
-  double damping;                  // damping coefficient
-  double frictionloss;             // friction loss
-  mjtNum solref_friction[mjNREF];  // solver reference: dof friction
-  mjtNum solimp_friction[mjNIMP];  // solver impedance: dof friction
-
-  // other
-  int group;                       // group
-  mjtByte actgravcomp;             // is gravcomp force applied via actuators
-  mjDoubleVec* userdata;           // user data
-  mjString* info;                  // message appended to compiler errors
-} mjsJoint;
-
-
-typedef struct mjsGeom_ {          // geom specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // classname
-  mjtGeom type;                    // geom type
-
-  // frame, size
-  double pos[3];                   // position
-  double quat[4];                  // orientation
-  mjsOrientation alt;              // alternative orientation
-  double fromto[6];                // alternative for capsule, cylinder, box, ellipsoid
-  double size[3];                  // type-specific size
-
-  // contact related
-  int contype;                     // contact type
-  int conaffinity;                 // contact affinity
-  int condim;                      // contact dimensionality
-  int priority;                    // contact priority
-  double friction[3];              // one-sided friction coefficients: slide, roll, spin
-  double solmix;                   // solver mixing for contact pairs
-  mjtNum solref[mjNREF];           // solver reference
-  mjtNum solimp[mjNIMP];           // solver impedance
-  double margin;                   // margin for contact detection
-  double gap;                      // include in solver if dist < margin-gap
-
-  // inertia inference
-  double mass;                     // used to compute density
-  double density;                  // used to compute mass and inertia from volume or surface
-  mjtGeomInertia typeinertia;      // selects between surface and volume inertia
-
-  // fluid forces
-  mjtNum fluid_ellipsoid;          // whether ellipsoid-fluid model is active
-  mjtNum fluid_coefs[5];           // ellipsoid-fluid interaction coefs
-
-  // visual
-  mjString* material;              // name of material
-  float rgba[4];                   // rgba when material is omitted
-  int group;                       // group
-
-  // other
-  mjString* hfieldname;            // heightfield attached to geom
-  mjString* meshname;              // mesh attached to geom
-  double fitscale;                 // scale mesh uniformly
-  mjDoubleVec* userdata;           // user data
-  mjsPlugin plugin;                // sdf plugin
-  mjString* info;                  // message appended to compiler errors
-} mjsGeom;
-
-
-typedef struct mjsSite_ {          // site specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // frame, size
-  double pos[3];                   // position
-  double quat[4];                  // orientation
-  mjsOrientation alt;              // alternative orientation
-  double fromto[6];                // alternative for capsule, cylinder, box, ellipsoid
-  double size[3];                  // geom size
-
-  // visual
-  mjtGeom type;                    // geom type
-  mjString* material;              // name of material
-  int group;                       // group
-  float rgba[4];                   // rgba when material is omitted
-
-  // other
-  mjDoubleVec* userdata;           // user data
-  mjString* info;                  // message appended to compiler errors
-} mjsSite;
-
-
-typedef struct mjsCamera_ {        // camera specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // extrinsics
-  double pos[3];                   // position
-  double quat[4];                  // orientation
-  mjsOrientation alt;              // alternative orientation
-  mjtCamLight mode;                // tracking mode
-  mjString* targetbody;            // target body for tracking/targeting
-
-  // intrinsics
-  double fovy;                     // y-field of view
-  double ipd;                      // inter-pupilary distance
-  float intrinsic[4];              // camera intrinsics (length)
-  float sensor_size[2];            // sensor size (length)
-  float resolution[2];             // resolution (pixel)
-  float focal_length[2];           // focal length (length)
-  float focal_pixel[2];            // focal length (pixel)
-  float principal_length[2];       // principal point (length)
-  float principal_pixel[2];        // principal point (pixel)
-
-  // other
-  mjDoubleVec* userdata;           // user data
-  mjString* info;                  // message appended to compiler errors
-} mjsCamera;
-
-
-typedef struct mjsLight_ {         // light specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // frame
-  double pos[3];                   // position
-  double dir[3];                   // direction
-  mjtCamLight mode;                // tracking mode
-  mjString* targetbody;            // target body for targeting
-
-  // intrinsics
-  mjtByte active;                  // is light active
-  mjtByte directional;             // is light directional or spot
-  mjtByte castshadow;              // does light cast shadows
-  double bulbradius;               // bulb radius, for soft shadows
-  float attenuation[3];            // OpenGL attenuation (quadratic model)
-  float cutoff;                    // OpenGL cutoff
-  float exponent;                  // OpenGL exponent
-  float ambient[3];                // ambient color
-  float diffuse[3];                // diffuse color
-  float specular[3];               // specular color
-
-  // other
-  mjString* info;                  // message appended to compiler errorsx
-} mjsLight;
-
-
-typedef struct mjsFlex_ {
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // contact properties
-  int contype;                     // contact type
-  int conaffinity;                 // contact affinity
-  int condim;                      // contact dimensionality
-  int priority;                    // contact priority
-  double friction[3];              // one-sided friction coefficients: slide, roll, spin
-  double solmix;                   // solver mixing for contact pairs
-  mjtNum solref[mjNREF];           // solver reference
-  mjtNum solimp[mjNIMP];           // solver impedance
-  double margin;                   // margin for contact detection
-  double gap;                      // include in solver if dist<margin-gap
-
-  // other properties
-  int dim;                         // element dimensionality
-  double radius;                   // radius around primitive element
-  mjtByte internal;                // enable internal collisions
-  mjtByte flatskin;                // render flex skin with flat shading
-  int selfcollide;                 // mode for flex self colllision
-  int activelayers;                // number of active element layers in 3D
-  int group;                       // group for visualizatioh
-  double edgestiffness;            // edge stiffness
-  double edgedamping;              // edge damping
-  float rgba[4];                   // rgba when material is omitted
-  mjString* material;              // name of material used for rendering
-
-  // mesh properties
-  mjStringVec* vertbody;           // vertex body names
-  mjDoubleVec* vert;               // vertex positions
-  mjIntVec* elem;                  // element vertex ids
-  mjFloatVec* texcoord;            // vertex texture coordinates
-
-  // other
-  mjString* info;                  // message appended to compiler errors
-} mjsFlex;
-
-
-typedef struct mjsMesh_ {          // mesh specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjString* content_type;          // content type of file
-  mjString* file;                  // mesh file
-  double refpos[3];                // reference position
-  double refquat[4];               // reference orientation
-  double scale[3];                 // rescale mesh
-  mjtByte smoothnormal;            // do not exclude large-angle faces from normals
-  int maxhullvert;                 // maximum vertex count for the convex hull
-  mjFloatVec* uservert;            // user vertex data
-  mjFloatVec* usernormal;          // user normal data
-  mjFloatVec* usertexcoord;        // user texcoord data
-  mjIntVec* userface;              // user vertex indices
-  mjIntVec* userfacenormal;        // user normal indices
-  mjIntVec* userfacetexcoord;      // user texcoord indices
-  mjsPlugin plugin;                // sdf plugin
-  mjString* info;                  // message appended to compiler errors
-} mjsMesh;
-
-
-typedef struct mjsHField_ {        // height field specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* content_type;          // content type of file
-  mjString* file;                  // file: (nrow, ncol, [elevation data])
-  double size[4];                  // hfield size (ignore referencing geom size)
-  int nrow;                        // number of rows
-  int ncol;                        // number of columns
-  mjFloatVec* userdata;            // user-provided elevation data
-  mjString* info;                  // message appended to compiler errors
-} mjsHField;
-
-
-
-typedef struct mjsSkin_ {          // skin specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjString* file;                  // skin file
-  mjString* material;              // name of material used for rendering
-  float rgba[4];                   // rgba when material is omitted
-  float inflate;                   // inflate in normal direction
-  int group;                       // group for visualization
-
-  // mesh
-  mjFloatVec* vert;                // vertex positions
-  mjFloatVec* texcoord;            // texture coordinates
-  mjIntVec* face;                  // faces
-
-  // skin
-  mjStringVec* bodyname;           // body names
-  mjFloatVec* bindpos;             // bind pos
-  mjFloatVec* bindquat;            // bind quat
-  mjIntVecVec* vertid;             // vertex ids
-  mjFloatVecVec* vertweight;       // vertex weights
-
-  // other
-  mjString* info;                  // message appended to compiler errors
-} mjsSkin;
-
-
-typedef struct mjsTexture_ {       // texture specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjtTexture type;                 // texture type
-
-  // method 1: builtin
-  int builtin;                     // builtin type (mjtBuiltin)
-  int mark;                        // mark type (mjtMark)
-  double rgb1[3];                  // first color for builtin
-  double rgb2[3];                  // second color for builtin
-  double markrgb[3];               // mark color
-  double random;                   // probability of random dots
-  int height;                      // height in pixels (square for cube and skybox)
-  int width;                       // width in pixels
-
-  // method 2: single file
-  mjString* content_type;          // content type of file
-  mjString* file;                  // png file to load; use for all sides of cube
-  int gridsize[2];                 // size of grid for composite file; (1,1)-repeat
-  char gridlayout[13];             // row-major: L,R,F,B,U,D for faces; . for unused
-
-  // method 3: separate files
-  mjStringVec* cubefiles;          // different file for each side of the cube
-
-  // flip options
-  mjtByte hflip;                   // horizontal flip
-  mjtByte vflip;                   // vertical flip
-
-  // other
-  mjString* info;                  // message appended to compiler errors
-} mjsTexture;
-
-
-typedef struct mjsMaterial_ {      // material specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjString* texture;               // name of texture (empty: none)
-  mjtByte texuniform;              // make texture cube uniform
-  float texrepeat[2];              // texture repetition for 2D mapping
-  float emission;                  // emission
-  float specular;                  // specular
-  float shininess;                 // shininess
-  float reflectance;               // reflectance
-  float metallic;                  // metallic
-  float roughness;                 // roughness
-  float rgba[4];                   // rgba
-  mjString* info;                  // message appended to compiler errors
-} mjsMaterial;
-
-
-typedef struct mjsPair_ {
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjString* geomname1;             // name of geom 1
-  mjString* geomname2;             // name of geom 2
-
-  // optional parameters: computed from geoms if not set by user
-  int condim;                      // contact dimensionality
-  mjtNum solref[mjNREF];           // solver reference, normal direction
-  mjtNum solreffriction[mjNREF];   // solver reference, frictional directions
-  mjtNum solimp[mjNIMP];           // solver impedance
-  double margin;                   // margin for contact detection
-  double gap;                      // include in solver if dist<margin-gap
-  double friction[5];              // full contact friction
-  mjString* info;                  // message appended to errors
-} mjsPair;
-
-
-typedef struct mjsExclude_ {
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* bodyname1;             // name of geom 1
-  mjString* bodyname2;             // name of geom 2
-  mjString* info;                  // message appended to errors
-} mjsExclude;
-
-
-typedef struct mjsEquality_ {      // equality specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-  mjtEq type;                      // constraint type
-  double data[mjNEQDATA];          // type-dependent data
-  mjtByte active;                  // is equality initially active
-  mjString* name1;                 // name of object 1
-  mjString* name2;                 // name of object 2
-  mjtNum solref[mjNREF];           // solver reference
-  mjtNum solimp[mjNIMP];           // solver impedance
-  mjString* info;                  // message appended to errors
-} mjsEquality;
-
-
-typedef struct mjsTendon_ {        // tendon specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // stiffness, damping, friction
-  double stiffness;                // stiffness coefficient
-  double springlength[2];          // spring resting length; {-1, -1}: use qpos_spring
-  double damping;                  // damping coefficient
-  double frictionloss;             // friction loss
-  mjtNum solref_friction[mjNREF];  // solver reference: tendon friction
-  mjtNum solimp_friction[mjNIMP];  // solver impedance: tendon friction
-
-  // length range
-  int limited;                     // does tendon have limits (mjtLimited)
-  double range[2];                 // length limits
-  double margin;                   // margin value for tendon limit detection
-  mjtNum solref_limit[mjNREF];     // solver reference: tendon limits
-  mjtNum solimp_limit[mjNIMP];     // solver impedance: tendon limits
-
-  // visual
-  mjString* material;              // name of material for rendering
-  double width;                    // width for rendering
-  float rgba[4];                   // rgba when material is omitted
-  int group;                       // group
-
-  // other
-  mjDoubleVec* userdata;           // user data
-  mjString* info;                  // message appended to errors
-} mjsTendon;
-
-
-typedef struct mjsWrap_ {          // wrapping object specification
-  mjElement* element;              // element type
-  mjString* info;                  // message appended to errors
-} mjsWrap;
-
-
-typedef struct mjsActuator_ {      // actuator specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // gain, bias
-  mjtGain gaintype;                // gain type
-  double gainprm[mjNGAIN];         // gain parameters
-  mjtBias biastype;                // bias type
-  double biasprm[mjNGAIN];         // bias parameters
-
-  // activation state
-  mjtDyn dyntype;                  // dynamics type
-  double dynprm[mjNDYN];           // dynamics parameters
-  int actdim;                      // number of activation variables
-  int plugin_actdim;               // actuator state size for plugins
-  mjtByte actearly;                // apply next activations to qfrc
-
-  // transmission
-  mjtTrn trntype;                  // transmission type
-  double gear[6];                  // length and transmitted force scaling
-  mjString* target;                // name of transmission target
-  mjString* refsite;               // reference site, for site transmission
-  mjString* slidersite;            // site defining cylinder, for slider-crank
-  double cranklength;              // crank length, for slider-crank
-  double lengthrange[2];           // transmission length range
-  double inheritrange;             // automatic range setting for position and intvelocity
-
-  // input/output clamping
-  int ctrllimited;                 // are control limits defined (mjtLimited)
-  double ctrlrange[2];             // control range
-  int forcelimited;                // are force limits defined (mjtLimited)
-  double forcerange[2];            // force range
-  int actlimited;                  // are activation limits defined (mjtLimited)
-  double actrange[2];              // activation range
-
-  // other
-  int group;                       // group
-  mjDoubleVec* userdata;           // user data
-  mjsPlugin plugin;                // actuator plugin
-  mjString* info;                  // message appended to compiler errors
-} mjsActuator;
-
-
-typedef struct mjsSensor_ {        // sensor specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* classname;             // class name
-
-  // sensor defintion
-  mjtSensor type;                  // type of sensor
-  mjtObj objtype;                  // type of sensorized object
-  mjString* objname;               // name of sensorized object
-  mjtObj reftype;                  // type of referenced object
-  mjString* refname;               // name of referenced object
-
-  // user-defined sensors
-  mjtDataType datatype;            // data type for sensor measurement
-  mjtStage needstage;              // compute stage needed to simulate sensor
-  int dim;                         // number of scalar outputs
-
-  // output post-processing
-  double cutoff;                   // cutoff for real and positive datatypes
-  double noise;                    // noise stdev
-
-  // other
-  mjDoubleVec* userdata;           // user data
-  mjsPlugin plugin;                // sensor plugin
-  mjString* info;                  // message appended to compiler errors
-} mjsSensor;
-
-
-typedef struct mjsNumeric_ {       // custom numeric field specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjDoubleVec* data;               // initialization data
-  int size;                        // array size, can be bigger than data size
-  mjString* info;                  // message appended to compiler errors
-} mjsNumeric;
-
-
-typedef struct mjsText_ {          // custom text specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjString* data;                  // text string
-  mjString* info;                  // message appended to compiler errors
-} mjsText;
-
-
-typedef struct mjsTuple_ {         // tuple specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  mjIntVec* objtype;               // object types
-  mjStringVec* objname;            // object names
-  mjDoubleVec* objprm;             // object parameters
-  mjString* info;                  // message appended to compiler errors
-} mjsTuple;
-
-
-typedef struct mjsKey_ {           // keyframe specification
-  mjElement* element;              // element type
-  mjString* name;                  // name
-  double time;                     // time
-  mjDoubleVec* qpos;               // qpos
-  mjDoubleVec* qvel;               // qvel
-  mjDoubleVec* act;                // act
-  mjDoubleVec* mpos;               // mocap pos
-  mjDoubleVec* mquat;              // mocap quat
-  mjDoubleVec* ctrl;               // ctrl
-  mjString* info;                  // message appended to compiler errors
-} mjsKey;
-
-
-typedef struct mjsDefault_ {       // default specification
-  mjElement* element;              // element type
-  mjString* name;                  // class name
-  mjsJoint* joint;                 // joint defaults
-  mjsGeom* geom;                   // geom defaults
-  mjsSite* site;                   // site defaults
-  mjsCamera* camera;               // camera defaults
-  mjsLight* light;                 // light defaults
-  mjsFlex* flex;                   // flex defaults
-  mjsMesh* mesh;                   // mesh defaults
-  mjsMaterial* material;           // material defaults
-  mjsPair* pair;                   // pair defaults
-  mjsEquality* equality;           // equality defaults
-  mjsTendon* tendon;               // tendon defaults
-  mjsActuator* actuator;           // actuator defaults
-} mjsDefault;
-
-
 //---------------------------------- Top-level spec manipulation -----------------------------------
 
 // Create spec.
-MJAPI mjSpec* mjs_createSpec(void);
+MJAPI mjSpec* mj_makeSpec(void);
 
 // Compile spec to model.
-MJAPI mjModel* mjs_compile(mjSpec* s, const mjVFS* vfs);
+MJAPI mjModel* mj_compile(mjSpec* s, const mjVFS* vfs);
 
 // Recompile spec to model preserving the current state.
-MJAPI void mjs_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d);
+MJAPI void mj_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d);
 
 // Copy spec.
-MJAPI mjSpec* mjs_copySpec(const mjSpec* s);
+MJAPI mjSpec* mj_copySpec(const mjSpec* s);
 
 // Get compiler error message from spec.
 MJAPI const char* mjs_getError(mjSpec* s);
@@ -784,10 +55,10 @@ MJAPI const char* mjs_getError(mjSpec* s);
 MJAPI int mjs_isWarning(mjSpec* s);
 
 // Copy model fields back into spec.
-MJAPI void mjs_copyBack(mjSpec* s, const mjModel* m);
+MJAPI void mj_copyBack(mjSpec* s, const mjModel* m);
 
 // Delete spec.
-MJAPI void mjs_deleteSpec(mjSpec* s);
+MJAPI void mj_deleteSpec(mjSpec* s);
 
 
 //---------------------------------- Attachment ----------------------------------------------------
@@ -831,7 +102,7 @@ MJAPI mjsLight* mjs_addLight(mjsBody* body, mjsDefault* def);
 MJAPI mjsFrame* mjs_addFrame(mjsBody* body, mjsFrame* parentframe);
 
 // Delete object corresponding to the given element.
-MJAPI void mjs_delete(mjElement* element);
+MJAPI void mjs_delete(mjsElement* element);
 
 
 //---------------------------------- Add non-tree elements -----------------------------------------
@@ -924,7 +195,7 @@ MJAPI mjsMesh* mjs_findMesh(mjSpec* s, const char* name);
 MJAPI mjsFrame* mjs_findFrame(mjSpec* s, const char* name);
 
 // Get default corresponding to an element.
-MJAPI mjsDefault* mjs_getDefault(mjElement* element);
+MJAPI mjsDefault* mjs_getDefault(mjsElement* element);
 
 // Find default in model by class name.
 MJAPI mjsDefault* mjs_findDefault(mjSpec* s, const char* classname);
@@ -933,16 +204,16 @@ MJAPI mjsDefault* mjs_findDefault(mjSpec* s, const char* classname);
 MJAPI mjsDefault* mjs_getSpecDefault(mjSpec* s);
 
 // Get element id.
-MJAPI int mjs_getId(mjElement* element);
+MJAPI int mjs_getId(mjsElement* element);
 
 
 //---------------------------------- Tree traversal ------------------------------------------------
 
 // Return body's first child of given type.
-MJAPI mjElement* mjs_firstChild(mjsBody* body, mjtObj type);
+MJAPI mjsElement* mjs_firstChild(mjsBody* body, mjtObj type);
 
 // Return body's next child of the same type; return NULL if child is last.
-MJAPI mjElement* mjs_nextChild(mjsBody* body, mjElement* child);
+MJAPI mjsElement* mjs_nextChild(mjsBody* body, mjsElement* child);
 
 
 //---------------------------------- Attribute setters ---------------------------------------------
@@ -993,10 +264,10 @@ MJAPI const double* mjs_getDouble(const mjDoubleVec* source, int* size);
 MJAPI void mjs_setActivePlugins(mjSpec* s, void* activeplugins);
 
 // Set element's default.
-MJAPI void mjs_setDefault(mjElement* element, mjsDefault* def);
+MJAPI void mjs_setDefault(mjsElement* element, mjsDefault* def);
 
 // Set element's enlcosing frame.
-MJAPI void mjs_setFrame(mjElement* dest, mjsFrame* frame);
+MJAPI void mjs_setFrame(mjsElement* dest, mjsFrame* frame);
 
 // Resolve alternative orientations to quat, return error if any.
 MJAPI const char* mjs_resolveOrientation(double quat[4], mjtByte degree, const char* sequence,

src/user/user_composite.cc

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_composite.h"
 
 #include <algorithm>

src/user/user_composite.h

@@ -20,7 +20,7 @@
 #include <vector>
 
 #include <mujoco/mjmodel.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_model.h"
 #include "user/user_objects.h"
 

src/user/user_flexcomp.cc

@@ -34,7 +34,7 @@
 #include "engine/engine_util_misc.h"
 #include "engine/engine_util_spatial.h"
 #include "user/user_flexcomp.h"
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_model.h"
 #include "user/user_objects.h"
 #include "user/user_util.h"
@@ -443,7 +443,7 @@ bool mjCFlexcomp::Make(mjSpec* spec, mjsBody* body, char* error, int error_sz) {
       if (plugin.active) {
         mjsPlugin* pplugin = &body->plugin;
         pplugin->active = true;
-        pplugin->instance = static_cast<mjElement*>(plugin.instance);
+        pplugin->instance = static_cast<mjsElement*>(plugin.instance);
         mjs_setString(pplugin->name, mjs_getString(plugin.name));
         mjs_setString(pplugin->instance_name, plugin_instance_name.c_str());
       }
@@ -507,7 +507,7 @@ bool mjCFlexcomp::Make(mjSpec* spec, mjsBody* body, char* error, int error_sz) {
       if (plugin.active) {
         mjsPlugin* pplugin = &pb->plugin;
         pplugin->active = true;
-        pplugin->instance = static_cast<mjElement*>(plugin.instance);
+        pplugin->instance = static_cast<mjsElement*>(plugin.instance);
         mjs_setString(pplugin->name, mjs_getString(plugin.name));
         mjs_setString(pplugin->instance_name, plugin_instance_name.c_str());
       }

src/user/user_flexcomp.h

@@ -19,7 +19,7 @@
 #include <vector>
 
 #include <mujoco/mujoco.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_model.h"
 #include "user/user_objects.h"
 

src/user/user_init.c

@@ -15,6 +15,7 @@
 #include <string.h>
 #include <mujoco/mjmodel.h>
 #include <mujoco/mjvisualize.h>
+#include <mujoco/mjspec.h>
 #include "engine/engine_io.h"
 #include "user/user_api.h"
 

src/user/user_mesh.cc

@@ -27,6 +27,7 @@
 #include <utility>
 #include <vector>
 
+#include <mujoco/mjspec.h>
 #include "user/user_api.h"
 
 #ifdef MUJOCO_TINYOBJLOADER_IMPL
@@ -196,7 +197,7 @@ mjCMesh& mjCMesh::operator=(const mjCMesh& other) {
 
 
 void mjCMesh::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.file = &spec_file_;
@@ -1983,7 +1984,7 @@ mjCSkin& mjCSkin::operator=(const mjCSkin& other) {
 
 
 void mjCSkin::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.file = &spec_file_;
@@ -2395,7 +2396,7 @@ mjCFlex& mjCFlex::operator=(const mjCFlex& other) {
 
 
 void mjCFlex::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.material = &spec_material_;

src/user/user_model.cc

@@ -28,6 +28,7 @@
 #include <mujoco/mjdata.h>
 #include <mujoco/mjmacro.h>
 #include <mujoco/mjmodel.h>
+#include <mujoco/mjspec.h>
 #include <mujoco/mjtnum.h>
 #include <mujoco/mjplugin.h>
 #include <mujoco/mjvisualize.h>
@@ -416,7 +417,7 @@ void mjCModel::CreateObjectLists() {
 
 
 void mjCModel::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.comment = &spec_comment_;
   spec.modelfiledir = &spec_modelfiledir_;
   spec.modelname = &spec_modelname_;

src/user/user_model.h

@@ -27,13 +27,13 @@
 #include <mujoco/mjmodel.h>
 #include <mujoco/mjplugin.h>
 #include <mujoco/mjtnum.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_objects.h"
 
 typedef std::map<std::string, int, std::less<> > mjKeyMap;
 typedef std::array<mjKeyMap, mjNOBJECT> mjListKeyMap;
 
-class mjCModel_ : public mjElement {
+class mjCModel_ : public mjsElement {
  public:
   // attach namespaces
   std::string prefix;

src/user/user_objects.cc

@@ -45,6 +45,7 @@
 #include "engine/engine_util_misc.h"
 #include "engine/engine_util_solve.h"
 #include "engine/engine_util_spatial.h"
+#include <mujoco/mjspec.h>
 #include "user/user_api.h"
 #include "user/user_cache.h"
 #include "user/user_model.h"
@@ -640,7 +641,7 @@ void mjCDef::PointToLocal() {
   equality_.PointToLocal();
   tendon_.PointToLocal();
   actuator_.PointToLocal();
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.joint = &joint_.spec;
   spec.geom = &geom_.spec;
@@ -949,7 +950,7 @@ mjCBody& mjCBody::operator-=(const mjCBody& subtree) {
 
 
 void mjCBody::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.childclass = &classname;
   spec.userdata = &spec_userdata_;
@@ -1256,7 +1257,7 @@ mjCBase* mjCBody::FindObject(mjtObj type, string _name, bool recursive) {
 
 
 template <class T>
-static mjElement* GetNext(std::vector<T*>& list, mjElement* child) {
+static mjsElement* GetNext(std::vector<T*>& list, mjsElement* child) {
   for (unsigned int i = 0; i < list.size()-1; i++) {
     if (list[i]->spec.element == child) {
       return list[i+1]->spec.element;
@@ -1268,7 +1269,7 @@ static mjElement* GetNext(std::vector<T*>& list, mjElement* child) {
 
 
 // get next child of given type
-mjElement* mjCBody::NextChild(mjElement* child, mjtObj type) {
+mjsElement* mjCBody::NextChild(mjsElement* child, mjtObj type) {
   if (type == mjOBJ_UNKNOWN) {
     if (!child) {
       throw mjCError(this, "child type must be specified if no child element is given");
@@ -1669,7 +1670,7 @@ void mjCFrame::SetParent(mjCBody* _body) {
 
 
 void mjCFrame::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.childclass = &classname;
   spec.info = &info;
@@ -1765,7 +1766,7 @@ bool mjCJoint::is_actfrclimited() const { return islimited(actfrclimited, actfrc
 
 
 void mjCJoint::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.userdata = &spec_userdata_;
@@ -1965,7 +1966,7 @@ mjCGeom& mjCGeom::operator=(const mjCGeom& other) {
 
 // to be called after any default copy constructor
 void mjCGeom::PointToLocal(void) {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.info = &info;
   spec.classname = &classname;
@@ -2598,7 +2599,7 @@ mjCSite& mjCSite::operator=(const mjCSite& other) {
 
 
 void mjCSite::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.info = &info;
   spec.classname = &classname;
@@ -2750,7 +2751,7 @@ mjCCamera& mjCCamera::operator=(const mjCCamera& other) {
 
 
 void mjCCamera::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.userdata = &spec_userdata_;
@@ -2901,7 +2902,7 @@ mjCLight& mjCLight::operator=(const mjCLight& other) {
 
 
 void mjCLight::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.targetbody = &spec_targetbody_;
@@ -3001,7 +3002,7 @@ mjCHField& mjCHField::operator=(const mjCHField& other) {
 
 
 void mjCHField::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.file = &spec_file_;
   spec.content_type = &spec_content_type_;
@@ -3230,7 +3231,7 @@ mjCTexture& mjCTexture::operator=(const mjCTexture& other) {
 
 
 void mjCTexture::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.file = &spec_file_;
@@ -3941,7 +3942,7 @@ mjCMaterial& mjCMaterial::operator=(const mjCMaterial& other) {
 
 
 void mjCMaterial::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.texture = &spec_texture_;
@@ -4031,7 +4032,7 @@ mjCPair& mjCPair::operator=(const mjCPair& other) {
 
 
 void mjCPair::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.geomname1 = &spec_geomname1_;
@@ -4256,7 +4257,7 @@ mjCBodyPair& mjCBodyPair::operator=(const mjCBodyPair& other) {
 
 
 void mjCBodyPair::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.bodyname1 = &spec_bodyname1_;
   spec.bodyname2 = &spec_bodyname2_;
@@ -4390,7 +4391,7 @@ mjCEquality& mjCEquality::operator=(const mjCEquality& other) {
 
 
 void mjCEquality::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.name1 = &spec_name1_;
@@ -4559,7 +4560,7 @@ bool mjCTendon::is_limited() const { return islimited(limited, range); }
 
 
 void mjCTendon::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.material = &spec_material_;
@@ -4891,7 +4892,7 @@ mjCWrap& mjCWrap::operator=(const mjCWrap& other) {
 
 
 void mjCWrap::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.info = &info;
 }
 
@@ -5040,7 +5041,7 @@ bool mjCActuator::is_actlimited() const { return islimited(actlimited, actrange)
 
 
 void mjCActuator::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.userdata = &spec_userdata_;
@@ -5363,7 +5364,7 @@ mjCSensor& mjCSensor::operator=(const mjCSensor& other) {
 
 
 void mjCSensor::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.classname = &classname;
   spec.userdata = &spec_userdata_;
@@ -5866,7 +5867,7 @@ mjCNumeric& mjCNumeric::operator=(const mjCNumeric& other) {
 
 
 void mjCNumeric::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.data = &spec_data_;
   spec.info = &info;
@@ -5955,7 +5956,7 @@ mjCText& mjCText::operator=(const mjCText& other) {
 
 
 void mjCText::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.data = &spec_data_;
   spec.info = &info;
@@ -6035,7 +6036,7 @@ mjCTuple& mjCTuple::operator=(const mjCTuple& other) {
 
 
 void mjCTuple::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.objtype = (mjIntVec*)&spec_objtype_;
   spec.objname = &spec_objname_;
@@ -6170,7 +6171,7 @@ mjCKey& mjCKey::operator=(const mjCKey& other) {
 
 
 void mjCKey::PointToLocal() {
-  spec.element = static_cast<mjElement*>(this);
+  spec.element = static_cast<mjsElement*>(this);
   spec.name = &name;
   spec.qpos = &spec_qpos_;
   spec.qvel = &spec_qvel_;

src/user/user_objects.h

@@ -26,7 +26,7 @@
 #include <mujoco/mjtnum.h>
 #include <mujoco/mjmodel.h>
 #include <mujoco/mjplugin.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_cache.h"
 #include "user/user_util.h"
 
@@ -168,7 +168,7 @@ class mjCBoundingVolumeHierarchy : public mjCBoundingVolumeHierarchy_ {
 //------------------------- class mjCBase ----------------------------------------------------------
 // Generic functionality for all derived classes
 
-class mjCBase_ : public mjElement {
+class mjCBase_ : public mjsElement {
  public:
   int id;                 // object id
   std::string name;       // object name
@@ -309,7 +309,7 @@ class mjCBody : public mjCBody_, private mjsBody {
   const std::vector<double>& get_userdata() { return userdata_; }
 
   // get next child of given type
-  mjElement* NextChild(mjElement* child, mjtObj type = mjOBJ_UNKNOWN);
+  mjsElement* NextChild(mjsElement* child, mjtObj type = mjOBJ_UNKNOWN);
 
  private:
   mjCBody(const mjCBody& other, mjCModel* _model);  // copy constructor
@@ -1624,7 +1624,7 @@ class mjCKey : public mjCKey_, private mjsKey {
 //------------------------- class mjCDef -----------------------------------------------------------
 // Describes one set of defaults
 
-class mjCDef : public mjElement {
+class mjCDef : public mjsElement {
   friend class mjXWriter;
 
  public:

src/xml/xml.cc

@@ -35,7 +35,7 @@
 #include "cc/array_safety.h"
 #include "engine/engine_crossplatform.h"
 #include "engine/engine_resource.h"
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_util.h"
 #include "user/user_vfs.h"
 #include "xml/xml_native_reader.h"
@@ -345,7 +345,7 @@ mjSpec* mjParseXML(const char* filename, const mjVFS* vfs,
   }
 
   // create model, set filedir
-  spec = mjs_createSpec();
+  spec = mj_makeSpec();
   const char* dir;
   int ndir = 0;
   mju_getResourceDir(resource, &dir, &ndir);
@@ -394,7 +394,7 @@ mjSpec* mjParseXML(const char* filename, const mjVFS* vfs,
   // catch known errors
   catch (mjXError err) {
     mjCopyError(error, err.message, error_sz);
-    mjs_deleteSpec(spec);
+    mj_deleteSpec(spec);
     return nullptr;
   }
 

src/xml/xml.h

@@ -19,7 +19,7 @@
 
 #include <mujoco/mjexport.h>
 #include <mujoco/mjmodel.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 
 // Top level API
 

src/xml/xml_api.cc

@@ -28,7 +28,7 @@
 #include <mujoco/mjmodel.h>
 #include "engine/engine_io.h"
 #include "engine/engine_resource.h"
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_vfs.h"
 #include "xml/xml.h"
 #include "xml/xml_native_reader.h"
@@ -59,7 +59,7 @@ std::optional<std::string> GlobalModel::ToXML(const mjModel* m, char* error,
     mjCopyError(error, "No XML model loaded", error_sz);
     return std::nullopt;
   }
-  mjs_copyBack(spec_, m);
+  mj_copyBack(spec_, m);
   std::string result = mjWriteXML(spec_, error, error_sz);
   if (result.empty()) {
     return std::nullopt;
@@ -70,7 +70,7 @@ std::optional<std::string> GlobalModel::ToXML(const mjModel* m, char* error,
 void GlobalModel::Set(mjSpec* spec) {
   std::lock_guard<std::mutex> lock(*mutex_);
   if (spec_ != nullptr) {
-    mjs_deleteSpec(spec_);
+    mj_deleteSpec(spec_);
   }
   spec_ = spec;
 }
@@ -96,13 +96,13 @@ mjModel* mj_loadXML(const char* filename, const mjVFS* vfs,
   // parse new model
   std::unique_ptr<mjSpec, std::function<void(mjSpec*)>> spec(
       mjParseXML(filename, vfs, error, error_sz),
-      [](mjSpec* s) { mjs_deleteSpec(s); });
+      [](mjSpec* s) { mj_deleteSpec(s); });
   if (!spec) {
     return nullptr;
   }
 
   // compile new model
-  mjModel* m = mjs_compile(spec.get(), vfs);
+  mjModel* m = mj_compile(spec.get(), vfs);
   if (!m) {
     mjCopyError(error, mjs_getError(spec.get()), error_sz);
     return nullptr;
@@ -248,7 +248,7 @@ int mj_saveXMLString(const mjSpec* s, char* xml, int xml_sz, char* error, int er
     std::string error_msg = "Output string too short, should be at least " +
                             std::to_string(result.size()+1);
     mjCopyError(error, error_msg.c_str(), error_sz);
-    return 0;
+    return result.size();
   }
   if (result.empty()) {
     return 0;
@@ -256,6 +256,6 @@ int mj_saveXMLString(const mjSpec* s, char* xml, int xml_sz, char* error, int er
 
   result.copy(xml, xml_sz);
   xml[result.size()] = 0;
-  return 1;
+  return 0;
 }
 

src/xml/xml_api.h

@@ -17,7 +17,7 @@
 
 #include <mujoco/mjexport.h>
 #include <mujoco/mjmodel.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 
 #ifdef __cplusplus
 extern "C" {

src/xml/xml_base.cc

@@ -21,9 +21,7 @@
 #include <string>
 #include <vector>
 
-#include "user/user_api.h"
-#include "user/user_model.h"
-#include "user/user_objects.h"
+#include <mujoco/mjspec.h>
 #include "xml/xml_util.h"
 #include "tinyxml2.h"
 

src/xml/xml_base.h

@@ -19,7 +19,7 @@
 #include <string>
 
 #include "tinyxml2.h"
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "xml/xml_util.h"
 
 

src/xml/xml_native_reader.cc

@@ -36,7 +36,7 @@
 #include "engine/engine_plugin.h"
 #include "engine/engine_util_errmem.h"
 #include "engine/engine_util_misc.h"
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_composite.h"
 #include "user/user_flexcomp.h"
 #include "user/user_util.h"

src/xml/xml_native_reader.h

@@ -21,7 +21,7 @@
 #include "tinyxml2.h"
 
 #include <mujoco/mujoco.h>
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "xml/xml_base.h"
 #include "xml/xml_util.h"
 

src/xml/xml_native_writer.cc

@@ -22,11 +22,12 @@
 
 #include <mujoco/mjmodel.h>
 #include <mujoco/mjplugin.h>
+#include <mujoco/mjspec.h>
+#include <mujoco/mujoco.h>
 #include "engine/engine_io.h"
 #include "engine/engine_plugin.h"
 #include "engine/engine_util_errmem.h"
 #include "engine/engine_util_misc.h"
-#include "user/user_api.h"
 #include "user/user_model.h"
 #include "user/user_objects.h"
 #include "user/user_util.h"

src/xml/xml_native_writer.h

@@ -18,7 +18,7 @@
 #include <cstdlib>
 #include <string>
 
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "user/user_objects.h"
 #include "xml/xml_base.h"
 #include "tinyxml2.h"

src/xml/xml_urdf.cc

@@ -20,6 +20,7 @@
 #include <vector>
 
 #include <mujoco/mjmodel.h>
+#include <mujoco/mjspec.h>
 #include "user/user_api.h"
 #include "user/user_util.h"
 #include "xml/xml_native_reader.h"

src/xml/xml_urdf.h

@@ -19,7 +19,7 @@
 #include <unordered_set>
 #include <vector>
 
-#include "user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "xml/xml_base.h"
 #include "tinyxml2.h"
 

test/user/user_api_test.cc

@@ -24,7 +24,7 @@
 #include <gtest/gtest.h>
 #include <absl/strings/match.h>
 #include <mujoco/mujoco.h>
-#include "src/user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "src/xml/xml_api.h"
 #include "src/xml/xml_numeric_format.h"
 #include "test/fixture.h"
@@ -39,7 +39,7 @@ using ::testing::NotNull;
 // -------------------------- test model manipulation  -------------------------
 
 TEST_F(MujocoTest, GetSetData) {
-  mjSpec* spec = mjs_createSpec();
+  mjSpec* spec = mj_makeSpec();
   mjsBody* world = mjs_findBody(spec, "world");
   mjsBody* body = mjs_addBody(world, 0);
   mjsSite* site = mjs_addSite(body, 0);
@@ -60,11 +60,11 @@ TEST_F(MujocoTest, GetSetData) {
     EXPECT_EQ(vec[i], i);
   }
 
-  mjs_deleteSpec(spec);
+  mj_deleteSpec(spec);
 }
 
 TEST_F(MujocoTest, TreeTraversal) {
-  mjSpec* spec = mjs_createSpec();
+  mjSpec* spec = mj_makeSpec();
   mjsBody* world = mjs_findBody(spec, "world");
   mjsBody* body = mjs_addBody(world, 0);
 
@@ -75,15 +75,15 @@ TEST_F(MujocoTest, TreeTraversal) {
   mjsSite* site3 = mjs_addSite(body, 0);
   mjsGeom* geom3 = mjs_addGeom(body, 0);
 
-  mjElement* t_el1 = mjs_firstChild(body, mjOBJ_TENDON);
-  mjElement* s_el1 = mjs_firstChild(body, mjOBJ_SITE);
-  mjElement* s_el2 = mjs_nextChild(body, s_el1);
-  mjElement* s_el3 = mjs_nextChild(body, s_el2);
-  mjElement* s_el4 = mjs_nextChild(body, s_el3);
-  mjElement* g_el1 = mjs_firstChild(body, mjOBJ_GEOM);
-  mjElement* g_el2 = mjs_nextChild(body, g_el1);
-  mjElement* g_el3 = mjs_nextChild(body, g_el2);
-  mjElement* g_el4 = mjs_nextChild(body, g_el3);
+  mjsElement* t_el1 = mjs_firstChild(body, mjOBJ_TENDON);
+  mjsElement* s_el1 = mjs_firstChild(body, mjOBJ_SITE);
+  mjsElement* s_el2 = mjs_nextChild(body, s_el1);
+  mjsElement* s_el3 = mjs_nextChild(body, s_el2);
+  mjsElement* s_el4 = mjs_nextChild(body, s_el3);
+  mjsElement* g_el1 = mjs_firstChild(body, mjOBJ_GEOM);
+  mjsElement* g_el2 = mjs_nextChild(body, g_el1);
+  mjsElement* g_el3 = mjs_nextChild(body, g_el2);
+  mjsElement* g_el4 = mjs_nextChild(body, g_el3);
 
   EXPECT_EQ(t_el1, nullptr);
   EXPECT_EQ(s_el1, site1->element);
@@ -95,7 +95,7 @@ TEST_F(MujocoTest, TreeTraversal) {
   EXPECT_EQ(g_el4, nullptr);
   EXPECT_EQ(s_el4, nullptr);
 
-  mjs_deleteSpec(spec);
+  mj_deleteSpec(spec);
 }
 
 // ------------------- test recompilation multiple files -----------------------
@@ -131,16 +131,16 @@ TEST_F(PluginTest, RecompileCompare) {
             << "Failed to load " << xml << ": " << err.data();
 
         // copy spec
-        mjSpec* s_copy = mjs_copySpec(s);
+        mjSpec* s_copy = mj_copySpec(s);
 
         // compile twice and compare
-        mjModel* m_old = mjs_compile(s, nullptr);
+        mjModel* m_old = mj_compile(s, nullptr);
 
         ASSERT_THAT(m_old, NotNull())
             << "Failed to compile " << xml << ": " << mjs_getError(s);
 
-        mjModel* m_new = mjs_compile(s, nullptr);
-        mjModel* m_copy = mjs_compile(s_copy, nullptr);
+        mjModel* m_new = mj_compile(s, nullptr);
+        mjModel* m_copy = mj_compile(s_copy, nullptr);
 
         ASSERT_THAT(m_new, NotNull())
             << "Failed to recompile " << xml << ": " << mjs_getError(s);
@@ -158,8 +158,8 @@ TEST_F(PluginTest, RecompileCompare) {
             << "Different field: " << field << '\n';
 
         // copy to a new spec, compile and compare
-        mjSpec* s_copy2 = mjs_copySpec(s);
-        mjModel* m_copy2 = mjs_compile(s_copy2, nullptr);
+        mjSpec* s_copy2 = mj_copySpec(s);
+        mjModel* m_copy2 = mj_compile(s_copy2, nullptr);
 
         ASSERT_THAT(m_copy2, NotNull())
             << "Failed to compile " << xml << ": " << mjs_getError(s_copy2);
@@ -170,9 +170,9 @@ TEST_F(PluginTest, RecompileCompare) {
             << "Different field: " << field << '\n';
 
         // delete models
-        mjs_deleteSpec(s);
-        mjs_deleteSpec(s_copy);
-        mjs_deleteSpec(s_copy2);
+        mj_deleteSpec(s);
+        mj_deleteSpec(s_copy);
+        mj_deleteSpec(s_copy2);
         mj_deleteModel(m_old);
         mj_deleteModel(m_new);
         mj_deleteModel(m_copy);
@@ -433,7 +433,7 @@ TEST_F(MujocoTest, AttachSame) {
       mjs_attachBody(frame, body, /*prefix=*/"attached-", /*suffix=*/"-1"), 0);
 
   // compile new model
-  mjModel* m_attached = mjs_compile(parent, 0);
+  mjModel* m_attached = mj_compile(parent, 0);
   EXPECT_THAT(m_attached, NotNull());
 
   // check full name stored in mjModel
@@ -450,7 +450,7 @@ TEST_F(MujocoTest, AttachSame) {
             << "Different field: " << field << '\n';;
 
   // destroy everything
-  mjs_deleteSpec(parent);
+  mj_deleteSpec(parent);
   mj_deleteModel(m_attached);
   mj_deleteModel(m_expected);
 }
@@ -550,7 +550,7 @@ TEST_F(MujocoTest, AttachDifferent) {
       mjs_attachBody(frame, body, /*prefix=*/"attached-", /*suffix=*/"-1"), 0);
 
   // compile new model
-  mjModel* m_attached = mjs_compile(parent, 0);
+  mjModel* m_attached = mj_compile(parent, 0);
   EXPECT_THAT(m_attached, NotNull());
 
   // check full name stored in mjModel
@@ -567,8 +567,8 @@ TEST_F(MujocoTest, AttachDifferent) {
             << "Different field: " << field << '\n';;
 
   // destroy everything
-  mjs_deleteSpec(parent);
-  mjs_deleteSpec(child);
+  mj_deleteSpec(parent);
+  mj_deleteSpec(child);
   mj_deleteModel(m_attached);
   mj_deleteModel(m_expected);
 }
@@ -662,7 +662,7 @@ TEST_F(MujocoTest, AttachFrame) {
       mjs_attachFrame(body, frame, /*prefix=*/"attached-", /*suffix=*/"-1"), 0);
 
   // compile new model
-  mjModel* m_attached = mjs_compile(parent, 0);
+  mjModel* m_attached = mj_compile(parent, 0);
   EXPECT_THAT(m_attached, NotNull());
 
   // check full name stored in mjModel
@@ -679,8 +679,8 @@ TEST_F(MujocoTest, AttachFrame) {
             << "Different field: " << field << '\n';;
 
   // destroy everything
-  mjs_deleteSpec(parent);
-  mjs_deleteSpec(child);
+  mj_deleteSpec(parent);
+  mj_deleteSpec(child);
   mj_deleteModel(m_attached);
   mj_deleteModel(m_expected);
 }
@@ -715,7 +715,7 @@ void TestDetachBody(bool compile) {
   EXPECT_THAT(child, NotNull()) << er.data();
 
   // compile model (for testing double compilation)
-  mjModel* m_child = compile ? mjs_compile(child, 0) : nullptr;
+  mjModel* m_child = compile ? mj_compile(child, 0) : nullptr;
 
   // get subtree
   mjsBody* body = mjs_findBody(child, "body");
@@ -725,7 +725,7 @@ void TestDetachBody(bool compile) {
   EXPECT_THAT(mjs_detachBody(child, body), 0);
 
   // compile new model
-  mjModel* m_detached = mjs_compile(child, 0);
+  mjModel* m_detached = mj_compile(child, 0);
   EXPECT_THAT(m_detached, NotNull());
 
   // compare with expected XML
@@ -736,7 +736,7 @@ void TestDetachBody(bool compile) {
             << "Different field: " << field << '\n';
 
   // destroy everything
-  mjs_deleteSpec(child);
+  mj_deleteSpec(child);
   mj_deleteModel(m_detached);
   mj_deleteModel(m_expected);
   if (m_child) mj_deleteModel(m_child);
@@ -791,7 +791,7 @@ TEST_F(MujocoTest, PreserveState) {
   EXPECT_THAT(spec, NotNull()) << er.data();
 
   // compile models
-  mjModel* model = mjs_compile(spec, 0);
+  mjModel* model = mj_compile(spec, 0);
   EXPECT_THAT(model, NotNull());
   mjModel* m_expected = LoadModelFromString(xml_expected, er.data(), er.size());
   EXPECT_THAT(m_expected, NotNull());
@@ -834,7 +834,7 @@ TEST_F(MujocoTest, PreserveState) {
   joint->ref = d_expected->qpos[m_expected->nq-1];
 
   // compile new model
-  mjs_recompile(spec, 0, model, data);
+  mj_recompile(spec, 0, model, data);
   EXPECT_THAT(model, NotNull());
 
   // compare qpos
@@ -861,7 +861,7 @@ TEST_F(MujocoTest, PreserveState) {
   // destroy everything
   mj_deleteData(data);
   mj_deleteData(d_expected);
-  mjs_deleteSpec(spec);
+  mj_deleteSpec(spec);
   mj_deleteModel(model);
   mj_deleteModel(m_expected);
 }

test/xml/xml_api_test.cc

@@ -24,7 +24,7 @@
 #include <mujoco/mjdata.h>
 #include <mujoco/mjmodel.h>
 #include <mujoco/mujoco.h>
-#include "src/user/user_api.h"
+#include <mujoco/mjspec.h>
 #include "src/xml/xml_api.h"
 #include "test/fixture.h"
 
@@ -119,15 +119,15 @@ TEST_F(MujocoTest, SaveXmlShortString) {
 
   mjSpec* spec = mj_parseXMLString(xml, 0, error.data(), error.size());
   EXPECT_THAT(spec, NotNull()) << "Failed to parse spec: " << error.data();
-  mjModel* model = mjs_compile(spec, 0);
+  mjModel* model = mj_compile(spec, 0);
   EXPECT_THAT(model, NotNull()) << "Failed to compile model: " << error.data();
 
   std::array<char, 10> out;
   EXPECT_THAT(mj_saveXMLString(spec, out.data(), out.size(),
-                               error.data(), error.size()), 0);
+                               error.data(), error.size()), 272);
   EXPECT_STREQ(error.data(), "Output string too short, should be at least 273");
 
-  mjs_deleteSpec(spec);
+  mj_deleteSpec(spec);
   mj_deleteModel(model);
 }
 
@@ -136,16 +136,16 @@ TEST_F(MujocoTest, SaveXml) {
 
   mjSpec* spec = mj_parseXMLString(xml, 0, error.data(), error.size());
   EXPECT_THAT(spec, NotNull()) << "Failed to parse spec: " << error.data();
-  mjModel* model = mjs_compile(spec, 0);
+  mjModel* model = mj_compile(spec, 0);
   EXPECT_THAT(model, NotNull()) << "Failed to compile model: " << error.data();
 
   std::array<char, 273> out;
   EXPECT_THAT(mj_saveXMLString(spec, out.data(), out.size(), error.data(),
-                               error.size()), 1) << error.data();
+                               error.size()), 0) << error.data();
 
   mjSpec* saved_spec = mj_parseXMLString(xml, 0, error.data(), error.size());
   EXPECT_THAT(saved_spec, NotNull()) << "Invalid saved spec: " << error.data();
-  mjModel* saved_model = mjs_compile(saved_spec, 0);
+  mjModel* saved_model = mj_compile(saved_spec, 0);
   EXPECT_THAT(saved_model, NotNull()) << "Invalid model: " << error.data();
 
   mjtNum tol = 0;
@@ -154,8 +154,8 @@ TEST_F(MujocoTest, SaveXml) {
             << "Expected and attached models are different!\n"
             << "Different field: " << field << '\n';
 
-  mjs_deleteSpec(spec);
-  mjs_deleteSpec(saved_spec);
+  mj_deleteSpec(spec);
+  mj_deleteSpec(saved_spec);
   mj_deleteModel(model);
   mj_deleteModel(saved_model);
 }

test/xml/xml_native_reader_test.cc

@@ -24,10 +24,10 @@
 #include <gmock/gmock.h>
 #include <gtest/gtest.h>
 #include <mujoco/mjmodel.h>
+#include <mujoco/mjspec.h>
 #include <mujoco/mujoco.h>
 #include "src/cc/array_safety.h"
 #include "src/engine/engine_util_errmem.h"
-#include "src/user/user_api.h"
 #include "src/xml/xml_api.h"
 #include "test/fixture.h"
 
@@ -1101,7 +1101,7 @@ TEST_F(XMLReaderTest, ParseReplicateDefaultPropagate) {
   EXPECT_THAT(def, NotNull());
   EXPECT_THAT(def->geom->type, mjGEOM_CAPSULE);
 
-  mjs_deleteSpec(spec);
+  mj_deleteSpec(spec);
 }
 
 // ----------------------- test camera parsing ---------------------------------

unity/Runtime/Bindings/MjBindings.cs

@@ -57,6 +57,7 @@ public const bool mjEXTERNC = true;
 public const bool THIRD_PARTY_MUJOCO_MJRENDER_H_ = true;
 public const int mjNAUX = 10;
 public const int mjMAXTEXTURE = 1000;
+public const bool THIRD_PARTY_MUJOCO_INCLUDE_MJSPEC_H_ = true;
 public const bool THIRD_PARTY_MUJOCO_INCLUDE_MJTHREAD_H_ = true;
 public const int mjMAXTHREAD = 128;
 public const bool THIRD_PARTY_MUJOCO_INCLUDE_MJTNUM_H_ = true;
@@ -427,6 +428,39 @@ public enum mjtFont : int{
   mjFONT_SHADOW = 1,
   mjFONT_BIG = 2,
 }
+public enum mjtGeomInertia : int{
+  mjINERTIA_VOLUME = 1,
+  mjINERTIA_SHELL = 2,
+}
+public enum mjtBuiltin : int{
+  mjBUILTIN_NONE = 0,
+  mjBUILTIN_GRADIENT = 1,
+  mjBUILTIN_CHECKER = 2,
+  mjBUILTIN_FLAT = 3,
+}
+public enum mjtMark : int{
+  mjMARK_NONE = 0,
+  mjMARK_EDGE = 1,
+  mjMARK_CROSS = 2,
+  mjMARK_RANDOM = 3,
+}
+public enum mjtLimited : int{
+  mjLIMITED_FALSE = 0,
+  mjLIMITED_TRUE = 1,
+  mjLIMITED_AUTO = 2,
+}
+public enum mjtInertiaFromGeom : int{
+  mjINERTIAFROMGEOM_FALSE = 0,
+  mjINERTIAFROMGEOM_TRUE = 1,
+  mjINERTIAFROMGEOM_AUTO = 2,
+}
+public enum mjtOrientation : int{
+  mjORIENTATION_QUAT = 0,
+  mjORIENTATION_AXISANGLE = 1,
+  mjORIENTATION_XYAXES = 2,
+  mjORIENTATION_ZAXIS = 3,
+  mjORIENTATION_EULER = 4,
+}
 public enum mjtTaskStatus : int{
   mjTASK_NEW = 0,
   mjTASK_QUEUED = 1,
@@ -6358,9 +6392,6 @@ public static unsafe extern int mj_saveLastXML([MarshalAs(UnmanagedType.LPStr)]s
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
 public static unsafe extern void mj_freeLastXML();
 
-[DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
-public static unsafe extern int mj_printSchema([MarshalAs(UnmanagedType.LPStr)]string filename, StringBuilder buffer, int buffer_sz, int flg_html, int flg_pad);
-
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
 public static unsafe extern void mj_step(mjModel_* m, mjData_* d);
 
@@ -6469,6 +6500,9 @@ public static unsafe extern void mju_printMat(double* mat, int nr, int nc);
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
 public static unsafe extern void mju_printMatSparse(double* mat, int nr, int* rownnz, int* rowadr, int* colind);
 
+[DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
+public static unsafe extern int mj_printSchema([MarshalAs(UnmanagedType.LPStr)]string filename, StringBuilder buffer, int buffer_sz, int flg_html, int flg_pad);
+
 [DllImport("mujoco", CallingConvention = CallingConvention.Cdecl)]
 public static unsafe extern void mj_fwdPosition(mjModel_* m, mjData_* d);