Implementation:CARLA simulator Carla Python World Bindings

Knowledge Sources	CARLA
Domains	Python Bindings, World Management, Simulation Control
Last Updated	2026-02-15 05:00 GMT

Overview

World.cpp provides Boost.Python bindings for CARLA's world, timestamp, actor list, episode settings, and environment object types, enabling Python scripts to control and query the simulation world.

Description

This binding file exposes core simulation management types to Python via the export_world() function.

Stream Output Operators

• ActorList -- Delegates to a generic PrintList helper.
• World -- Outputs World(id=...).
• EpisodeSettings -- Outputs all settings including synchronous_mode, no_rendering_mode, fixed_delta_seconds, substepping parameters, max_culling_distance, and deterministic_ragdolls.
• EnvironmentObject -- Outputs id, name, transform, and bounding_box.

GIL-Releasing Wrapper Functions

• WaitForTick -- Wraps World::WaitForTick with GIL release and time duration conversion.
• Tick -- Wraps World::Tick with GIL release.
• ApplySettings -- Wraps World::ApplySettings with GIL release.

List Conversion Helpers

• GetActorsById -- Converts a Python list of actor IDs to C++ vector, then calls World::GetActors with GIL released.
• GetVehiclesLightStates -- Converts the returned map to a Python dictionary.
• GetLevelBBs -- Converts bounding box vector to Python list.
• GetEnvironmentObjects -- Converts environment objects to Python list.
• EnableEnvironmentObjects -- Converts Python iterable of IDs to C++ vector.

Python Class Bindings (via export_world)

• Timestamp -- Exposes frame, elapsed_seconds, delta_seconds, platform_timestamp with readwrite properties.
• ActorList -- Exposes find, filter, __getitem__, __len__, __iter__.
• WorldSettings (EpisodeSettings) -- Exposes all episode settings as readwrite properties, including the special fixed_delta_seconds property using Optional-to-Python conversion.
• EnvironmentObject -- Exposes transform, bounding_box, id, name, type.
• AttachmentType enum -- Rigid, SpringArm, SpringArmGhost.
• CityObjectLabel enum -- Full set of semantic labels (Buildings, Roads, Vehicles, Pedestrians, etc.).
• MapLayer enum -- Map layer types for loading/unloading.

Usage

These bindings are accessed through the carla Python module, primarily via carla.World, carla.Timestamp, carla.WorldSettings, and related types.

Code Reference

Source Location

• Repository: CARLA
• File: PythonAPI/carla/src/World.cpp (401 lines)

Signature

// GIL-releasing wrappers
static auto WaitForTick(const carla::client::World &world, double seconds);
static size_t OnTick(carla::client::World &self, boost::python::object callback);
static auto Tick(carla::client::World &world, double seconds);
static auto ApplySettings(carla::client::World &world,
                          carla::rpc::EpisodeSettings settings, double seconds);

// List conversion helpers
static auto GetActorsById(carla::client::World &self, const boost::python::list &actor_ids);
static auto GetVehiclesLightStates(carla::client::World &self);
static auto GetLevelBBs(const carla::client::World &self, uint8_t queried_tag);
static auto GetEnvironmentObjects(const carla::client::World &self, uint8_t queried_tag);
static void EnableEnvironmentObjects(carla::client::World &self,
                                     const boost::python::object& py_env_objects_ids, const bool enable);

// Main export function
void export_world();

Import

#include <PythonAPI.h>

I/O Contract

Inputs

Name	Type	Required	Description
world	carla::client::World	Yes	The simulation world instance
seconds	double	No	Timeout duration for tick/wait operations
settings	carla::rpc::EpisodeSettings	No	Episode settings to apply
actor_ids	boost::python::list	No	Python list of actor IDs to query
queried_tag	uint8_t	No	Semantic tag to filter environment objects or bounding boxes

Outputs

Name	Type	Description
WorldSnapshot	carla::client::WorldSnapshot	Returned by WaitForTick
frame_id	uint64_t	Returned by Tick
actor_list	SharedPtr<ActorList>	Returned by GetActorsById
light_states	boost::python::dict	Vehicle light states dictionary
bounding_boxes	boost::python::list	Level bounding boxes

Usage Examples

import carla

client = carla.Client('localhost', 2000)
world = client.get_world()

# Configure synchronous mode
settings = world.get_settings()
settings.synchronous_mode = True
settings.fixed_delta_seconds = 0.05
world.apply_settings(settings)

# Tick the simulation
frame_id = world.tick(timeout=10.0)

# Get actors by ID
actors = world.get_actors([42, 43, 44])

# Get all environment objects
env_objects = world.get_environment_objects(carla.CityObjectLabel.Buildings)

# Register tick callback
def on_tick(snapshot):
    print(f"Frame: {snapshot.frame}, Timestamp: {snapshot.timestamp}")
callback_id = world.on_tick(on_tick)

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• Implementation:CARLA_simulator_Carla_PythonAPI_Header - Master header included by this file
• Implementation:CARLA_simulator_Carla_WorldSnapshot_Class - WorldSnapshot returned by tick operations
• Implementation:CARLA_simulator_Carla_Timestamp_Class - Timestamp class exposed in this file
• Implementation:CARLA_simulator_Carla_Actor_Class - Actor class accessed through world methods