carla-simulator/carla-agentic-tools/debug-draw

Draw CARLA debug shapes

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.

Overlay primitives on the running world for visual debugging: points, lines, arrows, boxes, text. They are drawn by the server as a transient overlay — not actors — so they cannot be selected or deleted individually; they expire after their --life. Other skills (e.g. map-waypoints) draw through this same world.debug API.

Instructions

Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Draw the primitive(s) with a colour and lifetime
- [ ] Step 3: Confirm in a rendered view; redraw if it must persist in sync mode

Commands need CARLA_HOST/CARLA_PORT from scripts/env.sh. Coordinates are world metres X,Y,Z; colours are r,g,b (0-255). Negative coordinates: use the = form (--at=-10,-5,1, --from=-3,0,1) so a leading minus isn't read as a flag.

Step 1: Check prerequisites

bash scripts/check_env.sh

Step 2: Draw

source scripts/env.sh
 
python3 scripts/debug_draw.py point  --at 10,20,1 --size 0.2 --color 0,255,0 --life 60
python3 scripts/debug_draw.py line   --from 0,0,1 --to 50,0,1 --thickness 0.2 --life 60
python3 scripts/debug_draw.py arrow  --from 0,0,1 --to 10,0,1 --color 0,0,255 --life 60
python3 scripts/debug_draw.py box    --center 30,30,1 --extent 2,4,1.5 --yaw 45 --life 60
python3 scripts/debug_draw.py text   --at 30,30,3 --text "junction 12" --color 255,255,0 --life 60

Step 3: Confirm / persistence

Shapes render on a world tick, in a rendered view. Two gotchas:

• Headless `-nullrhi` servers show nothing — there is no render thread. Use a

windowed or packaged server to see overlays.

• Sync mode: nothing appears until the client ticks, and --life is in

simulation time. For an overlay that stays up while stepping, redraw each frame (or set --life longer than your tick interval).

On CARLA 0.10.0 (the UE5 line: 5.5 and 5.8)

The HUD variants are gone on 0.10.0. carla.DebugHelper there exposes exactly seven methods — draw_point, draw_line, draw_arrow, draw_box, draw_string, clear_debug_shape, clear_debug_string — so the 0.9.14+ draw_hud_point / draw_hud_line / draw_hud_box family (which drew in screen space, ignoring depth) has no equivalent. Use the world-space calls; they behave the same on both versions.

clear_debug_shape and clear_debug_string exist on both, and are the only way to remove a shape before its lifetime expires.

Examples

Example 1: mark a spot

User says: "mark world position (10, 20)"

point --at 10,20,1 --size 0.2 --color 0,255,0 --life 120.

Example 2: label and box an object

User says: "put a box and a label around (30,30)"

box --center 30,30,1 --extent 2,4,1.5 then text --at 30,30,3 --text "target".

Troubleshooting

Problem: nothing shows up Cause: headless -nullrhi server (no rendering), or sync mode without a tick. Solution: run a windowed/packaged server; in sync mode tick the world.

Problem: shape vanishes immediately Cause: very small --life, or a single-frame draw in sync mode. Solution: raise --life, or redraw each frame for a persistent overlay.

Problem: I can't delete a shape Cause: debug shapes are not actors. Solution: they expire on their own; use a short --life, or reload the world.

Outputs

Transient visual overlay in the rendered world. No file, no persistent actor.

Detail (each primitive's parameters, colour/lifetime semantics, sync-mode behaviour) in references/debug.md.