Implementation:CARLA simulator Carla WorldSnapshot Class

Knowledge Sources	CARLA
Domains	Client Library, Simulation State, Snapshot
Last Updated	2026-02-15 05:00 GMT

Overview

WorldSnapshot provides an immutable snapshot of the simulation world at a specific point in time, containing the timestamp and state of all actors present in the episode.

Description

The WorldSnapshot class in the carla::client namespace wraps a shared pointer to a detail::EpisodeState and provides a read-only view of the world at a particular simulation tick.

Construction

Takes a std::shared_ptr<const detail::EpisodeState> which contains the complete state captured from the simulator.

Episode Identification

• GetId() -- Returns the uint64_t episode ID associated with this snapshot.

Frame Information

• GetFrame() -- Returns the frame number from the snapshot's timestamp.
• GetTimestamp() -- Returns a const reference to the Timestamp object containing frame, elapsed_seconds, delta_seconds, and platform_timestamp.

Actor Access

• Contains(actor_id) -- Checks if an actor with the given ActorId is present in this snapshot.
• Find(actor_id) -- Returns a std::optional<ActorSnapshot> for the given actor ID. The ActorSnapshot contains the actor's transform, velocity, acceleration, and other state data.

Iteration

• size() -- Returns the number of ActorSnapshots in this snapshot.
• begin() / end() -- Iterators for ranging over all actor snapshots.

Comparison

• operator== / operator!= -- Two snapshots are equal if their timestamps are equal.

The class is designed to be lightweight, holding only a shared pointer to the underlying state data, making copies inexpensive.

Usage

WorldSnapshots are returned by World::WaitForTick() and World::OnTick() callbacks. They provide a consistent view of the simulation state at a specific frame, useful for synchronous simulation control and data analysis.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/client/WorldSnapshot.h (77 lines)

Signature

namespace carla {
namespace client {

class WorldSnapshot {
public:
  WorldSnapshot(std::shared_ptr<const detail::EpisodeState> state);

  uint64_t GetId() const;
  size_t GetFrame() const;
  const Timestamp &GetTimestamp() const;

  bool Contains(ActorId actor_id) const;
  std::optional<ActorSnapshot> Find(ActorId actor_id) const;

  size_t size() const;
  auto begin() const;
  auto end() const;

  bool operator==(const WorldSnapshot &rhs) const;
  bool operator!=(const WorldSnapshot &rhs) const;

private:
  std::shared_ptr<const detail::EpisodeState> _state;
};

} // namespace client
} // namespace carla

Import

#include "carla/client/WorldSnapshot.h"

I/O Contract

Inputs

Name	Type	Required	Description
state	std::shared_ptr<const detail::EpisodeState>	Yes	Episode state captured at a simulation tick
actor_id	ActorId	No (for Contains/Find)	Actor identifier to look up in the snapshot

Outputs

Name	Type	Description
id	uint64_t	Episode identifier
frame	size_t	Frame number of this snapshot
timestamp	const Timestamp&	Full timestamp with elapsed and delta seconds
contains	bool	Whether an actor is present in this snapshot
actor_snapshot	std::optional<ActorSnapshot>	Actor state data if found, empty optional otherwise
size	size_t	Number of actor snapshots in this world snapshot

Usage Examples

// Synchronous mode: wait for tick
auto snapshot = world.WaitForTick(std::chrono::seconds(10));

// Access frame info
std::cout << "Frame: " << snapshot.GetFrame() << std::endl;
std::cout << "Timestamp: " << snapshot.GetTimestamp() << std::endl;

// Check for a specific actor
if (snapshot.Contains(ego_vehicle_id)) {
    auto actor_snapshot = snapshot.Find(ego_vehicle_id);
    if (actor_snapshot.has_value()) {
        auto transform = actor_snapshot->transform;
        auto velocity = actor_snapshot->velocity;
    }
}

// Iterate over all actors in the snapshot
for (auto it = snapshot.begin(); it != snapshot.end(); ++it) {
    // Process each ActorSnapshot
}

std::cout << "Total actors: " << snapshot.size() << std::endl;

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_Timestamp_Class - Timestamp embedded in this snapshot
• CARLA_simulator_Carla_Python_World_Bindings - Python bindings that expose WorldSnapshot
• CARLA_simulator_Carla_Actor_Class - Actor snapshots contained within