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:

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:

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:

<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. Do not zip an extra parent directory around the package contents unless that directory is the single enclosing directory described above.