4、Python API入门：连接CARLA服务器、获取世界对象、生成车辆与行人、控制Actor运动

好，咱们正式开始动手了。

前面几章我们把CARLA的架构、环境搭建、联合仿真流程都捋了一遍。说实话，光看理论容易犯困。我个人习惯是，先让代码跑起来，看到车在动、人在走，心里才踏实。

这一章，我们就来写第一段真正的Python脚本。目标很明确：连上CARLA服务器，拿到世界，往里面扔几辆车和几个行人，然后让他们动起来。

4.1 连接CARLA服务器

CARLA采用客户端-服务器架构。你的Python脚本就是客户端，它通过TCP连接到CARLA服务器（也就是你启动的CARLA程序）。

连接代码其实就一行：

import carla

# 连接到本地服务器，默认端口是2000
client = carla.Client('localhost', 2000)
client.set_timeout(10.0)  # 设置超时时间，单位秒

这里有个坑，我一开始就踩过。set_timeout 一定要设。如果不设，默认超时时间很短，网络稍微波动一下，连接就断了。我曾经在调试一个复杂场景时，脚本跑了一半突然报超时错误，排查了半天才发现是没设超时。

连接成功后，我们可以获取客户端支持的世界列表：

world_list = client.get_available_maps()
print(world_list)

你会看到一堆地图名字，比如 Town01、Town02 等等。每个地图就是一个仿真世界。

4.2 获取世界对象

有了客户端，下一步就是获取世界对象。世界对象是CARLA仿真环境的核心，它管理着地图、天气、Actor（车辆、行人、传感器等）所有东西。

# 加载指定地图
world = client.load_world('Town01')

# 或者直接获取当前已经加载的世界
world = client.get_world()

我个人建议用 load_world，因为你可以明确指定要加载哪个地图。用 get_world 的话，如果服务器还没加载地图，会返回空。

拿到世界对象后，你可以做很多事情。比如设置天气：

weather = carla.WeatherParameters(
    cloudiness=30.0,
    precipitation=0.0,
    sun_altitude_angle=70.0
)
world.set_weather(weather)

嗯，这里要注意，天气参数是实时生效的。你可以在仿真过程中动态调整，模拟白天、黑夜、雨天等不同场景。

4.3 生成车辆与行人

这是最激动人心的部分。我们要往世界里塞东西了。

4.3.1 生成车辆

生成车辆需要三步：获取蓝图、选择生成点、生成。

# 获取蓝图库
blueprint_library = world.get_blueprint_library()

# 选择一辆车，比如奥迪A2
vehicle_bp = blueprint_library.find('vehicle.audi.a2')

# 获取一个随机生成点
spawn_points = world.get_map().get_spawn_points()
spawn_point = spawn_points[0]  # 取第一个生成点

# 生成车辆
vehicle = world.spawn_actor(vehicle_bp, spawn_point)

这里有个细节：生成点 是地图预定义的。每个地图都有几十个甚至上百个生成点，分布在道路两侧。你可以用 get_spawn_points() 获取所有生成点。

生成多个车辆也很简单，循环就行：

vehicles = []
for i in range(10):
    bp = blueprint_library.filter('vehicle.*')[i]  # 取前10种不同的车
    spawn_point = spawn_points[i % len(spawn_points)]
    v = world.spawn_actor(bp, spawn_point)
    vehicles.append(v)

4.3.2 生成行人

行人的生成逻辑类似，但要注意：行人蓝图在 walker.pedestrian.* 下面。

# 获取行人蓝图
walker_bp = blueprint_library.find('walker.pedestrian.0001')

# 行人需要设置位置，通常在人行道上
walker_transform = carla.Transform(carla.Location(x=50, y=100, z=0.5))

# 生成行人
walker = world.spawn_actor(walker_bp, walker_transform)

行人生成后，默认是静止的。要让他们动起来，需要用到 行人控制器。这个我们下一节讲。

4.4 控制Actor运动

Actor生成后，怎么让他们动起来？两种方式：手动控制 和 自动控制。

4.4.1 控制车辆运动

最简单的方式是给车辆一个速度：

vehicle.set_velocity(carla.Vector3D(x=10, y=0, z=0))  # 向前以10m/s行驶

但这样太粗暴了。更真实的方式是控制油门、刹车、方向盘：

# 创建一个控制命令
control = carla.VehicleControl()
control.throttle = 0.5   # 油门 50%
control.steer = 0.0      # 方向盘回正
control.brake = 0.0      # 不刹车

# 应用控制
vehicle.apply_control(control)

你可以在循环中不断更新控制命令，实现加速、转弯、刹车等操作。

如果想省事，可以用CARLA自带的 自动驾驶模式：

vehicle.set_autopilot(True)

开启后，车辆会按照交通规则自动行驶。我在做基础测试时经常用这个模式，省得自己写控制逻辑。

4.4.2 控制行人运动

行人控制稍微复杂一点。需要先获取行人控制器：

# 生成行人控制器蓝图
walker_controller_bp = blueprint_library.find('controller.ai.walker')

# 生成控制器，并关联到行人
walker_controller = world.spawn_actor(walker_controller_bp, carla.Transform(), attach_to=walker)

# 启动控制器
walker_controller.start()
walker_controller.go_to_location(carla.Location(x=100, y=100, z=0.5))

控制器会让行人自动导航到目标位置。你也可以设置行人的行走速度：

walker_controller.set_max_speed(1.5)  # 1.5 m/s，大约相当于正常步行速度

4.5 完整示例：生成一辆车并让它跑起来

把上面的知识点串起来，写一个完整的脚本：

import carla
import time

# 连接服务器
client = carla.Client('localhost', 2000)
client.set_timeout(10.0)

# 加载世界
world = client.load_world('Town01')

# 获取蓝图
blueprint_library = world.get_blueprint_library()
vehicle_bp = blueprint_library.find('vehicle.audi.a2')

# 获取生成点
spawn_points = world.get_map().get_spawn_points()
spawn_point = spawn_points[0]

# 生成车辆
vehicle = world.spawn_actor(vehicle_bp, spawn_point)
print(f'车辆已生成，ID: {vehicle.id}')

# 开启自动驾驶
vehicle.set_autopilot(True)

# 让仿真运行10秒
time.sleep(10)

# 销毁车辆
vehicle.destroy()
print('车辆已销毁')

这个脚本虽然简单，但涵盖了连接、加载、生成、控制、销毁的完整流程。你想想看，从零到让一辆车在虚拟世界里跑起来，是不是挺有成就感的？

4.6 本章知识体系

为了让你更直观地理解本章的核心逻辑，我画了一张流程图：

这张图把本章的四个步骤串起来了。你照着这个流程写代码，基本不会出错。

4.7 避坑指南

最后，分享几个我实际项目中遇到的坑：

• 连接超时： 服务器没启动，或者端口不对。检查一下 ./CarlaUE4.sh 是否在运行。
• 生成失败： 生成点被占用。用 try_spawn_actor 替代 spawn_actor，并检查返回值。
• 行人不动： 忘了调用 start()。控制器必须启动才能工作。
• 车辆失控： 同时用了 apply_control 和 set_autopilot，两者会冲突。选一种方式即可。
• 内存泄漏： Actor用完后记得 destroy()。尤其是行人控制器，不销毁的话，下次生成会报错。

嗯，这一章的内容就到这里。代码不多，但都是基础中的基础。把这些练熟了，后面我们才能玩更高级的东西。