# AGENTS.md

Guidance for any coding agent working in this repository.

## Skills

This repo ships a library of **62 vetted CARLA procedures** under
[`Skills/`](Skills/). Each is a directory containing a `SKILL.md` with YAML
frontmatter (`name`, `description`, `compatibility`, `metadata`), the step-by-step
procedure, and often `scripts/` and `references/` beside it.

**These skills are the source of truth** for building, packaging, cooking,
map/vehicle/asset import, running servers, scenarios and ROS 2, and they cover
most of the commands those tasks need.

### How to use them

1. Match the user's request against the catalogue below.
2. Read that skill's `SKILL.md` in full before acting — each encodes the
   failure modes that make the naive approach fail.
3. Run its `scripts/check_env.sh` (when `metadata.prerequisites` names one)
   before starting.
4. Follow the procedure rather than improvising; the gotchas sections exist
   because those mistakes have already cost someone a day.

Paths (`CARLA_ROOT` and friends) are configured on first need, not up front.
Never guess a path — several CARLA checkouts on one machine is normal and the
wrong one fails slowly. Ask the user, then record the answer.

### Optional: MCP server

[`Util/AgenticTools/`](Util/AgenticTools/) serves the same skills over MCP
(`list_skills`, `read_skill`, `check_prerequisites`, `get_config`,
`set_config`), which adds environment detection and persistent path config.
Project config is in [`.mcp.json`](.mcp.json); clients that read it get the
tools automatically. Agents without MCP should read `Skills/` directly — the
files are the source of truth either way.

## Skill catalogue

### `docs`

- **`audit-carla-docs`** — Finds undocumented and rotting documentation in a CARLA checkout — unreleased features, bindings missing from the API reference, documented API that no longer exists....
- **`document-carla-feature`** — Writes the missing CARLA documentation that the audit found, one category at a time, in CARLA's house style....

### `leaderboard`

- **`create-leaderboard-route`** — Creates and edits CARLA Leaderboard route files — placing waypoints and scenario trigger points interactively from the spectator camera....
- **`package-leaderboard-agent`** — Packages an agent for CARLA Leaderboard submission — builds the docker image with make_docker.sh (plain or ROS variant), checks the four required....
- **`read-leaderboard-results`** — Reads a CARLA Leaderboard results.json — per-route driving score, route completion, infraction penalty and the infraction lists — explains how the....
- **`run-leaderboard-evaluation`** — Runs the CARLA Leaderboard evaluator over a set of routes with your agent — routes/routes-subset/repetitions/track selection, checkpoint and....
- **`write-leaderboard-agent`** — Writes an autonomous agent for the CARLA Leaderboard — an AutonomousAgent subclass with setup/sensors/run_step/destroy, a sensor suite inside the....

### `python-api`

