SimWorld API 参考手册：Communicator 常用接口与 UE 命令速查清单

SimWorld 是一个面向物理世界与社会世界的开放式高保真智能体模拟器。本文系统梳理 SimWorld 中 Communicator 模块的常用 API 与底层 UE 命令（UnrealCV+）速查清单，帮助你快速掌握如何连接 Unreal Engine 后端、生成世界、控制车辆/行人/信号灯、获取相机与传感器观测，是编写智能体训练与评测脚本时的实用接口指南。

一、通信架构：先看懂 Communicator 的双层设计

在查阅 API 之前，先理解 SimWorld 的通信架构，能帮助你快速定位"该调哪一层方法"：

• UnrealCV（底层客户端）：通过 TCP 连接 UE 服务端的 9000 端口，发送 vset / vget / vbp / vrun 等命令，负责最细粒度的对象操作与图像获取；
• Communicator（高层接口）：封装了车辆、行人、信号灯、人形智能体的 ID→名称映射，提供批量更新、世界生成、环境清理等"开箱即用"的能力。

UE 服务端内部由 Parser（解析器）+ Executor（执行器） 组成，Python 端每发出一条命令（如 vset /object/location），服务端解析后即时执行，从而实现逻辑计算与渲染的解耦。

核心源码位置：

• 高层接口：simworld/communicator/communicator.py
• 底层客户端：simworld/communicator/unrealcv.py
• 官方文档：docs/source/components/unrealcv+.rst、docs/source/components/ue_detail.rst

二、建立连接：3 步接入 UE 后端

from simworld.communicator.unrealcv import UnrealCV
from simworld.communicator.communicator import Communicator

ucv = UnrealCV(port=9000, ip='127.0.0.1', resolution=(1280, 720))
communicator = Communicator(ucv)

要点说明：

参数/行为	说明
port=9000	UnrealCV 默认端口，UE 端需先点击 Play 进入运行状态
resolution	连接后自动执行 vrun setres WxH 设置渲染分辨率
check_connection()	断连时每 1 秒自动重连，无需手动处理

💡 完整交互示例可参考 examples/ue_command.ipynb，其中演示了相机、机器狗、人形智能体、滑板车等对象的全套命令调用。

三、对象管理 API 速查表：Spawn、Transform、Destroy

这是日常使用频率最高的一组接口。下表列出常用 Python 方法与其底层 UE 命令的对应关系：

用途	Python 方法	对应 UE 命令
生成蓝图对象	ucv.spawn_bp_asset(prefab_path, name)	vset /objects/spawn_bp_asset {path} {name}
设置位置	ucv.set_location((x, y, z), name)	vset /object/{name}/location
设置朝向	ucv.set_orientation((p, y, r), name)	vset /object/{name}/rotation
设置缩放	ucv.set_scale((x, y, z), name)	vset /object/{name}/scale
设置颜色	ucv.set_color(name, [R, G, B])	vset /object/{name}/color
碰撞开关	ucv.set_collision(name, True)	vset /object/{name}/collision
可移动开关	ucv.set_movable(name, True)	vset /object/{name}/object_mobility
物理开关	ucv.set_physics(name, True)	vset /object/{name}/physics
销毁对象	ucv.destroy(name)	vset /object/{name}/destroy
列出全部对象	ucv.get_objects()	vget /objects
重命名对象	ucv.set_object_name(name, new_name)	vset /object/{name}/name

高层封装（推荐优先使用）：Communicator 把"生成 + 定位 + 定朝向 + 碰撞设置"打包成一步：

方法	作用
communicator.generate_world(world_json, ue_asset_path)	读取 data/progen_world.json 格式的布局，批量重建整座城市
communicator.spawn_agent(agent, model_path, type)	生成人形智能体（默认路径 Base_User_Agent）
communicator.spawn_vehicles(vehicles) / spawn_pedestrians(pedestrians)	批量生成车辆 / 行人
communicator.spawn_scooter(scooter, model_path)	生成滑板车
communicator.spawn_traffic_signals(traffic_signals)	按 type 自动选择车行灯 / 行人灯模型
communicator.spawn_ue_manager(ue_manager_path)	生成 UE Manager（批量状态更新必须）
communicator.clear_env(keep_roads=True)	一键清理所有 GEN_BP_ 前缀对象并重置 ID 计数器

四、交通管制 API：车辆、行人与信号灯

交通对象在 UE 中的命名有固定规则（由 Communicator 自动完成 ID→名称映射），排查问题时务必记住这些前缀：

• 车辆：GEN_BP_Vehicle_{id}
• 行人：GEN_BP_Pedestrian_{id}
• 人形智能体：GEN_BP_Humanoid_{id}
• 信号灯：GEN_BP_TrafficSignal_{id}
• 滑板车：GEN_BP_Scooter_{id}

车辆与行人控制：

