carla 0.14.1

use super::{
    Actor, ActorBase, ActorBlueprint, ActorBuilder, ActorList, ActorVec, BlueprintLibrary,
    BoundingBoxList, DebugHelper, EnvironmentObjectList, LabelledPointList, Landmark, LightManager,
    Map, Waypoint, WorldSnapshot,
};
#[cfg(carla_0100)]
use crate::rpc::{MaterialParameter, TextureColor, TextureFloatColor};
use crate::{
    error::{OperationError, Result, ffi::with_ffi_error},
    geom::{Location, Transform, Vector3D},
    road::JuncId,
    rpc::{
        ActorId, AttachmentType, EpisodeSettings, LabelledPoint, MapLayer, VehicleLightStateList,
        WeatherParameters,
    },
    utils::CxxVectorExt,
};
use autocxx::prelude::*;
use carla_sys::carla_rust::{
    client::{FfiActor, FfiWorld, FfiWorldSnapshot},
    geom::FfiVector3D,
};
use cxx::{CxxVector, UniquePtr, let_cxx_string};
use derivative::Derivative;
use static_assertions::assert_impl_all;
use std::{mem, ptr, time::Duration};

use autocxx::c_void;

const DEFAULT_TICK_TIMEOUT: Duration = Duration::from_secs(60);

/// The world contains the map and assets of a simulation.
///
/// [`World`] is the main interface for interacting with the simulation. It provides:
/// - Access to the simulation [`Map`] and environment
/// - Actor spawning and management
/// - Weather and lighting control
/// - Simulation settings (synchronous mode, fixed time step, etc.)
/// - Traffic light management
/// - World snapshots for state inspection
///
/// Corresponds to [`carla.World`] in the Python API.
#[cfg_attr(carla_version_0916, doc = "")]
#[cfg_attr(
    carla_version_0916,
    doc = " [`carla.World`]: https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World"
)]
#[cfg_attr(carla_version_0915, doc = "")]
#[cfg_attr(
    carla_version_0915,
    doc = " [`carla.World`]: https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World"
)]
#[cfg_attr(carla_version_0914, doc = "")]
#[cfg_attr(
    carla_version_0914,
    doc = " [`carla.World`]: https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World"
)]
///
/// # Thread Safety
///
/// [`World`] implements [`Send`] and [`Sync`] and can be cloned cheaply (internally
/// reference-counted).
///
/// # Examples
///
/// ```no_run
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// use carla::client::Client;
///
/// let client = Client::connect("localhost", 2000, None)?;
/// let mut world = client.world()?;
///
/// // Get simulation info
/// println!("World ID: {}", world.id()?);
/// let map = world.map()?;
/// println!("Map: {}", map.name());
///
/// // Spawn an actor
/// let bp_lib = world.blueprint_library()?;
/// let vehicle_bp = bp_lib.filter("vehicle.tesla.model3").get(0).unwrap();
/// let spawn_points = map.recommended_spawn_points();
/// if let Some(spawn_point) = spawn_points.get(0) {
///     let actor = world.spawn_actor(&vehicle_bp, &spawn_point)?;
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Derivative)]
#[derivative(Debug)]
#[repr(transparent)]
pub struct World {
    #[derivative(Debug = "ignore")]
    pub(crate) inner: UniquePtr<FfiWorld>,
}

