Introduce archive resource providers.

This change introduces a new registration function
mjp_registerArchiveResourceProvider for mjpResourceProvider plugins.
These special resource providers are meant to address asset fetching
from within an "archive" such as an mjz, but it's easy to imagine other
extensions such as reference buffers within a binary format, or a tar
file.

Assets can be addressed via regular path syntax anywhere filepaths are
used in MuJoCo:

```
<mesh name="chair_leg" file="a/b/c.mjz/meshes/chair.obj"/>
```

By consequence, this allows us to remove the shared VFS requirement
between model parsing and compilation for MJZ.

```
# BEFORE
with mujoco.MjVfs() as vfs:
  spec = mujoco.MjSpec.from_file("some_asset.mjz", vfs=vfs)
  model = spec.compile(vfs=vfs)

# AFTER
spec = mujoco.MjSpec.from_file("some_asset.mjz")
model = spec.compile()
```

A VFS can still be used if you need tight control over rsource
management in tight loops compiling a lot of models, but we hope to
address that specific usecase in a follow up soon.

PiperOrigin-RevId: 983512715
Change-Id: I639bd80ca7edbec379ccf7aba667f742ea311323

Author: havess

doc/APIreference/functions.rst

@@ -4108,6 +4108,36 @@ Return the encoder that matches against the content type or filename extension.
 
 If no match, return NULL.
 