用途	方法	对应 UE 命令
单车控制	communicator.update_vehicle(id, throttle, brake, steering)	vbp {name} SetState {throttle} {brake} {steering}
批量车辆控制	communicator.update_vehicles(states)	vbp {manager} VSetState {批量串}
掉头	communicator.vehicle_make_u_turn(id)	vbp {name} MakeUTurn
行人前进/停止	communicator.pedestrian_move_forward(id) / pedestrian_stop(id)	vbp {name} MoveForward / StopPedestrian
行人转向/限速	pedestrian_rotate(id, angle, direction) / set_pedestrian_speed(id, speed)	vbp {name} Rotate_Angle / SetMaxSpeed
设置行人路径	communicator.p_set_waypoints(id, waypoints)	vbp {name} SetWaypoints（格式 x,y;x,y）
批量读取状态	communicator.get_position_and_direction(...)	vbp {manager} GetInformation

信号灯控制：

用途	方法	对应 UE 命令
车辆放行	traffic_signal_switch_to(id, 'green')	vbp {name} SwitchVehicleFrontGreen
行人通行	traffic_signal_switch_to(id, 'pedestrian walk')	vbp {name} SetPedestrianWalk
配时设置	traffic_signal_set_duration(id, green, yellow, ped_green)	vbp {name} SetDuration
路口开始仿真	communicator.traffic_signal_start_simulation(intersection)	vbp {intersection} StartSimulation

信号灯配时参数可在 config/example.yaml 的 traffic.traffic_signal 段落中调整（默认绿 10s / 黄 2s / 行人 30s）。

人形智能体（Humanoid）扩展动作（直接调用 ucv 层）：humanoid_move_forward、humanoid_stop、humanoid_step_forward、humanoid_sit_down / humanoid_stand_up、humanoid_pick_up_object / humanoid_drop_object、humanoid_enter_vehicle / humanoid_exit_vehicle、humanoid_discuss / humanoid_argue / humanoid_listen。多数交互动作会返回 JSON 中的 Success 字段用于判断成败。

五、相机与传感器观测：三种 viewmode 全覆盖

获取观测图像只需一行调用，viewmode 决定图像类型：

viewmode	输出内容	典型用途
lit	彩色 RGB 图像（PNG 编码）	视觉策略输入
depth	深度图（NPY 编码，自动伪彩色化）	距离感知 / SLAM
object_mask	实例分割掩码	检测与识别监督

常用方法速查：

方法	作用
communicator.get_camera_observation(cam_id, viewmode)	获取单相机图像（mode 可选 direct/fast/file）
communicator.get_camera_observation_multicam(cam_ids, viewmode)	多相机批量取图
ucv.get_cameras()	列出场景中所有相机 ID
ucv.set_camera_location / rotation / fov / resolution	调整相机位姿、视场角与分辨率
ucv.get_camera_location / rotation / fov / resolution	查询相机当前参数
ucv.show_img(image)	在 Notebook 中即时预览（深度图自动归一化）

💡 需要高频取图时可将 mode 改为 fast（BMP 解码更快）或 file（落盘后读取）。

六、进阶：同步/异步模式与天气控制

同步/异步模式（同步模式保证确定性，适合强化学习评测）：

ucv.set_mode('sync', tick_interval=0.05)  # 暂停并设置 tick 间隔
ucv.tick()                               # 推进一个仿真步
ucv.set_mode('async')                    # 恢复自由运行
ucv.set_fps(30)                          # 固定帧率

天气接口（作用于 GEN_WeatherManager，见 simworld/weather/weather_manager.py）：

方法	参数范围
communicator.set_sun_direction(name, pitch, yaw)	pitch ∈ [-89, 89]，yaw ∈ [0, 360]
communicator.get_sun_direction(name)	返回 (pitch, yaw) 元组
communicator.get_sun_intensity(name)	返回光照强度
ucv.set_fog(name, density, distance, falloff)	density 0-100 / distance 0-5000cm / falloff 0-2
ucv.set_atmosphere(name, rayleigh, mie)	rayleigh 0-2 / mie 0-5

七、常见问题排查清单

现象	排查方向
一直提示 UnrealCV server is not running	UE 端未点击 Play；端口被占用；防火墙拦截 9000 端口
命令无响应、对象未出现	确认对象名带 GEN_BP_ 前缀与 ID 一致；先生成 UE_Manager 再调用批量接口
GetInformation 解析为空	车辆/行人未 spawn 或已被 clear_env 销毁
深度图发黑	depth 视图走 NPY 通道，确认 viewmode 拼写正确

八、参考资料导航

• API 总览文档：docs/source/components/unrealcv+.rst
• UE 后端与传感器细节：docs/source/components/ue_detail.rst
• 交通系统说明：docs/source/components/traffic_system.rst
• 命令交互完整示例：examples/ue_command.ipynb、examples/camera.ipynb
• 全局配置模板：config/example.yaml

掌握以上两层接口与命令对照关系后，你就可以自由组合"生成世界 → 放置智能体 → 控制交通 → 采集观测"的完整链路，开始自己的智能体实验了。