Plugin Loading

This tutorial shows how to create an executable that loads physics engine plugins on Ubuntu, according to the desired feature list.

Overview

Physics Plugin integrates external physics engines into the Gazebo Physics. It allows users to select from multiple supported physics engines based on their simulation needs. This tutorial will describe how to load a compiled physics plugin using Gazebo Physics API.

Prerequisites

• Installation
• Understanding the physics plugin

Write a simple loader

We will use a simplified physics plugin example for this tutorial. Source code can be found at gz-physics/examples folder.

First, create a workspace for the example plugin loader.

cd ~
mkdir -p ~/hello_world_loader/build
cd hello_world_loader

Then download the example loader into your current directory by:

wget https://raw.githubusercontent.com/gazebosim/gz-physics/main/examples/hello_world_loader/hello_world_loader.cc

Examine the code

At the top of the file hello_world_loader.cc, we include the headers that will be used in our code. After the std C++ libraries are the Loader.hh and PluginPtr.hh, which provides main functionalities for loading physics plugins and plugin pointers. Next includes from gz::physics are the tools for retrieving Feature and Entity from physics plugins (please refer to Understanding the physics plugin tutorial for their design concepts).

#include <iostream>
 
#include <gz/plugin/Loader.hh>
#include <gz/plugin/PluginPtr.hh>
 
#include <gz/physics/FindFeatures.hh>
#include <gz/physics/GetEntities.hh>
#include <gz/physics/RequestEngine.hh>
 
// The features that an engine must have to be loaded by this loader.
using Features = gz::physics::FeatureList<
    gz::physics::GetEngineInfo
>;

Next, in the main function, the loader requires users to provide a path for desired plugins to be loaded. The plugin names are retrieved by gz::plugin::Loader::LoadLib member function.

Assuming the correct path, our loader will instantiate all plugins that are available in the path using gz::plugin::Loader::Instantiate member function. Then for each instantiated plugin, using gz::physics::RequestEngine3d<Features>::From, it will request an engine implementing a FeaturePolicy (3D in this case).

int main(int argc, char **argv)
{
  // User should provide path to plugin library
  if (argc <= 1)
  {
    std::cerr << "Please provide the path to an engine plugin." << std::endl;
    return 1;
  }
 
  std::string pluginPath = argv[1];
 
  gz::plugin::Loader pl;
  auto plugins = pl.LoadLib(pluginPath);
 
  // Look for 3d plugins
  auto pluginNames = gz::physics::FindFeatures3d<Features>::From(pl);
  if (pluginNames.empty())
  {
    std::cerr << "No plugins with required features found in "
              << pluginPath
              << std::endl;
  }
 
  for (const std::string &name : pluginNames)
  {
    std::cout << "Testing plugin: " << name << std::endl;
    gz::plugin::PluginPtr plugin = pl.Instantiate(name);
 
    auto engine = gz::physics::RequestEngine3d<Features>::From(plugin);
 
    std::cout << "  engine name: " << engine->GetName() << std::endl;
  }
}

Setup CMakeLists.txt for CMake build

Now create a file named CMakeLists.txt with your favorite editor and add these lines for finding gz-plugin and gz-physics dependencies in Citadel release. After that, add the executable pointing to our file and add linking library so that cmake can compile it.

cmake_minimum_required(VERSION 3.22.1 FATAL_ERROR)
 
project(gz-physics-hello-world-loader)
 
find_package(gz-plugin3 REQUIRED COMPONENTS all)
set(GZ_PLUGIN_VER ${gz-plugin3_VERSION_MAJOR})
 
find_package(gz-physics8 REQUIRED)
set(GZ_PHYSICS_VER ${gz-physics8_VERSION_MAJOR})
 
add_executable(hello_world_loader hello_world_loader.cc)
target_link_libraries(hello_world_loader
  gz-plugin${GZ_PLUGIN_VER}::loader
  gz-physics${GZ_PHYSICS_VER}::gz-physics${GZ_PHYSICS_VER})

If you find CMake syntax difficult to understand, take a look at the official tutorial here.

Build and run

Compile the loader

Your current loader folder should look like this

$ ls ~/hello_world_loader
CMakeLists.txt  hello_world_loader.cc  build

Now you can build the loader by:

cd build
cmake ..
make

This will generate the hello_world_loader executable under build folder. This loader will load any plugin that implements the GetEngineInfo feature, and print the engine name.

Load existing plugins

For example, if you have the Gazebo Physics plugin for DART compiled, find where it is installed with (you may need administrative rights: sudo on Linux platform):

find / | grep libgz-physics-dartsim-plugin.so

You may find more than one file. Choose one of them, and load it with the loader by:

./hello_world_loader <path_to>/libgz-physics-dartsim-plugin.so

And you'll see the engine info:

Testing plugin: gz::physics::dartsim::Plugin
  engine name: dartsim-6.13.2

At the time of writing, Gazebo Physics is shipped with DART and TPE physics plugins installed. Following the above steps, you can load TPE by the library name libgz-physics-tpe-plugin.so or other custom plugins by their corresponding names.