How to Record Assets, Units, Versions and Seeds in a Robot Simulation Exercise

Sources checked on 25 October 2026. This learning guide explains how to document a robot-simulation exercise so another learner can understand and repeat the setup. It does not claim that simulation validates a physical robot, a safety function or a production process.

A screenshot of a robot reaching a target is not a reproducible result. The same world can behave differently when the simulator release, physics engine, model files, plugin versions, initial pose, controller settings or random inputs change. A useful exercise record therefore treats the environment as part of the result. It identifies what ran, where each asset came from and which conditions were held constant.

Name the software stack precisely

Record the simulator release and the relevant library or package versions instead of writing only “Gazebo” or “ROS”. Gazebo releases are collections of versioned libraries, and the official release documentation distinguishes long-term, supported and rolling releases. A rolling stream may change continuously, while a named release constrains major library versions. The operating system, architecture, middleware distribution, bridge packages and controller packages should be listed as well.

Save the exact command used to start the exercise and the environment setup that preceded it. Include workspace revision identifiers, container image digests or package lock files where available. If a tutorial was followed, record its URL and access date, then note every local change. A later learner should be able to distinguish the upstream example from the files that produced the reported run.

Freeze the world, robot and external assets

Archive the world file, robot description, meshes, materials, plugin configuration and controller configuration under a versioned exercise folder. Gazebo Fuel can provide simulation models online, but a convenient model name alone is not a stable record. The Gazebo documentation describes local resource directories and the GZ_SIM_RESOURCE_PATH used to locate assets; recording those paths helps explain which local copy was actually loaded.

For each external asset, keep the owner or source, model name, version or revision if exposed, download date, licence, local path and a file hash. If the asset is referenced by a remote URI, also record whether the run used a cached copy. Do not republish an asset unless its licence permits it. If the exercise modifies a model, store the modified copy separately and describe the change instead of silently overwriting the source.

Write down units, frames and initial conditions

State the length, mass, time and angle units expected by every input. Record the world frame, robot base frame, tool frame and sensor frames, along with any fixed or dynamic transforms that matter to the task. A pose without a named reference frame is incomplete. For joint values, identify the joint order and whether angles are in radians or degrees. For velocities, forces and torques, include the unit and sign convention.

• World and robot initial pose, joint configuration and controller state.
• Object geometry, mass, inertia, collision shape and contact parameters.
• Gravity, physics engine, solver settings, time step and real-time factor target.
• Sensor update rates, noise settings, topic names and frame identifiers.
• Goal definition, tolerances, timeout and the exact condition counted as success.

Control randomness and separate deterministic inputs

If the exercise uses random object placement, noise, sampling or planning, record every seed that can be configured. Gazebo Sim has supported a custom random seed from the command line in its release history, but a simulator seed does not automatically control random generators inside every plugin, controller or external process. Record each separately. When a component does not expose a seed, mark that limitation rather than calling the run deterministic.

Repeat the run enough times to show whether the reported result is stable under the chosen seeds and initial conditions. Preserve per-run identifiers and raw outputs. Do not average successful and failed runs without retaining their counts and definitions. If a learning exercise is intended only to demonstrate a concept, say so; avoid converting one favourable run into a reliability or performance claim.

Capture commands, outputs and failure evidence

Keep the launch command, console output, simulator log, topic or state recordings, configuration files and a small machine-readable result summary. Gazebo's getting-started documentation shows verbose logging options and server-only operation; noting whether the GUI was present matters because rendering and interaction can affect resource use. Record the hardware available to the run, especially when timing or real-time factor is part of the observation.

When a run fails, preserve the first error and the state immediately before it. Re-running after changing several packages at once may hide the cause. Create a new experiment revision for each controlled change, and link it to the previous run. A short README should state the objective, prerequisites, setup, command, expected output, actual output and known deviations.

Use a reviewable exercise package

A practical package contains a manifest, locked or recorded dependencies, local asset inventory, launch files, world and robot descriptions, input data, per-run logs and a result table. It should also state what the simulation does not model, such as cable behaviour, wear, uncertain friction, human interaction, network delay or real controller limits. Those omissions define the boundary of the conclusion.

The site's industry information and site search can be used to find related learning notes. Public examples are starting points, not evidence that a model, plugin or parameter set is correct for a physical installation. Validate physical work under the applicable engineering and safety process.

Official references

References: Gazebo Releases; Gazebo: Model Insertion from Fuel; and Gazebo: Getting Started. The record structure above is original editorial guidance derived from the need to identify versioned software, assets and run conditions; it is not an official Gazebo certification procedure.