impl World {
    /// Returns the unique ID of this world/episode.
    ///
    /// The ID changes whenever the world is reloaded or a new map is loaded.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.id](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.id)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.id](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.id)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.id](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.id)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn id(&self) -> Result<u64> {
        with_ffi_error("World::id", |e| self.inner.GetId(e))
    }

    /// Returns the map associated with this world.
    ///
    /// The map contains the road network, spawn points, and navigation information.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_map](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_map)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_map](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_map)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_map](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_map)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn map(&self) -> crate::Result<Map> {
        let ptr = with_ffi_error("map", |e| self.inner.GetMap(e))?;
        Ok(unsafe { Map::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns the light manager for controlling street lights and vehicle lights.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_lightmanager](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_lightmanager)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_lightmanager](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_lightmanager)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_lightmanager](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_lightmanager)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn light_manager(&self) -> crate::Result<LightManager> {
        let ptr = with_ffi_error("light_manager", |e| self.inner.GetLightManager(e))?;
        Ok(unsafe { LightManager::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Loads a map layer (e.g., buildings, props, roads).
    ///
    /// Use this to dynamically load/unload parts of the map for performance.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.load_map_layer](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.load_map_layer)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.load_map_layer](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.load_map_layer)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.load_map_layer](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.load_map_layer)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn load_level_layer(&self, map_layers: MapLayer) -> crate::Result<()> {
        with_ffi_error("load_level_layer", |e| {
            self.inner.LoadLevelLayer(map_layers as u16, e)
        })
    }

    /// Unloads a map layer.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.unload_map_layer](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.unload_map_layer)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.unload_map_layer](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.unload_map_layer)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.unload_map_layer](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.unload_map_layer)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn unload_level_layer(&self, map_layers: MapLayer) -> crate::Result<()> {
        with_ffi_error("unload_level_layer", |e| {
            self.inner.UnloadLevelLayer(map_layers as u16, e)
        })
    }

    /// Returns the blueprint library containing all available actor blueprints.
    ///
    /// Blueprints are templates for spawning actors (vehicles, sensors, pedestrians, etc.).
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_blueprint_library](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_blueprint_library)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_blueprint_library](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_blueprint_library)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_blueprint_library](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_blueprint_library)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::client::Client;
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let world = client.world()?;
    /// let bp_lib = world.blueprint_library()?;
    ///
    /// // Find all vehicle blueprints
    /// let vehicles = bp_lib.filter("vehicle.*");
    /// println!("Found {} vehicle types", vehicles.len());
    /// # Ok(())
    /// # }
    /// ```
    pub fn blueprint_library(&self) -> crate::Result<BlueprintLibrary> {
        let ptr = with_ffi_error("blueprint_library", |e| self.inner.GetBlueprintLibrary(e))?;
        Ok(unsafe { BlueprintLibrary::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns the light state of all vehicles in the world.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_vehicles_light_states](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_vehicles_light_states)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_vehicles_light_states](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_vehicles_light_states)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_vehicles_light_states](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_vehicles_light_states)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn vehicle_light_states(&self) -> crate::Result<VehicleLightStateList> {
        let ptr = with_ffi_error("vehicle_light_states", |e| {
            self.inner.GetVehiclesLightStates(e)
        })?;
        Ok(unsafe { VehicleLightStateList::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns a random navigable location (on roads/sidewalks).
    ///
    /// Useful for spawning actors at random valid positions.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_random_location_from_navigation](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_random_location_from_navigation)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_random_location_from_navigation](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_random_location_from_navigation)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_random_location_from_navigation](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_random_location_from_navigation)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn random_location_from_navigation(&self) -> crate::Result<Location> {
        let ptr = with_ffi_error("random_location_from_navigation", |e| {
            self.inner.GetRandomLocationFromNavigation(e)
        })?;
        Ok(Location::from_ffi(ptr.as_ref().unwrap().clone()))
    }

    /// Returns the spectator actor (the free-flying camera).
    ///
    /// Move the spectator to change the view in the CARLA window.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_spectator](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_spectator)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_spectator](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_spectator)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_spectator](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_spectator)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn spectator(&self) -> crate::Result<Actor> {
        let ptr = with_ffi_error("spectator", |e| self.inner.GetSpectator(e))?;
        Ok(unsafe { Actor::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns the current simulation settings.
    ///
    /// Settings include synchronous mode, fixed time step, rendering options, etc.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_settings](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_settings)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_settings](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_settings)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_settings](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_settings)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn settings(&self) -> crate::Result<EpisodeSettings> {
        let ptr = with_ffi_error("settings", |e| self.inner.GetSettings(e))?;
        Ok(EpisodeSettings::from_cxx(&ptr))
    }

    /// Returns a snapshot of the current world state.
    ///
    /// Snapshots contain actor transforms, velocities, and simulation timestamp.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_snapshot](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_snapshot)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_snapshot](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_snapshot)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_snapshot](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_snapshot)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn snapshot(&self) -> crate::Result<WorldSnapshot> {
        let ptr = with_ffi_error("snapshot", |e| self.inner.GetSnapshot(e))?;
        Ok(unsafe { WorldSnapshot::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns names of all environment objects in the world.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_names_of_all_objects](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_names_of_all_objects)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_names_of_all_objects](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_names_of_all_objects)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_names_of_all_objects](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_names_of_all_objects)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn names_of_all_objects(&self) -> crate::Result<Vec<String>> {
        let names = with_ffi_error("names_of_all_objects", |e| {
            self.inner.GetNamesOfAllObjects(e)
        })?;
        Ok(names.iter().map(|s| s.to_string()).collect())
    }

    /// Finds an actor by its ID.
    ///
    /// Returns `None` if the actor doesn't exist or has been destroyed.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_actor](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_actor)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_actor](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_actor)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_actor](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_actor)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn actor(&self, actor_id: ActorId) -> crate::Result<Option<Actor>> {
        let ptr = with_ffi_error("actor", |e| self.inner.GetActor(actor_id, e))?;
        Ok(Actor::from_cxx(ptr))
    }

    /// Returns a list of all actors currently in the world.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_actors](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_actors)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_actors](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_actors)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_actors](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_actors)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::client::Client;
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let world = client.world()?;
    /// let actors = world.actors()?;
    /// println!("Total actors: {}", actors.len());
    /// # Ok(())
    /// # }
    /// ```
    pub fn actors(&self) -> crate::Result<ActorList> {
        let ptr = with_ffi_error("actors", |e| self.inner.GetActors(e))?;
        Ok(unsafe { ActorList::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns a list of actors matching the given IDs.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_actors](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_actors)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_actors](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_actors)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_actors](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_actors)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn actors_by_ids(&self, ids: &[ActorId]) -> crate::Result<ActorList> {
        let mut vec = CxxVector::new_typed();
        ids.iter().cloned().for_each(|id| {
            vec.pin_mut().push(id);
        });

        let ptr = with_ffi_error("actors_by_ids", |e| self.inner.GetActorsByIds(&vec, e))?;
        Ok(unsafe { ActorList::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns traffic lights affecting a waypoint within a certain distance.
    ///
    /// # Arguments
    /// * `waypoint` - The waypoint to check from
    /// * `distance` - Maximum distance to search for traffic lights
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_traffic_lights_from_waypoint](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_traffic_lights_from_waypoint)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_traffic_lights_from_waypoint](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_traffic_lights_from_waypoint)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_traffic_lights_from_waypoint](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_traffic_lights_from_waypoint)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn traffic_lights_from_waypoint(
        &self,
        waypoint: &Waypoint,
        distance: f64,
    ) -> crate::Result<ActorVec> {
        let ptr = with_ffi_error("traffic_lights_from_waypoint", |e| {
            self.inner
                .GetTrafficLightsFromWaypoint(&waypoint.inner, distance, e)
        })?;
        Ok(unsafe { ActorVec::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns all traffic lights in a junction.
    ///
    /// # Arguments
    /// * `junc_id` - Junction ID to query
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_traffic_lights_in_junction](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_traffic_lights_in_junction)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_traffic_lights_in_junction](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_traffic_lights_in_junction)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_traffic_lights_in_junction](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_traffic_lights_in_junction)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn traffic_lights_in_junction(&self, junc_id: JuncId) -> crate::Result<ActorVec> {
        let ptr = with_ffi_error("traffic_lights_in_junction", |e| {
            self.inner.GetTrafficLightsInJunction(junc_id.into(), e)
        })?;
        Ok(unsafe { ActorVec::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Applies new simulation settings.
    ///
    /// Use this to change synchronous mode, time step, rendering options, etc.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.apply_settings](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.apply_settings)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.apply_settings](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.apply_settings)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.apply_settings](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.apply_settings)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Arguments
    ///
    /// * `settings` - The new settings to apply
    /// * `timeout` - Maximum time to wait for the operation
    ///
    /// # Returns
    ///
    /// The frame number when the settings were applied.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::client::Client;
    /// use std::time::Duration;
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let mut world = client.world()?;
    ///
    /// let mut settings = world.settings()?;
    /// settings.synchronous_mode = true;
    /// settings.fixed_delta_seconds = Some(0.05);
    /// world.apply_settings(&settings, Duration::from_secs(2))?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn apply_settings(
        &mut self,
        settings: &EpisodeSettings,
        timeout: Duration,
    ) -> crate::Result<u64> {
        let ffi_settings = settings.to_cxx();
        let millis = timeout.as_millis() as usize;
        with_ffi_error("apply_settings", |e| {
            self.inner.pin_mut().ApplySettings(&ffi_settings, millis, e)
        })
    }

    /// Spawns an actor in the world.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.spawn_actor](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.spawn_actor)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.spawn_actor](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.spawn_actor)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.spawn_actor](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.spawn_actor)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Arguments
    ///
    /// * `blueprint` - The actor blueprint (from [`blueprint_library()`](Self::blueprint_library))
    /// * `transform` - Initial position and rotation
    ///
    /// # Returns
    ///
    /// The spawned [`Actor`], or an error if spawning failed (e.g., collision with
    /// another object).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::client::{ActorBase, Client};
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let mut world = client.world()?;
    ///
    /// let bp_lib = world.blueprint_library()?;
    /// let vehicle_bp = bp_lib.filter("vehicle.tesla.model3").get(0).unwrap();
    ///
    /// let spawn_points = world.map()?.recommended_spawn_points();
    /// if let Some(spawn_point) = spawn_points.get(0) {
    ///     match world.spawn_actor(&vehicle_bp, &spawn_point) {
    ///         Ok(actor) => println!("Spawned actor {}", actor.id()),
    ///         Err(e) => eprintln!("Failed to spawn: {}", e),
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn spawn_actor(
        &mut self,
        blueprint: &ActorBlueprint,
        transform: &Transform,
    ) -> Result<Actor> {
        self.spawn_actor_opt::<Actor, _>(blueprint, transform, None, None)
    }

    /// Spawns an actor with optional parent attachment.
    ///
    /// **Important**: In synchronous mode, the actor's spawn is queued but not processed until
    /// the next tick. You must call [`wait_for_tick()`](Self::wait_for_tick) or [`tick()`](Self::tick)
    /// after spawning to ensure the actor is actually created in the simulation before querying
    /// its properties (position, etc.).
    ///
    /// # Arguments
    ///
    /// * `blueprint` - The actor blueprint
    /// * `transform` - Initial position and rotation (relative to parent if attached)
    /// * `parent` - Optional parent actor to attach to
    /// * `attachment_type` - How to attach to parent (Rigid, SpringArm, etc.)
    ///
    /// # Examples
    ///
    /// Attaching a camera to a vehicle:
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::{
    ///     client::Client,
    ///     geom::{Location, Rotation, Transform},
    ///     rpc::AttachmentType,
    /// };
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let mut world = client.world()?;
    /// # let bp_lib = world.blueprint_library()?;
    /// # let vehicle_bp = bp_lib.filter("vehicle.*").get(0).unwrap();
    /// # let spawn_points = world.map()?.recommended_spawn_points();
    /// # let vehicle_actor = world.spawn_actor(&vehicle_bp, &spawn_points.get(0).unwrap())?;
    /// # let vehicle: carla::client::Vehicle = vehicle_actor.try_into().unwrap();
    ///
    /// // Spawn camera attached to vehicle
    /// let camera_bp = bp_lib.filter("sensor.camera.rgb").get(0).unwrap();
    /// let camera_transform = Transform {
    ///     location: Location::new(0.0, 0.0, 2.0),
    ///     rotation: Rotation::default(),
    /// };
    ///
    /// let camera = world.spawn_actor_opt(
    ///     &camera_bp,
    ///     &camera_transform,
    ///     Some(&vehicle),
    ///     AttachmentType::Rigid,
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn spawn_actor_opt<A, T>(
        &mut self,
        blueprint: &ActorBlueprint,
        transform: &Transform,
        parent: Option<&A>,
        attachment_type: T,
    ) -> Result<Actor>
    where
        A: ActorBase,
        T: Into<Option<AttachmentType>>,
    {
        let parent = parent.map(|parent| parent.cxx_actor());
        let attachment_type = attachment_type.into().unwrap_or(AttachmentType::Rigid);

        unsafe {
            let parent_ptr: *mut FfiActor = parent
                .as_ref()
                .and_then(|parent| parent.as_ref())
                .map(|ref_| ref_ as *const _ as *mut _)
                .unwrap_or(ptr::null_mut());
            let ffi_transform = transform.clone();
            #[cfg(carla_version_0916)]
            let actor = {
                use cxx::let_cxx_string;
                let_cxx_string!(socket_name = "");
                with_ffi_error("World::try_spawn_actor", |e| {
                    self.inner.pin_mut().TrySpawnActor(
                        &blueprint.inner,
                        ffi_transform.as_ffi(),
                        parent_ptr,
                        attachment_type,
                        &socket_name,
                        e,
                    )
                })?
            };
            #[cfg(not(carla_version_0916))]
            let actor = with_ffi_error("World::try_spawn_actor", |e| {
                self.inner.pin_mut().TrySpawnActor(
                    &blueprint.inner,
                    ffi_transform.as_ffi(),
                    parent_ptr,
                    attachment_type,
                    e,
                )
            })?;
            Actor::from_cxx(actor).ok_or_else(|| {
                OperationError::SpawnFailed {
                    blueprint: blueprint.id().to_string(),
                    transform: format!("{:?}", transform),
                    reason: "Spawn returned null (likely collision or invalid location)"
                        .to_string(),
                    source: None,
                }
                .into()
            })
        }
    }

    /// Spawns an actor attached to a parent actor (convenience method).
    ///
    /// This is a convenience wrapper around [`spawn_actor_opt`](Self::spawn_actor_opt) that
    /// makes the API clearer when you specifically want to attach an actor to a parent.
    ///
    /// # Arguments
    ///
    /// * `blueprint` - The actor blueprint
    /// * `transform` - Initial position and rotation (relative to parent)
    /// * `parent` - Parent actor to attach to
    /// * `attachment_type` - How to attach to parent (defaults to [`AttachmentType::Rigid`] if not specified)
    ///
    /// # Examples
    ///
    /// Attaching a camera sensor to a vehicle:
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::{
    ///     client::Client,
    ///     geom::{Location, Rotation, Transform},
    ///     rpc::AttachmentType,
    /// };
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let mut world = client.world()?;
    /// let bp_lib = world.blueprint_library()?;
    ///
    /// // Spawn a vehicle
    /// let vehicle_bp = bp_lib.filter("vehicle.tesla.model3").get(0).unwrap();
    /// let spawn_points = world.map()?.recommended_spawn_points();
    /// let vehicle = world.spawn_actor(&vehicle_bp, &spawn_points.get(0).unwrap())?;
    ///
    /// // Attach a camera to the vehicle's roof
    /// let camera_bp = bp_lib.find("sensor.camera.rgb").unwrap();
    /// let camera_transform = Transform {
    ///     location: Location::new(0.0, 0.0, 2.5), // 2.5m above vehicle center
    ///     rotation: Rotation::default(),
    /// };
    ///
    /// let camera = world.spawn_actor_attached(
    ///     &camera_bp,
    ///     &camera_transform,
    ///     &vehicle,
    ///     AttachmentType::Rigid, // Camera moves rigidly with vehicle
    /// )?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See also: [`spawn_actor_opt`](Self::spawn_actor_opt) for spawning with optional parent
    pub fn spawn_actor_attached<A, T>(
        &mut self,
        blueprint: &ActorBlueprint,
        transform: &Transform,
        parent: &A,
        attachment_type: T,
    ) -> Result<Actor>
    where
        A: ActorBase,
        T: Into<Option<AttachmentType>>,
    {
        self.spawn_actor_opt(blueprint, transform, Some(parent), attachment_type)
    }

    /// Waits for the next simulation tick and returns the world snapshot.
    ///
    /// In synchronous mode, the server waits for this call before advancing the simulation.
    /// In asynchronous mode, this returns when the next tick completes.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.wait_for_tick](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.wait_for_tick)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.wait_for_tick](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.wait_for_tick)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.wait_for_tick](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.wait_for_tick)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Errors
    ///
    /// Returns an error if the operation times out (default: 60 seconds).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::client::Client;
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let world = client.world()?;
    ///
    /// // Wait for next tick
    /// let snapshot = world.wait_for_tick()?;
    /// println!("Frame: {}", snapshot.frame());
    /// # Ok(())
    /// # }
    /// ```
    pub fn wait_for_tick(&self) -> Result<WorldSnapshot> {
        self.wait_for_tick_or_timeout(DEFAULT_TICK_TIMEOUT)?
            .ok_or_else(|| {
                crate::error::ConnectionError::Timeout {
                    operation: "wait_for_tick".to_string(),
                    duration: DEFAULT_TICK_TIMEOUT,
                    source: None,
                }
                .into()
            })
    }

    /// Creates an actor builder for convenient actor spawning with attribute configuration.
    ///
    /// # Arguments
    ///
    /// * `key` - Blueprint ID (e.g., "vehicle.tesla.model3")
    pub fn actor_builder(&mut self, key: &str) -> Result<ActorBuilder<'_>> {
        ActorBuilder::new(self, key)
    }

    /// Waits for the next tick with a custom timeout.
    ///
    /// Returns `Ok(None)` if the timeout expires (expected behavior).
    /// Returns `Err` if the server is disconnected or another error occurs.
    pub fn wait_for_tick_or_timeout(&self, timeout: Duration) -> Result<Option<WorldSnapshot>> {
        with_ffi_error("wait_for_tick", |error| {
            let ptr = self.inner.WaitForTick(timeout.as_millis() as usize, error);
            WorldSnapshot::from_cxx(ptr)
        })
    }

    /// Advances the simulation by one tick (synchronous mode only).
    ///
    /// # Arguments
    ///
    /// * `timeout` - Maximum time to wait for the tick
    ///
    /// # Returns
    ///
    /// The frame number after the tick.
    pub fn tick_or_timeout(&mut self, timeout: Duration) -> crate::Result<u64> {
        let millis = timeout.as_millis() as usize;
        with_ffi_error("tick", |e| self.inner.pin_mut().Tick(millis, e))
    }

    /// Advances the simulation by one tick (synchronous mode only).
    ///
    /// Uses the default timeout of 60 seconds.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.tick](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.tick)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.tick](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.tick)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.tick](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.tick)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn tick(&mut self) -> crate::Result<u64> {
        self.tick_or_timeout(DEFAULT_TICK_TIMEOUT)
    }

    /// Sets the percentage of pedestrians that will cross roads.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.set_pedestrians_cross_factor](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.set_pedestrians_cross_factor)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.set_pedestrians_cross_factor](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.set_pedestrians_cross_factor)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.set_pedestrians_cross_factor](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.set_pedestrians_cross_factor)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Arguments
    ///
    /// * `percentage` - Value from 0.0 to 1.0 (0% to 100%)
    pub fn set_pedestrians_cross_factor(&mut self, percentage: f32) -> crate::Result<()> {
        with_ffi_error("set_pedestrians_cross_factor", |e| {
            self.inner
                .pin_mut()
                .SetPedestriansCrossFactor(percentage, e)
        })
    }

    /// Sets the random seed for pedestrian behavior.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.set_pedestrians_seed](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.set_pedestrians_seed)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.set_pedestrians_seed](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.set_pedestrians_seed)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.set_pedestrians_seed](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.set_pedestrians_seed)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn set_pedestrians_seed(&mut self, seed: usize) -> crate::Result<()> {
        let seed = c_uint(seed as std::os::raw::c_uint);
        with_ffi_error("set_pedestrians_seed", |e| {
            self.inner.pin_mut().SetPedestriansSeed(seed, e)
        })
    }

    /// Returns the traffic sign actor at the given landmark location.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_traffic_sign](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_traffic_sign)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_traffic_sign](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_traffic_sign)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_traffic_sign](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_traffic_sign)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn traffic_sign_at(&self, landmark: &Landmark) -> crate::Result<Option<Actor>> {
        // SAFETY: Landmark.inner is guaranteed non-null (see landmark.rs from_cxx())
        let ptr = with_ffi_error("traffic_sign_at", |e| {
            self.inner
                .GetTrafficSign(unsafe { landmark.inner.as_ref().unwrap_unchecked() }, e)
        })?;
        Ok(Actor::from_cxx(ptr))
    }

    /// Returns the traffic light actor at the given landmark location.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_traffic_light](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_traffic_light)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_traffic_light](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_traffic_light)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_traffic_light](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_traffic_light)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn traffic_light_at(&self, landmark: &Landmark) -> crate::Result<Option<Actor>> {
        // SAFETY: Landmark.inner is guaranteed non-null (see landmark.rs from_cxx())
        let ptr = with_ffi_error("traffic_light_at", |e| {
            self.inner
                .GetTrafficLight(unsafe { landmark.inner.as_ref().unwrap_unchecked() }, e)
        })?;
        Ok(Actor::from_cxx(ptr))
    }

    /// Returns the traffic light actor with the given OpenDRIVE sign ID.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_traffic_light_from_opendrive](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_traffic_light_from_opendrive)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_traffic_light_from_opendrive](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_traffic_light_from_opendrive)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_traffic_light_from_opendrive](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_traffic_light_from_opendrive)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn traffic_light_from_open_drive(&self, sign_id: &str) -> crate::Result<Option<Actor>> {
        let_cxx_string!(sign_id = sign_id);
        let ptr = with_ffi_error("traffic_light_from_open_drive", |e| {
            self.inner.GetTrafficLightFromOpenDRIVE(&sign_id, e)
        })?;
        Ok(Actor::from_cxx(ptr))
    }

    /// Freezes or unfreezes all traffic lights in the world.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.freeze_all_traffic_lights](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.freeze_all_traffic_lights)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.freeze_all_traffic_lights](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.freeze_all_traffic_lights)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.freeze_all_traffic_lights](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.freeze_all_traffic_lights)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn freeze_all_traffic_lights(&mut self, frozen: bool) -> crate::Result<()> {
        with_ffi_error("freeze_all_traffic_lights", |e| {
            self.inner.pin_mut().FreezeAllTrafficLights(frozen, e)
        })
    }

    /// Resets all traffic lights to their initial state.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.reset_all_traffic_lights](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.reset_all_traffic_lights)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.reset_all_traffic_lights](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.reset_all_traffic_lights)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.reset_all_traffic_lights](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.reset_all_traffic_lights)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn reset_all_traffic_lights(&mut self) -> crate::Result<()> {
        with_ffi_error("reset_all_traffic_lights", |e| {
            self.inner.pin_mut().ResetAllTrafficLights(e)
        })
    }

    /// Returns bounding boxes for environment objects matching the queried tag.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_level_bbs](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_level_bbs)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_level_bbs](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_level_bbs)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_level_bbs](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_level_bbs)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn level_bounding_boxes(&self, queried_tag: u8) -> crate::Result<BoundingBoxList> {
        let ptr = with_ffi_error("level_bounding_boxes", |e| {
            self.inner.GetLevelBBs(queried_tag, e)
        })?;
        Ok(unsafe { BoundingBoxList::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Returns the current weather parameters.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_weather](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_weather)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_weather](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_weather)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_weather](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_weather)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn weather(&self) -> crate::Result<WeatherParameters> {
        with_ffi_error("weather", |e| self.inner.GetWeather(e))
    }

    /// Sets the weather parameters (sun, clouds, precipitation, fog, etc.).
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.set_weather](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.set_weather)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.set_weather](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.set_weather)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.set_weather](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.set_weather)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use carla::{client::Client, rpc::WeatherParameters};
    ///
    /// let client = Client::connect("localhost", 2000, None)?;
    /// let mut world = client.world()?;
    ///
    /// let mut weather = world.weather()?;
    /// weather.cloudiness = 80.0;
    /// weather.precipitation = 50.0;
    /// world.set_weather(&weather)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_weather(&mut self, weather: &WeatherParameters) -> crate::Result<()> {
        with_ffi_error("set_weather", |e| {
            self.inner.pin_mut().SetWeather(weather, e)
        })
    }

    /// Returns whether weather simulation is enabled.
    ///
    /// **Available in CARLA 0.10.0+**
    #[cfg(carla_0100)]
    pub fn is_weather_enabled(&self) -> crate::Result<bool> {
        with_ffi_error("is_weather_enabled", |e| self.inner.IsWeatherEnabled(e))
    }

    /// Returns environment objects matching the queried tag.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.get_environment_objects](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.get_environment_objects)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.get_environment_objects](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.get_environment_objects)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.get_environment_objects](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.get_environment_objects)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn environment_objects(&self, queried_tag: u8) -> crate::Result<EnvironmentObjectList> {
        let ptr = with_ffi_error("environment_objects", |e| {
            self.inner.GetEnvironmentObjects(queried_tag, e)
        })?;
        Ok(unsafe { EnvironmentObjectList::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Enables or disables environment objects by their IDs.
    #[cfg_attr(
        carla_version_0916,
        doc = " See [carla.World.enable_environment_objects](https://carla.readthedocs.io/en/0.9.16/python_api/#carla.World.enable_environment_objects)"
    )]
    #[cfg_attr(
        carla_version_0915,
        doc = " See [carla.World.enable_environment_objects](https://carla.readthedocs.io/en/0.9.15/python_api/#carla.World.enable_environment_objects)"
    )]
    #[cfg_attr(
        carla_version_0914,
        doc = " See [carla.World.enable_environment_objects](https://carla.readthedocs.io/en/0.9.14/python_api/#carla.World.enable_environment_objects)"
    )]
    #[cfg_attr(
        any(carla_version_0916, carla_version_0915, carla_version_0914),
        doc = " in the Python API."
    )]
    pub fn enable_environment_objects(&self, ids: &[u64], enable: bool) -> crate::Result<()> {
        let ptr = ids.as_ptr();
        let len = ids.len();
        with_ffi_error("enable_environment_objects", |e| unsafe {
            self.inner.EnableEnvironmentObjects(ptr, len, enable, e)
        })
    }

    pub fn project_point(
        &self,
        location: &Location,
        direction: &Vector3D,
        search_distance: f32,
    ) -> crate::Result<Option<LabelledPoint>> {
        // SAFETY: FfiVector3D and carla::geom::Vector3D have identical memory layout
        let cpp_dir = unsafe {
            std::mem::transmute::<FfiVector3D, carla_sys::carla::geom::Vector3D>(
                direction.into_ffi(),
            )
        };
        let ptr = with_ffi_error("project_point", |e| {
            self.inner
                .ProjectPoint(location.into_ffi(), cpp_dir, search_distance, e)
        })?;

        if ptr.is_null() {
            Ok(None)
        } else {
            Ok(Some((*ptr).clone()))
        }
    }

    pub fn ground_projection(
        &self,
        location: &Location,
        search_distance: f32,
    ) -> crate::Result<Option<LabelledPoint>> {
        let ptr = with_ffi_error("ground_projection", |e| {
            self.inner
                .GroundProjection(location.into_ffi(), search_distance, e)
        })?;

        if ptr.is_null() {
            Ok(None)
        } else {
            Ok(Some((*ptr).clone()))
        }
    }

    pub fn cast_ray(&self, start: &Location, end: &Location) -> crate::Result<LabelledPointList> {
        let ptr = with_ffi_error("cast_ray", |e| {
            self.inner.CastRay(start.into_ffi(), end.into_ffi(), e)
        })?;
        Ok(unsafe { LabelledPointList::from_cxx(ptr).unwrap_unchecked() })
    }

    /// Creates a debug helper for drawing visualization primitives.
    ///
    /// Returns a [`DebugHelper`] that can be used to draw points, lines, boxes, arrows,
    /// and text in the simulation for debugging and visualization purposes.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use carla::client::Client;
    /// # use carla::geom::Location;
    /// # use carla::rpc::Color;
    /// #
    /// # let mut client = Client::connect("localhost", 2000, None).unwrap();
    /// # let mut world = client.world();
    /// let mut debug = world.debug();
    ///
    /// // Draw a red point at the origin
    /// debug.draw_point(Location::new(0.0, 0.0, 0.0), 0.5, Color::RED, 5.0, false);
    /// ```
    pub fn debug(&mut self) -> crate::Result<DebugHelper> {
        let ptr = with_ffi_error("debug", |e| self.inner.pin_mut().MakeDebugHelper(e))?;
        Ok(DebugHelper { inner: ptr })
    }

    /// Applies a color texture to a single object by name.
    ///
    /// **Available in CARLA 0.10.0+**
    #[cfg(carla_0100)]
    pub fn apply_color_texture_to_object(
        &mut self,
        object_name: &str,
        parameter: MaterialParameter,
        texture: &TextureColor,
    ) -> crate::Result<()> {
        let_cxx_string!(name = object_name);
        with_ffi_error("apply_color_texture_to_object", |e| {
            self.inner.pin_mut().ApplyColorTextureToObject(
                &name,
                parameter.as_u8(),
                &texture.inner,
                e,
            )
        })
    }

    /// Applies a float color texture to a single object by name.
    ///
    /// **Available in CARLA 0.10.0+**
    #[cfg(carla_0100)]
    pub fn apply_float_color_texture_to_object(
        &mut self,
        object_name: &str,
        parameter: MaterialParameter,
        texture: &TextureFloatColor,
    ) -> crate::Result<()> {
        let_cxx_string!(name = object_name);
        with_ffi_error("apply_float_color_texture_to_object", |e| {
            self.inner.pin_mut().ApplyFloatColorTextureToObject(
                &name,
                parameter.as_u8(),
                &texture.inner,
                e,
            )
        })
    }

    /// Applies a full set of textures (diffuse, emissive, normal, AO/roughness/metallic/emissive)
    /// to a single object by name.
    ///
    /// **Available in CARLA 0.10.0+**
    #[cfg(carla_0100)]
    pub fn apply_textures_to_object(
        &mut self,
        object_name: &str,
        diffuse: &TextureColor,
        emissive: &TextureFloatColor,
        normal: &TextureFloatColor,
        ao_roughness_metallic_emissive: &TextureFloatColor,
    ) -> crate::Result<()> {
        let_cxx_string!(name = object_name);
        with_ffi_error("apply_textures_to_object", |e| {
            self.inner.pin_mut().ApplyTexturesToObject(
                &name,
                &diffuse.inner,
                &emissive.inner,
                &normal.inner,
                &ao_roughness_metallic_emissive.inner,
                e,
            )
        })
    }

    /// Registers a callback to be called on every world tick.
    ///
    /// The callback receives a [`WorldSnapshot`] capturing the state of all
    /// actors at that tick.
    ///
    /// Returns an [`OnTickId`] that can be passed to [`remove_on_tick`](Self::remove_on_tick)
    /// to unregister the callback.
    pub fn on_tick<F>(&mut self, mut callback: F) -> crate::Result<OnTickId>
    where
        F: FnMut(WorldSnapshot) + Send + 'static,
    {
        with_ffi_error("on_tick", |e| unsafe {
            let fn_ptr = {
                let fn_ = move |ptr: UniquePtr<FfiWorldSnapshot>| {
                    if let Some(snapshot) = WorldSnapshot::from_cxx(ptr) {
                        (callback)(snapshot);
                    }
                };
                let fn_: Box<OnTickCb> = Box::new(fn_);
                let fn_ = Box::new(fn_);
                let fn_: *mut Box<OnTickCb> = Box::into_raw(fn_);
                fn_ as *mut c_void
            };

            let caller_ptr = on_tick_caller as *mut c_void;
            let deleter_ptr = on_tick_deleter as *mut c_void;

            OnTickId(
                self.inner
                    .pin_mut()
                    .OnTick(caller_ptr, fn_ptr, deleter_ptr, e),
            )
        })
    }

    /// Removes a previously registered on-tick callback.
    ///
    /// # Arguments
    ///
    /// * `id` - The [`OnTickId`] returned by [`on_tick`](Self::on_tick)
    pub fn remove_on_tick(&mut self, id: OnTickId) -> crate::Result<()> {
        with_ffi_error("remove_on_tick", |e| {
            self.inner.pin_mut().RemoveOnTick(id.0, e);
        })
    }

    pub(crate) fn from_cxx(ptr: UniquePtr<FfiWorld>) -> Option<World> {
        if ptr.is_null() {
            None
        } else {
            Some(Self { inner: ptr })
        }
    }
}

