How to adapt your world or PROTO to Webots R2022b

What are EXTERNPROTO

PROTO nodes are a powerful way of describing complex objects or robots. PROTO files however evolve, bugs are fixed, and given that there is no inherent way of defining a specific version of a PROTO to be used when loading a world, older simulations no longer behave the same way due to these changes. Moreover, with the addition of JavaScript as a template language for procedural PROTO nodes, having PROTO files as external assets that can be downloaded on the fly opens up, for example, the possibility of rendering a PROTO directly from the web.

For these reasons, from R2022b, all PROTO files used by a world need to be declared using the EXTERNPROTO keyword. Similarly, every PROTO inserted during the execution of the simulation by a supervisor needs to be declared an Ephemeral EXTERNPROTO prior to import it.

Offline assets

PROTO, texture, mesh and sound assets are downloaded when needed during the loading of the world. These files are subsequently cached and the local version will be used in subsequent loads.

The entirety of these assets is also provided as a zip (assets-R2022b.zip) file, which can be downloaded and extracted following the procedure described here.

How are EXTERNPROTO (and Ephemeral EXTERNPROTO) declared

When opening a world file using a text editor, declared PROTO will look like:

#VRML_SIM R2022b utf8

EXTERNPROTO "https://raw.githubusercontent.com/cyberbotics/webots/R2022b/projects/objects/backgrounds/protos/TexturedBackground.proto"

WorldInfo {
  basicTimeStep 16
}
Viewpoint {
}
TexturedBackground {
}

In this case, the PROTO TexturedBackground will be retrieved from the corresponding url. Similarly, a PROTO may reference another PROTO, in this case a declaration is also necessary:

#VRML_SIM R2022b utf8

EXTERNPROTO "https://raw.githubusercontent.com/cyberbotics/webots/R2022b/projects/appearances/protos/Plastic.proto"

PROTO MyProto [
  field SFVec3f  size    0.1 0.1 0.1  # Defines the size of the box.
]
{
  Shape {
    appearance Plastic {
    }
    geometry Box {
      size IS size
    }
  }
}

In general, the url can be defined multiple ways:

# remote PROTO
EXTERNPROTO "https://raw.githubusercontent.com/cyberbotics/webots/R2022b/projects/objects/backgrounds/protos/TexturedBackground.proto"

# local PROTO (absolute path)
EXTERNPROTO "/home/user/Documents/my_project/protos/TexturedBackground.proto"

# local PROTO (relative path)
EXTERNPROTO "../protos/TexturedBackground.proto"

The location (url) for official PROTO can be found in the file: WEBOTS_HOME/resources/proto-list.xml When inserting PROTO nodes using the add-node button, a declaration is added automatically.

Ephemeral EXTERNPROTO declaration

Under the hood, EXTERNPROTO and Ephemeral EXTERNPROTO are treated in the same manner so the information provided above is valid for ephemeral EXTERNPROTO as well. What distinguishes the two is that, as the name implies, PROTO nodes that are ephemeral don't exist when the world is loaded but instead may appear later on during the execution of the simulation, typically when spawned by a supervisor.

Therefore, declared PROTO nodes that have no instances in the world at load-time will be shown under the Ephemeral EXTERNPROTO panel, which can be opened by clicking the similarly named button:

Doing so will open the panel:

Only PROTO included in this list can be inserted into the world using a Supervisor. Therefore if your controller spawns PROTO nodes, you need to declare them prior to doing so.

Preparing your world for R2022b

If your world was created before R2022a, generally speaking it should be sufficient for you to load it with Webots R2022b and click the save button. Doing so, the backwards compatibility mechanism will add the declaration for you by assuming you are using the official Webots PROTO nodes and therefore setting the url accordingly. If however your world uses locally defined PROTO, the process may fail. For this reason, a script is provided.

1. Download the script:
2. Place it at the root level of your project (the same directory that contains the protos, worlds and controllers folders)
3. Run the script by providing the location of your webots installation as argument.
4. Load the world using Webots

Note that the script only declares instantiated PROTO. If your controller spawns additional PROTO nodes using a supervisor, you need to declared the corresponding Ephemeral EXTERNPROTO accordingly.