+.. _mjp_registerArchiveResourceProvider:
+
+`mjp_registerArchiveResourceProvider <#mjp_registerArchiveResourceProvider>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_registerArchiveResourceProvider
+
+Globally register an archive resource provider. This function is thread-safe.
+provider->prefix specifies the filename extension(s) (e.g. .mjz|.zip).
+
+.. _mjp_findArchiveResourceProvider:
+
+`mjp_findArchiveResourceProvider <#mjp_findArchiveResourceProvider>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_findArchiveResourceProvider
+
+Return the archive resource provider that matches against the resource name.
+
+If no match, return NULL.
+
+.. _mjp_archiveResourceProviderCount:
+
+`mjp_archiveResourceProviderCount <#mjp_archiveResourceProviderCount>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_archiveResourceProviderCount
+
+Return the number of globally registered archive resource providers.
+
 .. _Thread:
 
 Threads

doc/changelog.rst

@@ -16,6 +16,12 @@ General
    while ``elastic2d`` elasticity is integrated implicitly through the effective metric. The contacts the mode resolves
    are frictionless. The mode keeps contact multipliers across steps that no state specification covers, so
    ``mj_getState``/``mj_setState`` do not capture its full state and exact replay is not supported.
+- Introduced :ref:`archive resource providers<mjp_registerArchiveResourceProvider>`
+  (``mjp_registerArchiveResourceProvider``). Archive providers use the
+  :ref:`mjpResourceProvider` interface to mount and read archive containers (such as
+  ``.mjz``/``.zip``), decoupling container handling from format decoders and enabling
+  on-demand asset extraction without requiring a pre-allocated :ref:`VFS<Virtualfilesystem>`.
+
 
 Engine
 ^^^^^^

doc/includes/references.h

@@ -4122,6 +4122,9 @@ const mjpDecoder* mjp_findDecoder(const mjResource* resource, const char* conten
 void mjp_registerEncoder(const mjpEncoder* encoder);
 void mjp_defaultEncoder(mjpEncoder* encoder);
 const mjpEncoder* mjp_findEncoder(const char* filename, const char* content_type);
+void mjp_registerArchiveResourceProvider(const mjpResourceProvider* provider);
+const mjpResourceProvider* mjp_findArchiveResourceProvider(const char* resource_name);
+int mjp_archiveResourceProviderCount(void);
 mjResource* mju_openResource(const char* dir, const char* name,
                              const mjVFS* vfs, char* error, size_t nerror);
 void mju_closeResource(mjResource* resource);

doc/programming/modeledit.rst

@@ -122,12 +122,6 @@ When decoding an ``.mjz`` archive, MuJoCo searches for the root model XML file i
 Options 2-4 exist for backwards compatibility with legacy archives and common zip packaging layouts, but are
 susceptible to failure if the archive file is renamed.
 
-VFS Requirement
-^^^^^^^^^^^^^^^
-
-Parsing and compilation of an ``.mjz`` archive (and all of its contained asset files) require using the **exact same
-VFS instance**.
-
 .. _meCustomFormats:
 
 Custom formats

doc/python.rst

@@ -522,9 +522,7 @@ Assets
 ^^^^^^
 
 MuJoCo optionally uses a :ref:`Virtual File System <Virtualfilesystem>` (VFS) to load assets (like meshes and textures)
-from memory. Some :ref:`decoders<exDecoder>` may also choose to leverage the VFS as a way to load assets on
-demand, such as when addressing files in an archive format. This requires the same VFS to be used when parsing and
-compiling a spec (and all attached specs) into a model.
+from memory.
 
 The Python bindings provide the ``mujoco.MjVfs`` as a wrapper around the :ref:`mjVFS` C struct.
 

include/mujoco/mujoco.h

@@ -1590,6 +1590,16 @@ MJAPI void mjp_defaultEncoder(mjpEncoder* encoder);
 // If no match, return NULL.
 MJAPI const mjpEncoder* mjp_findEncoder(const char* filename, const char* content_type);
 
+// Globally register an archive resource provider. This function is thread-safe.
+// provider->prefix specifies the filename extension(s) (e.g. .mjz|.zip).
+MJAPI void mjp_registerArchiveResourceProvider(const mjpResourceProvider* provider);
+
+// Return the archive resource provider that matches against the resource name.
+// If no match, return NULL.
+MJAPI const mjpResourceProvider* mjp_findArchiveResourceProvider(const char* resource_name);
+
+// Return the number of globally registered archive resource providers.
+MJAPI int mjp_archiveResourceProviderCount(void);
 
 
 //---------------------------------- Resources -----------------------------------------------------

python/mujoco/introspect/functions.py

@@ -9975,6 +9975,43 @@
          ),
          doc='Return the encoder that matches against the content type or filename extension. If no match, return NULL.',  # pylint: disable=line-too-long
      )),
+    ('mjp_registerArchiveResourceProvider',
+     FunctionDecl(
+         name='mjp_registerArchiveResourceProvider',
+         return_type=ValueType(name='void'),
+         parameters=(
+             FunctionParameterDecl(
+                 name='provider',
+                 type=PointerType(
+                     inner_type=ValueType(name='mjpResourceProvider', is_const=True),  # pylint: disable=line-too-long
+                 ),
+             ),
+         ),
+         doc='Globally register an archive resource provider. This function is thread-safe. provider->prefix specifies the filename extension(s) (e.g. .mjz|.zip).',  # pylint: disable=line-too-long
+     )),
+    ('mjp_findArchiveResourceProvider',
+     FunctionDecl(
+         name='mjp_findArchiveResourceProvider',
+         return_type=PointerType(
+             inner_type=ValueType(name='mjpResourceProvider', is_const=True),
+         ),
+         parameters=(
+             FunctionParameterDecl(
+                 name='resource_name',
+                 type=PointerType(
+                     inner_type=ValueType(name='char', is_const=True),
+                 ),
+             ),
+         ),
+         doc='Return the archive resource provider that matches against the resource name. If no match, return NULL.',  # pylint: disable=line-too-long
+     )),
+    ('mjp_archiveResourceProviderCount',
+     FunctionDecl(
+         name='mjp_archiveResourceProviderCount',
+         return_type=ValueType(name='int'),
+         parameters=(),
+         doc='Return the number of globally registered archive resource providers.',  # pylint: disable=line-too-long
+     )),
     ('mju_openResource',
      FunctionDecl(
          name='mju_openResource',

src/engine/engine_plugin.cc

@@ -141,6 +141,8 @@ void ForEachPipeSeparated(std::string_view str, Fn&& fn) {
   }
 }
 
+struct ArchiveTag {};
+
 // resource provider helpers
 std::string_view ResourceProviderKey(const mjpResourceProvider& provider) {
   return std::string_view(provider.prefix, strklen(provider.prefix));
@@ -151,6 +153,8 @@ bool ResourceProviderEqual(const mjpResourceProvider& p1, const mjpResourceProvi
           p1.open == p2.open &&
           p1.read == p2.read &&
           p1.close == p2.close &&
+          p1.mount == p2.mount &&
+          p1.unmount == p2.unmount &&
           p1.modified == p2.modified &&
           p1.write == p2.write &&
           p1.data == p2.data);
@@ -283,6 +287,9 @@ bool GlobalTable<mjpPlugin>::CopyObject(mjpPlugin& dst, const mjpPlugin& src, Er
   return true;
 }
 
+
+
+// Standard URI resource provider table specialization
 template <>
 const char* GlobalTable<mjpResourceProvider>::HumanReadableTypeName() {
   return "resource provider";
@@ -304,6 +311,27 @@ bool GlobalTable<mjpResourceProvider>::CopyObject(mjpResourceProvider& dst, cons
   return ResourceProviderCopy(dst, src, err);
 }
 
+// Archive resource provider table specialization
+template <>
+const char* GlobalTable<mjpResourceProvider, ArchiveTag>::HumanReadableTypeName() {
+  return "archive resource provider";
+}
+
+template <>
+std::string_view GlobalTable<mjpResourceProvider, ArchiveTag>::ObjectKey(const mjpResourceProvider& plugin) {
+  return ResourceProviderKey(plugin);
+}
+
+template <>
+bool GlobalTable<mjpResourceProvider, ArchiveTag>::ObjectEqual(const mjpResourceProvider& p1, const mjpResourceProvider& p2) {
+  return ResourceProviderEqual(p1, p2);
+}
+
+template <>
+bool GlobalTable<mjpResourceProvider, ArchiveTag>::CopyObject(mjpResourceProvider& dst, const mjpResourceProvider& src, ErrorMessage& err) {
+  return ResourceProviderCopy(dst, src, err);
+}
+
 template <>
 const char* GlobalTable<mjpDecoder>::HumanReadableTypeName() {
   return "resource decoder";
@@ -465,6 +493,8 @@ bool GlobalTable<mjpEncoder>::CopyObject(mjpEncoder& dst, const mjpEncoder& src,
   return true;
 }
 
+
+
 // globally register a plugin (thread-safe), return new slot id
 int mjp_registerPlugin(const mjpPlugin* plugin) {
   if (!plugin->name) {
@@ -706,6 +736,47 @@ const mjpEncoder* mjp_findEncoder(const char* filename,
   return nullptr;
 }
 
+// registers an archive resource provider
+void mjp_registerArchiveResourceProvider(const mjpResourceProvider* provider) {
+  if (!provider || !provider->open || !provider->read || !provider->close) {
+    mju_error("archive provider must provide open, read, and close callbacks.");
+    return;
+  }
+
+  if (!provider->prefix) {
+    mju_error("archive provider must provide prefix (file extensions).");
+    return;
+  }
+
+  char ext_buf[kMaxNameLength + 1];
+  ForEachPipeSeparated(provider->prefix, [&](std::string_view ext) {
+    if (ext.size() <= kMaxNameLength) {
+      std::memcpy(ext_buf, ext.data(), ext.size());
+      ext_buf[ext.size()] = '\0';
+      mjpResourceProvider provider_copy = *provider;
+      provider_copy.prefix = ext_buf;
+      GlobalTable<mjpResourceProvider, ArchiveTag>::GetSingleton().AppendIfUnique(provider_copy);
+    }
+  });
+}
+
+// find an archive resource provider that matches a given resource or content type
+const mjpResourceProvider* mjp_findArchiveResourceProvider(const char* resource_name) {
+  std::string extension = resource_name ? getext(resource_name) : "";
+  if (extension.empty()) {
+    return nullptr;
+  }
+
+  return GlobalTable<mjpResourceProvider, ArchiveTag>::GetSingleton().GetByKey(
+      extension.c_str(), nullptr);
+}
+
+// return the number of globally registered archive resource providers
+int mjp_archiveResourceProviderCount() {
+  return GlobalTable<mjpResourceProvider, ArchiveTag>::GetSingleton().count();
+}
+
+
 // load plugins from a dynamic library
 void mj_loadPluginLibrary(const char* path) {
 #if defined(_WIN32) || defined(__CYGWIN__)

src/engine/engine_plugin.h

@@ -80,6 +80,16 @@ MJAPI void mjp_defaultEncoder(mjpEncoder* encoder);
 // find an encoder that can write a given format
 MJAPI const mjpEncoder* mjp_findEncoder(const char* filename, const char* content_type);
 
+// registers an archive resource provider
+MJAPI void mjp_registerArchiveResourceProvider(const mjpResourceProvider* provider);
+
+// find an archive resource provider that matches a given name
+MJAPI const mjpResourceProvider* mjp_findArchiveResourceProvider(const char* resource_name);
+
+// return the number of globally registered archive resource providers
+MJAPI int mjp_archiveResourceProviderCount(void);
+
+
 // =================================================================================================
 // MuJoCo-internal functions beyond this point.
 // "Unsafe" suffix indicates that improper use of these functions may result in data races.