- **`bounding-boxes`** — Gets actor and level 3D bounding boxes and projects them into a camera image as 2D boxes — the dataset-annotation workflow.
- **`control-lights`** — Controls the map's light sources through the CARLA LightManager — turn street lamps, building/facade lights, vehicle lights or all of them on/off,....
- **`control-spectator`** — Moves the CARLA spectator camera, frames an actor, or follows one live — third-person/chase, first-person/driver, top-down, or front views,....
- **`control-traffic`** — Tunes the CARLA Traffic Manager that drives autopilot vehicles — global and per-vehicle speed, following distance, running lights/signs,....
- **`control-traffic-lights`** — Controls the traffic-light actors on a running CARLA server — set a light green/red/yellow/off, freeze all lights (optionally all-green), set....
- **`control-vehicle`** — Directly drives a specific vehicle on a running CARLA server — raw VehicleControl (throttle/steer/brake/reverse/hand-brake), Ackermann speed....
- **`create-sensor`** — Spawns and attaches sensors on a running CARLA server — cameras (rgb/depth/semantic/instance/optical-flow/normals), lidar, radar, IMU, GNSS,....
- **`debug-draw`** — Draws debug overlays in a running CARLA world via world.debug — points, lines, arrows, bounding boxes, and text strings, each with a colour and....
- **`debug-navmesh`** — Visualises and validates a map's pedestrian navigation mesh by sampling walkable locations (get_random_location_from_navigation) and drawing them....
- **`load-map`** — Loads, reloads, and reshapes the map on a running CARLA server via the Python API — get_available_maps, load_world and reload_world (with or....
- **`map-waypoints`** — Explores a CARLA map's road network through the Map/Waypoint API — a natural-language rundown of the whole map ("give me the topology"), drawing....
- **`navigate-to`** — Drives a vehicle to a destination autonomously using CARLA's navigation agents (BasicAgent/BehaviorAgent/ConstantVelocityAgent), or plans a route....
- **`query-recording`** — Inspects a recorded CARLA .log without replaying it — show_recorder_file_info for the header/actors/frames, collision queries between actor....
- **`read-sensor`** — Listens to a CARLA sensor and either saves its data to files, shows it live in a window, prints a one-shot summary, or (ros-info) reports the....
- **`record-simulation`** — Records a running CARLA simulation to a .log file via start_recorder/stop_recorder for later deterministic replay — capturing actor spawns,....
- **`replay-recording`** — Replays a CARLA .log recorded by the recorder — the whole run or a time window, at any speed, following a chosen actor, optionally regenerating....
- **`set-weather`** — Reads and sets the weather on a running CARLA server via get_weather/set_weather, and turns natural-language weather requests ("heavy rain at....
- **`set-world-settings`** — Reads and changes a running CARLA server's WorldSettings via apply_settings — synchronous vs asynchronous mode, fixed_delta_seconds (fps), physics....
- **`spawn-vehicles`** — Spawns vehicles on a running CARLA server and destroys them — scattered across the map's spawn points on Traffic Manager autopilot, a row queued....
- **`spawn-walkers`** — Spawns pedestrians that wander autonomously via WalkerAIController, and destroys them in the correct order.
- **`telemetry`** — Reads a specific actor's live telemetry from a running CARLA server — location and rotation, velocity and speed, acceleration, angular velocity,....
- **`toggle-env-objects`** — Lists and toggles a map's static environment objects via get_environment_objects / enable_environment_objects — hide or show buildings,....
- **`world-data`** — Queries the live CARLA world and resolves an entity description into a concrete actor id — find actors by type, role, or colour, or the single one....

### `ros2`

- **`add-ros-message-type`** — Adds a new ROS 2 message type to CARLA's native ROS 2 interface — the hand-written POD struct under LibCarla/source/carla/ros2/types/msg, its....
- **`add-ros-publisher`** — Adds a new topic to CARLA's native ROS 2 interface — a publisher (BasePublisher + PublisherImpl, topic suffix, QoS, registration in....
- **`visualize-ros-rviz`** — Inspects and visualises a ROS-2-enabled CARLA server from Docker containers, with no local ROS 2 install — list/echo/rate-check topics (the "are....

### `scenario-runner`

- **`analyze-scenario-results`** — Reads and summarises ScenarioRunner output — the criteria pass/fail tables from --output/--file, the machine-readable --json and --junit result....
- **`create-scenario`** — Writes a new ScenarioRunner scenario — a Python class deriving from BasicScenario with its behaviour tree assembled from srunner atomic behaviours....
- **`run-openscenario`** — Runs standard-format scenarios through ScenarioRunner — ASAM OpenSCENARIO 1.x (.xosc, via --openscenario, with catalogs and ParameterDeclaration....
- **`run-route-scenario`** — Runs a route through ScenarioRunner's RouteScenario mode (--route / --route-id) with an autonomous agent driving the ego — the same mechanism the....
- **`run-scenario`** — Runs a single ScenarioRunner Python scenario (or a whole group) against a running CARLA server — FollowLeadingVehicle, ControlLoss,....

### `scenic`

- **`create-scenic-scenario`** — Writes a new Scenic scenario (.scenic) from a natural-language description — "a car cuts in from the right lane", "a pedestrian crosses in front....
- **`run-scenic-scenario`** — Runs Scenic probabilistic scenarios against a running CARLA server with the `scenic FILE --simulate --2d` CLI — the carlaChallenge1-10 traffic....

### `setup`

- **`check-feature-support`** — Answers "can CARLA do X here, and is there a vetted procedure for it" before you promise anything, and detects client/server/tree version skew — a....
- **`download-carla`** — Downloads CARLA so nothing has to be fetched by hand — an official release package for any published version (resolved live from the GitHub....
- **`install-leaderboard`** — Installs the CARLA Autonomous Driving Leaderboard (leaderboard.carla.org) at a chosen version — 1.0, 2.0 or 2.1 — together with the exact....
- **`install-python-api`** — Installs the CARLA Python client (the `carla` package) into a chosen interpreter so the other python-api skills work — from a wheel bundled with....
- **`install-scenario-runner`** — Installs CARLA's ScenarioRunner (the official scenario engine) and picks the branch that matches the CARLA in use — master for 0.9.14-0.9.16....
- **`install-scenic`** — Installs Scenic, the probabilistic scenario description language, for the CARLA in use — pip installing it into the same interpreter that holds....

### `ue4`

- **`build-carla-ue4`** — Builds CARLA (branch ue4-dev, Unreal Engine 4.26) from source on Linux end-to-end — UE4 fork, the Carla server (editor C++ modules), the LibCarla....
- **`import-carla-map`** — Imports a custom RoadRunner map (FBX geometry + XODR OpenDRIVE) into a CARLA source build as a drivable map — reads the map from the directory the....
- **`import-carla-prop`** — Imports FBX meshes into a CARLA source build as spawnable static.prop.* blueprints — pass a directory whose subdirectories name the semantic tags,....
- **`import-carla-vehicle`** — Imports an FBX vehicle into a CARLA source build as a spawnable vehicle.<make>.<model> — checks the FBX carries CARLA's 4-wheel bone rig, imports....
- **`import-carla-walker`** — Imports an FBX pedestrian into a CARLA source build as a spawnable walker.pedestrian.NNNN — checks the FBX is skinned to CARLA's GEN3 rig, imports....
- **`package-carla-ue4`** — Cooks and packages CarlaUE4 into distributable tarballs under Dist/ — either the full simulator or a standalone asset package of selected maps and....
- **`run-carla-server`** — Launches a CARLA RPC server a carla.Client can connect to, working out for itself what you pointed it at — a downloaded/extracted release, a....

### `ue5`

- **`check-ue5-limitations`** — Tells you what CARLA on UE 5.5 (branch ue5-dev) cannot do that UE 5.8 (ue58-dev) can, so you do not attempt an unsupported workflow there — no....

### `ue58`

- **`build-carla-ue58`** — Builds CARLA on Unreal Engine 5.8 from the ue58-dev branch using its CMake build system — configure a preset, then build the carla-unreal /....
- **`carla-vehicle-authoring`** — Create, migrate, improve, or debug detailed vehicle assets for CARLA using Blender and Unreal, including reference-based geometry, materials,....
- **`import-carla-ue58-map`** — Gets a custom map into CARLA on UE 5.8 — the four distinct routes and which one to pick — via Util/Tools/Import.py for FBX+OpenDRIVE assets into a....
- **`import-carla-ue58-prop`** — Imports FBX meshes into CARLA on UE 5.8 as spawnable props — drives the editor headlessly to import the mesh, derives the prop size from its....
- **`import-carla-ue58-walker`** — Imports a pedestrian into CARLA on UE 5.8 as a spawnable, animating walker — imports the skinned FBX bound to CARLA's shared pedestrian skeleton,....
- **`package-carla-ue58`** — Cooks and packages a shippable CARLA server from a UE 5.8 ue58-dev checkout via the CMake `package` targets (shipping/development/debug/test),....
- **`run-autoware-ue58`** — Runs the Autoware autonomous-driving stack against CARLA on UE 5.8 over CARLA's native ROS 2 interface — no bridge process.
- **`run-carla-ue58-server`** — Starts a CARLA UE 5.8 server from a ue58-dev tree — the editor binary in -game mode (the working headless server), the packaged shipping build, or....

## Repository conventions

- `LibCarla/` — the C++ client/server library. `PythonAPI/` — bindings, docs
  (`PythonAPI/docs/*.yml`) and examples.
- `Docs/python_api.md` is **generated** from `PythonAPI/docs/*.yml` by
  `PythonAPI/docs/doc_gen.py`. Never edit it directly; edit the YAML and
  regenerate.
- Smoke tests live in `PythonAPI/test/smoke/` and need a running server on
  port 3654.
- Add a `CHANGELOG.md` entry under `## LATEST Changes` for user-visible changes.