impl Clone for World {
    fn clone(&self) -> Self {
        let ptr =
            with_ffi_error("World::clone", |e| self.inner.clone(e)).expect("World::clone failed");
        unsafe { Self::from_cxx(ptr).unwrap_unchecked() }
    }
}

/// Identifier for an on-tick callback, returned by [`World::on_tick`].
///
/// Pass this to [`World::remove_on_tick`] to unregister the callback.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct OnTickId(usize);

type OnTickCb = dyn FnMut(UniquePtr<FfiWorldSnapshot>) + Send + 'static;

unsafe extern "C" fn on_tick_caller(fn_: *mut c_void, arg: *mut FfiWorldSnapshot) {
    if fn_.is_null() || arg.is_null() {
        eprintln!(
            "ERROR: Null pointer in on_tick callback - fn_: {:p}, arg: {:p}",
            fn_, arg
        );
        return;
    }

    let fn_ = fn_ as *mut Box<OnTickCb>;
    unsafe {
        // Take ownership of the heap-allocated FfiWorldSnapshot from C++
        let snapshot = UniquePtr::from_raw(arg);
        (*fn_)(snapshot);
    }
}

unsafe extern "C" fn on_tick_deleter(fn_: *mut c_void) {
    if fn_.is_null() {
        eprintln!("ERROR: Null pointer in on_tick deleter");
        return;
    }

    let fn_ = fn_ as *mut Box<OnTickCb>;
    let fn_: Box<Box<OnTickCb>> = unsafe { Box::from_raw(fn_) };
    mem::drop(fn_);
}

assert_impl_all!(World: Sync, Send);