Control the CARLA spectator
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.
Aim the on-screen camera (the "spectator"). Move it to a pose, frame an actor in
a preset view, or follow a moving actor. The spectator cannot be attached to
an actor (the API has no reparent for it) — following is emulated by re-setting
its transform every world tick.
Resolving the target from words
Like the other skills, this emits structured data (actors) and the agent
filters it:
- "the ego" →
--role hero (CARLA's ego role_name is usually hero).
- "the Toyota Prius" →
--filter '*prius*' (or vehicle.toyota.prius).
- a specific one →
--id N.
"3rd-person view of the ego" → follow --view chase --role hero. "1st-person of
the prius" → follow --view first --filter '*prius*'. On multiple matches it
picks the nearest and says so — run actors first if you need to choose.
Instructions
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Resolve the target (actors) if the request names an actor
- [ ] Step 3: move / look (one-shot) / follow (live) in the requested view
Commands need CARLA_HOST/CARLA_PORT from scripts/env.sh. Only useful on a
rendered server (windowed or packaged) — the spectator is that window's camera.
Negative coordinates: pass move --at with an = (--at=-24,-57,20) so the
leading minus isn't parsed as a flag.
Step 1: Check prerequisites
bash scripts/check_env.sh
Step 2-3: Aim it
source scripts/env.sh
# list actors to resolve a name
python3 scripts/spectator.py actors
python3 scripts/spectator.py actors --filter '*prius*'
# move to an explicit pose (looking slightly down)
python3 scripts/spectator.py move --at 40,20,15 --pitch -30 --yaw 90
# one-shot framing (no loop): chase view of the ego
python3 scripts/spectator.py look --view chase --role hero
# live follow for 30s: 1st-person of the prius
python3 scripts/spectator.py follow --view first --filter '*prius*' --seconds 30
# bird's-eye follow of actor 87
python3 scripts/spectator.py follow --view top --id 87 --seconds 20
Views: chase (3rd-person behind+above), first (driver), top (bird's eye),
front (ahead, looking back). Tune with --distance/--height/--pitch.
Examples
Example 1: 3rd-person of the ego
User says: "give me a 3rd-person view of the ego"
follow --view chase --role hero --seconds 30. The camera chases the hero from
behind and above.
Example 2: 1st-person of a named car
User says: "1st-person view of the Toyota Prius"
follow --view first --filter '*prius*'. If several Priuses exist it uses the
nearest and reports the id; run actors --filter '*prius*' to pick a specific one.
Example 3: park the camera and look at a spot
User says: "look at the crossroads at (42,24)"
move --at 42,54,20 --pitch -35 --yaw -90 (offset back from the point and angle
down), or look at a nearby actor.
Troubleshooting
Problem: nothing changes on screen
Cause: headless -nullrhi server (no window), or you're viewing a different
client's camera.
Solution: use a windowed/packaged server; the spectator is that view.
Problem: follow doesn't track in sync mode
Cause: it updates on world ticks; in sync mode nothing ticks unless a client does.
Solution: run the tick loop (set-world-settings), or follow in async mode.
Problem: "can I attach the spectator to the car?"
Answer: not directly — the API can't reparent the spectator. follow gives the
same effect by updating its transform each tick. For a recorded/attached camera,
spawn a camera sensor with SpringArm attachment (create-sensor skill).
Problem: wrong actor chosen
Cause: several actors matched the selector.
Solution: run actors and pass --id, or narrow --filter.
Outputs
Server-side camera state (the on-screen view). follow runs for --seconds then
stops cleanly. No file produced.
Detail (view math, attachment vs following, selector semantics, sync-mode) in
references/spectator.md.