Gazebo Gazebo

API Reference

6.16.0

Migration from Gazebo-classic: World API

When migrating plugins from Gazebo-classic to Ignition Gazebo, developers will notice that the C++ APIs for both simulators are quite different. Be sure to check the plugin migration tutorial to get a high-level view of the architecture differences before using this guide.

This tutorial is meant to serve as a reference guide for developers migrating functions from the sim::physics::World class.

If you're trying to use some API which doesn't have an equivalent on Ignition yet, feel free to ticket an issue.

World API

Gazebo-classic's sim::physics::World provides lots of functionality, which can be divided in these categories:

You'll find the Ignition APIs below on the following headers:

It's worth remembering that most of this functionality can be performed using the EntityComponentManager directly. The functions presented here exist for convenience and readability.

Properties

Most of Gazebo-classic's World API is related to setting and getting properties. These functions are great candidates to have equivalents on Ignition Gazebo, because the Entity-Component-System architecture is perfect for setting components (properties) into entities such as worlds.

Classic Ignition
Atmosphere gz::sim::World::Atmosphere
AtmosphereEnabled TODO
DisableAllModels TODO
EnableAllModels TODO
GetSDFDom TODO
Gravity gz::sim::World::Gravity
IsLoaded Not applicable
IsPaused Use gz::sim::UpdateInfo
Iterations Use gz::sim::UpdateInfo
MagneticField gz::sim::World::MagneticField
Name gz::sim::World::Name
PauseTime Use gz::sim::UpdateInfo
Physics TODO
PhysicsEnabled TODO
PresetMgr TODO
PublishLightPose Use gz::sim::systems::PosePublisher
PublishModelPose Use gz::sim::systems::PosePublisher
PublishModelScale TODO
RealTime Use gz::sim::UpdateInfo
Running Not applicable
SDF TODO
SetAtmosphereEnabled TODO
SetGravity TODO
SetGravitySDF TODO
SetMagneticField TODO
SetPaused Use world control service
SetPhysicsEnabled TODO
SetSimTime Use world control service
SetState TODO
SetWindEnabled TODO
SimTime Use gz::sim::UpdateInfo
SphericalCoords TODO
StartTime Use gz::sim::UpdateInfo
URI TODO
UpdateStateSDF TODO
Wind TODO
WindEnabled TODO

Read family

These APIs deal with reading information related to child / parent relationships.

The main difference in these APIs across Gazebo generations is that on classic, they deal with shared pointers to entities, while on Ignition, they deal with entity IDs.

Classic Ignition
BaseByName Use type-specific gz::sim::World::*ByName
EntityByName Use type-specific gz::sim::World::*ByName
LightByName gz::sim::World::LightByName
LightCount gz::sim::World::LightCount
Lights gz::sim::World::Lights
ModelByIndex gz::sim::World::ModelByName
ModelByName gz::sim::World::ModelByName
ModelCount gz::sim::World::ModelCount
Models gz::sim::World::Models
PrintEntityTree Use scene graph service

Write family

These functions deal with modifying the entity tree, attaching children to new parents.

Classic Ignition
Clear TODO
ClearModels TODO
InsertModelFile TODO
InsertModelSDF gz::sim::SdfEntityCreator::CreateEntities
InsertModelString TODO
RemoveModel TODO
RemovePlugin TODO

Lifecycle

These functions aren't related to the state of a model, but perform some processing related to the model's lifecycle, like initializing, updating or terminating it.

Classic Ignition
Fini N/A
Init N/A
Load gz::sim::SdfEntityCreator::CreateEntities
LoadLight gz::sim::SdfEntityCreator::CreateEntities
LoadPlugin TODO
Reset TODO
ResetEntities TODO
ResetPhysicsStates TODO
ResetTime Use world control service
Run See server API
RunBlocking See server API
SensorsInitialized N/A
Step See server API
Stop See server API
_AddDirty N/A
_SetSensorsInitialized N/A

Others

Miscelaneous functions that don't fit the other categories. Most of them involve logic that should be performed from within a system.

Classic Ignition
EntityBelowPoint Requires a system
ModelBelowPoint Requires a system
SceneMsg Use gz::sim::systems::SceneBoradcaster
WorldPoseMutex N/A
StripWorldName N/A
UniqueModelName TODO
Save Use SDF generator