Spawn autopilot vehicles
Paths. scripts/… and references/… below are relative to the
directory holding this SKILL.md. Your working directory is the user's
project, not that directory, so prefix them with its absolute path or the
command is not found.
Populate the roads with self-driving traffic. Vehicles are placed at the map's
predefined spawn points and, by default, handed to the Traffic Manager
autopilot at spawn time so they drive the road network autonomously. destroy
removes them.
spawn and line make the world synchronous. The Traffic Manager is not
reliable driving an asynchronous server: it runs its own loop against a server
advancing at whatever rate it likes. Measured on 0.10.0, async, 50 autopilot
vehicles with the spawning client alive and holding the TM: only 24 were
moving, and the actor count decayed on its own — 50 vehicles down to 39 and 15
walkers down to 5 over a couple of minutes. With a fixed timestep and the TM in
sync, 37 of 50 move and nothing decays. --no-sync keeps the old behaviour.
The TM cannot be driven by another client's tick
The Traffic Manager steps only when the process that created it ticks the
world. Measured on 0.10.0: with a camera client owning a 20 Hz clock and this
skill attached as an observer, its 40 vehicles never moved at all — no error,
just a frozen scene. So a held traffic pool and a lock-step frame capture
cannot share a world; record the traffic here and replay it into the capture
instead ([[read-sensor]] has the recipe).
The clock rule
The world settings are read before anything else happens:
- asynchronous — this client switches it to synchronous (
--delta, default
0.05 s = 20 Hz), puts the TM in sync, and becomes the ticker.
- already synchronous — another client owns the clock. This one never calls
tick(); it observes with wait_for_tick(). Ticking a world you do not own
silently drops commands — it is what stopped spawn-walkers' start() from
landing.
The previous settings are restored on release, because a synchronous world with
nothing ticking does not advance and looks exactly like a hung server. Stop a
holder with Ctrl+C, never kill -9: the restore is in a finally.
The Traffic Manager lives in the client process that created it. So a
spawn that exits leaves the vehicles registered with a dead TM: they sit at
throttle 0.00 for ever, in async and sync. Pass --hold to keep the TM
open (Ctrl+C releases it, and the vehicles then coast to a stop). Measured on
0.10.0: without --hold, 0/50 vehicles move; with it, 49/50 move.
The same is true of controller.ai.walker in [[spawn-walkers]] — its
controllers stop when their client exits — so a scene with both wants two
resident processes: this one owning the clock, the walker one held as an
observer.
Instructions
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Spawn N vehicles with --hold (the TM dies with the process without it)
- [ ] Step 3: Verify visually / via the world-data skill; spawn reports its count
- [ ] Step 4: Ctrl+C the held process, then destroy when done
Commands need CARLA_HOST/CARLA_PORT/TM_PORT from scripts/env.sh.
Negative coordinates: pass --at with an = (--at=-24,-57,0.6) so the
leading minus isn't parsed as a flag.
Step 1: Check prerequisites
bash scripts/check_env.sh
Step 2-4: Spawn / list / destroy
source scripts/env.sh
# 40 vehicles driving around on autopilot — --hold keeps the TM (and so the
# driving) alive; without it they spawn, then freeze when this command returns.
# The world is put in sync at 20 Hz and this client ticks it.
python3 scripts/vehicles.py spawn --count 40 --hold
# leave the world asynchronous (the old behaviour; the TM misbehaves)
python3 scripts/vehicles.py spawn --count 40 --hold --no-sync
# a different fixed timestep
python3 scripts/vehicles.py spawn --count 40 --hold --delta 0.033
# four-wheeled cars only, reproducible
python3 scripts/vehicles.py spawn --count 30 --safe --seed 42
# only Teslas, parked (no autopilot)
python3 scripts/vehicles.py spawn --count 10 --filter 'vehicle.tesla.*' --no-autopilot
# 5 vehicles in one lane, 15 m apart, starting near (x,y,z)
python3 scripts/vehicles.py line --at 30,20,0 --count 5 --gap 15
# ...as a static queue (no autopilot), laid behind the point
python3 scripts/vehicles.py line --at 30,20,0 --count 5 --gap 15 --no-autopilot --backward
# one hero/ego vehicle (autopilot off) — the anchor for control/sensors/telemetry
python3 scripts/vehicles.py ego --at 30,20,0 # prints its actor id + role=hero
# ...named for ROS 2: publishes TF as "hero" and accepts ROS control commands
python3 scripts/vehicles.py ego --at 30,20,0 --ros-name hero
python3 scripts/vehicles.py destroy # remove all vehicles
python3 scripts/vehicles.py destroy --filter 'vehicle.tesla.*' # a subset (keeps the ego)
Verify
The spawn command reports how many vehicles it created. Count is capped at the
number of spawn points (one vehicle per point); it reports if it capped or if some
spawns failed (occupied points) — both normal. Count/inspect live actors with the
world-data skill.
ROS 2 (ego only)
On a server started with --ros2 ([[run-carla-server]] ROS2=1), only a
vehicle with role_name = hero is registered with the ROS 2 layer — the server
checks that string explicitly. So spawn/line traffic is invisible to ROS and
cannot be driven from it, by design; there is no flag to change that here.
python3 scripts/vehicles.py ego --at=-24,-57,0.6 --ros-name hero
--ros-name / --ros-frame-id / --no-ros-tf set the ros_name /
ros_frame_id / ros_publish_tf blueprint attributes before spawn (they are
read once, at registration — no renaming afterwards). Registering the hero gives
(verified against a live server):
rt/carla/<ros_name>/vehicle_control_cmd — carla_msgs/CarlaEgoVehicleControl.rt/carla/<ros_name>/ackermann_control_cmd — ackermann_msgs/AckermannDriveStamped.
Both appear immediately, as subscriptions (the server is the subscriber).- the topic prefix that sensors attached to it nest under ([[create-sensor]]).
It does not publish its own transform. rt/tf stays absent until a sensor
publishes — CARLA emits sensor→parent transforms only, so the map→vehicle
transform must come from outside (that is what the demo's ego_tf_broadcaster.py
does, [[visualize-ros-rviz]]). ros_publish_tf=false suppresses the sensor-side
transform for that actor; it does not disable a vehicle transform that was never
published.
Unlike sensors, a vehicle needs no enable_for_ros(). Driving it from those
topics: [[control-vehicle]].
Examples
Example 1: fill the roads
User says: "spawn 50 cars driving around"
spawn --count 50 --hold. They drive on autopilot for as long as that command
runs; it reports how many spawned. Drop --hold only if you want them placed
and stationary.
Example 2: reproducible car-only traffic
User says: "same 30 cars every run, no motorbikes"
spawn --count 30 --safe --seed 42.
Example 3: a queue in one lane
User says: "put 5 cars in the same lane on this road, 15 m apart"
Find a point on the road (map-waypoints, or a known location), then
line --at <x,y,z> --count 5 --gap 15. They spawn in-lane 15 m apart and drive
off on autopilot; add --no-autopilot for a stationary queue.
Example 4: clean up
User says: "clear the traffic"
destroy.
Troubleshooting
Problem: fewer vehicles than requested
Cause: count exceeds spawn points, or points were occupied.
Solution: expected; the map has a fixed number of spawn points (one car each).
Problem: vehicles spawn but don't move (throttle stays 0.00)
Cause: most often the spawning process exited, taking its Traffic Manager with
it — the vehicles are enrolled with a TM that no longer exists. Verified on
0.10.0 in both async and sync, and it is not a sync/TM mismatch: forcing the
TM async afterwards changes nothing, because the TM is gone.
Solution: spawn with --hold, or keep your own long-lived client holding
client.get_trafficmanager(<port>). Re-registering set_autopilot from a new
process is not enough on its own. Other causes: --no-autopilot, or a sync
world with nothing calling world.tick() (set-world-settings).
Problem: vehicles jitter / freeze in sync mode
Cause: world sync but TM async (mismatch).
Solution: keep both in sync (set-world-settings couples them; spawn also sets
TM sync). Use the same --tm-port throughout.
Problem: the server appears hung — every client blocks or times out
Cause: the world was left synchronous with nothing ticking, usually because a
holder was kill -9ed instead of interrupted, so its restore never ran.
Solution: set synchronous_mode = False from any client
(set-world-settings), then start over. Note a frozen sync world also hands out
stale snapshots, so get_actors() can come back empty and destroy can report
0 actors — fix the clock before believing either.
Outputs
Live autopilot traffic on the server. No file. destroy removes all vehicles.
Detail (blueprint filtering, spawn-point capping, the autopilot hand-off, TM/sync
interaction, determinism) in references/vehicles.md.