carla-simulator/carla-agentic-tools/control-spectator

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.