Gazebo World Checkpoint: Plugin State Persistence Across Save/Load

Question

Gazebo's world checkpointing feature serializes simulation state to a persistent file, capturing model poses, physics engine configurations, and SDF‑declared plugin parameters. The mechanism is documented for regression testing, CI reproducibility, and cross‑session pause/resume scenarios.

However, the serialization scope for plugin‑internal state remains ambiguous. Plugin code that stores state in C++ member variables not exposed through SDF may not be automatically captured during save, and its restoration during load is not guaranteed. Cross‑release compatibility hints suggest potential data loss when checkpoints migrate between major Gazebo versions, particularly after physics engine upgrades.

Does the save operation inspect plugin memory regions beyond SDF declarations? If the load service invokes user‑implemented System::Load callbacks, what assurances exist regarding the completeness of restored state? How does a major version transition affect the integrity of plugin state stored in checkpoint files?

Tasadduq Burney · Answer

Direct AnswersNo. The save operation does not inspect plugin memory regions beyond SDF declarations. It serializes only model poses, physics engine configuration, and the SDF-exposed parameters of each plugin.No automatic assurances. When the load service invokes a plugin's System::Load (or Init) callback, it passes only the restored SDF values. Any C++ member variables, heap allocations, or runtime state not mirrored in SDF are not restored unless the plugin implements the gazebo::event::SaveState/LoadState hooks (Gazebo ≥ 11) or writes its own sidecar file.Major version transitions break compatibility. Checkpoint files embed the Gazebo version and the SDF/physics schema they were created with. Loading a checkpoint from Gazebo 11 into Gazebo 12 (or vice versa) typically produces version-mismatch warnings and discards plugin-specific data that the newer parser cannot map.How Checkpointing Actually WorksWorld::Save iterates over models, the physics engine, and each plugin's SDF element.For each plugin it writes the current SDF parameter values—not the plugin's internal C++ state.On load, World::Load reconstructs the world from that SDF, then calls each plugin's Load(sdf) with the restored parameters.If a plugin needs to survive a save/load cycle, it must:Expose every persistent variable through SDF (so it gets serialized automatically), orConnect to gazebo::event::Events::SaveState / LoadState and serialize/deserialize its own binary blob.Version Migration ChecklistScenarioExpected OutcomeMitigationSame Gazebo major versionSDF parameters restore; custom state lost unless plugin implements SaveState/LoadStateAdd SaveState/LoadState hooksMajor version upgrade (e.g., 11 → 12)Checkpoint load emits warnings; plugin SDF may be partially parsed; custom state discardedShip a migration tool that reads old checkpoint, extracts needed data, writes new checkpointPhysics engine swap (ODE → DART, etc.)Physics-specific fields dropped; plugin state tied to old engine lostDecouple plugin state from physics engine internalsVerification Steps for Your PluginAdd a diagnostic integer member int checkpointCounter = 42; to your plugin.Enable world checkpointing (gz world -s -w my_world --checkpoint).Save a checkpoint, then load it in the same Gazebo version.Log the value in Load(). If it reads 0 (default) instead of 42, internal state was not persisted.Implement SaveState/LoadState and repeat; the counter should survive.One Diagnostic Detail NeededWhich Gazebo major version are you targeting for the save and which for the load? The answer determines whether you need a migration layer or can rely on same-version SaveState/LoadState hooks alone.

Gazebo World Checkpoint: Plugin State Persistence Across Save/Load

1 answer

Direct Answers

How Checkpointing Actually Works

Version Migration Checklist

Verification Steps for Your Plugin

One Diagnostic Detail Needed

Your perspective belongs here.

0 question comments

Scenario	Expected Outcome	Mitigation
Same Gazebo major version	SDF parameters restore; custom state lost unless plugin implements SaveState/LoadState	Add SaveState/LoadState hooks
Major version upgrade (e.g., 11 → 12)	Checkpoint load emits warnings; plugin SDF may be partially parsed; custom state discarded	Ship a migration tool that reads old checkpoint, extracts needed data, writes new checkpoint
Physics engine swap (ODE → DART, etc.)	Physics-specific fields dropped; plugin state tied to old engine lost	Decouple plugin state from physics engine internals