Custom World ZIP Uploads
========================

Cloud Sim custom-world ZIP uploads use a Fuel-style layout for the world and
any models it references. Put one unambiguous ``.sdf`` or ``.world`` file in the
archive and keep each bundled model in its own directory with the required
Fuel metadata and model SDF. ZIP uploads can be up to 1 GB; standalone SDF and
world files remain limited to 20 MB.

ZIP layout requirements
-----------------------

The recommended layout is:

.. code-block:: text

   my-world/
   ├── world.sdf
   └── models/
       ├── chair/
       │   ├── model.config
       │   ├── model.sdf
       │   ├── meshes/
       │   │   └── chair.dae
       │   └── materials/
       │       └── textures/
       │           └── chair.png
       └── table/
           ├── model.config
           ├── model.sdf
           └── meshes/
               └── table.obj

``world.sdf`` may be at the ZIP root or inside one enclosing directory, but the
archive must contain exactly one unambiguous world file outside model, mesh,
material, and thumbnail directories. Each bundled model needs both
``model.config`` and ``model.sdf`` in its model directory. Keep meshes, textures,
materials, and other model resources beneath that model directory.

Adding a thumbnail
------------------

ZIP packages may include preview images for the world. Use ``.png``, ``.jpg``,
``.jpeg``, or ``.webp`` files no larger than 5 MB. For the best results, place
them in a ``thumbnail`` or ``thumbnails`` directory, or include a name such as
``thumbnail``, ``preview``, ``screenshot``, or ``cover`` in the filename. Up to 20
matching images can be included.

For example:

.. code-block:: text

   my-world/
   ├── world.sdf
   └── thumbnails/
       ├── overview.png
       └── cover.webp

When you review the uploaded package, the app shows any matching images so you
can choose one as the world's thumbnail. You can also upload a new image
during review, or save the world without a thumbnail.

Model references
----------------

Reference bundled models with ``model://`` URIs and keep model resources
relocatable:

.. code-block:: xml

   <include>
     <uri>model://chair</uri>
   </include>

The upload processor also understands Fuel model URLs such as
``https://fuel.gazebosim.org/1.0/OpenRobotics/models/Box`` and downloads those
models into the uploaded simulation package. Local relative paths and
absolute filesystem paths are not interchangeable: absolute paths are not
portable and will be reported as asset warnings.

This layout follows the official `Gazebo Fuel model directory structure
<https://gazebosim.org/api/sim/10/meshtofuel.html#model-directory-structure>`_.
Do not zip an extra parent directory around the package contents unless that
directory is the single enclosing directory described above.