From cfc7dc984897e7e9efe912720672ae0f67f94dcf Mon Sep 17 00:00:00 2001
From: Alessio Quaglino <quaglino@google.com>
Date: Fri, 16 Aug 2024 04:21:18 -0700
Subject: [PATCH] Clarify that keyframes are not replicated in nested
 attachments.

PiperOrigin-RevId: 663683684
Change-Id: Id180b3a6afad6809d8189a7a525c474bd3a91fc1
---
 doc/APIreference/APItypes.rst | 4 ++++
 doc/XMLreference.rst          | 7 +++++++
 doc/changelog.rst             | 5 +++++
 3 files changed, 16 insertions(+)

diff --git a/doc/APIreference/APItypes.rst b/doc/APIreference/APItypes.rst
index 61d2d7fa..9be6d9e4 100644
--- a/doc/APIreference/APItypes.rst
+++ b/doc/APIreference/APItypes.rst
@@ -1393,6 +1393,8 @@ Alternative orientation specifiers.
 
 .. _ArrayHandles:
 
+.. _mjBuffer:
+
 .. _mjString:
 
 .. _mjStringVec:
@@ -1417,6 +1419,7 @@ C handles for C++ strings and vector types. When using from C, use the provided
 
    #ifdef __cplusplus
      // C++: defined to be compatible with corresponding std types
+     using mjBuffer      = std::vector<std::byte>;
      using mjString      = std::string;
      using mjStringVec   = std::vector<std::string>;
      using mjIntVec      = std::vector<int>;
@@ -1426,6 +1429,7 @@ C handles for C++ strings and vector types. When using from C, use the provided
      using mjDoubleVec   = std::vector<double>;
    #else
      // C: opaque types
+     typedef void mjBuffer;
      typedef void mjString;
      typedef void mjStringVec;
      typedef void mjIntVec;
diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst
index 645ea9e2..e9c3f0fb 100644
--- a/doc/XMLreference.rst
+++ b/doc/XMLreference.rst
@@ -175,6 +175,12 @@ replicating 200 times, suffixes will be ``000, 001, ...`` etc). All referencing
 and namespaced appropriately. Detailed examples of models using replicate can be found in the
 `model/replicate/ <https://github.com/google-deepmind/mujoco/tree/main/model/replicate>`__ directory.
 
+There is a caveat concerning :ref:`keyframes<keyframe>` when using replicate. Since :ref:`mjs_attachFrame` is used to
+self-attach multiple times the enclosed kinematic tree, if this tree contains further :ref:`attach<body-attach>`
+elements, keyframes will not be replicated nor namespaced by :ref:`replicate<replicate>`, but they will be attached and
+namespaced once by the innermost call of :ref:`mjs_attachFrame` or :ref:`mjs_attachBody`. See the limitations discussed
+in :ref:`attach<body-attach>`.
+
 .. _replicate-count:
 
 :at:`count`: :at-val:`int, required`
@@ -3808,6 +3814,7 @@ all attachments will appear in the saved XML file.
    - An entire model cannot be attached (i.e. including all elements, referenced or not).
    - All assets from the child model will be copied in, whether they are referenced or not.
    - Self-attach or circular references are not checked for and will lead to infinite loops.
+   - :ref:`Keyframes<keyframe>` are attached once, so they are not replicated in nested attachments.
 
 .. _body-attach-model:
 
diff --git a/doc/changelog.rst b/doc/changelog.rst
index ea4a2edb..40713d29 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -24,6 +24,11 @@ Bug fixes
 7. Fixed a bug wherein, for models that have both muscles and stateless actuators and used one of the implicit
    integrators, wrong derivatives would be computed.
 
+Python bindings
+^^^^^^^^^^^^^^^
+8. Added support for engine plugins in :ref:`mjSpec` (:github:issue:`1903`).
+
+
 Version 3.2.2 (Aug 8, 2024)
 ---------------------------