Set CARLA world settings
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.
Change how a running server steps time and renders, from a client, and read
the result back. The deliverable is verified server state: after any change the
WorldSettings are re-read (apply_settings returns a frame id, not the state).
The core switch is synchronous vs asynchronous:
- async (default): the server free-runs on its own clock; the client observes.
- sync: the server advances only when the client calls
world.tick(), at
a fixed fixed_delta_seconds step — required for frame-aligned sensors and
reproducible runs.
This skill couples the Traffic Manager to that switch automatically: sync
also sets the TM synchronous, async also sets it asynchronous. A mismatched
pair is a classic source of jittery or frozen traffic. Full semantics:
references/world-settings.md.
Instructions
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Show current settings
- [ ] Step 3: Apply sync / async / a field change (TM follows sync|async)
- [ ] Step 4: Verify the VERIFY block matches the intent
- [ ] (on exit) Restore async so the server self-ticks — never leave it stuck in sync
Commands need CARLA_HOST/CARLA_PORT/TM_PORT from scripts/env.sh (defaults
127.0.0.1:2000, TM 8000). Prefix with source scripts/env.sh or export them.
Step 1: Check prerequisites
bash scripts/check_env.sh
FAILs only on a missing carla module or an unreachable server. It also warns if
the server is already in sync mode (it will look "frozen" without a ticker).
Step 2: Show current settings
source scripts/env.sh
python3 scripts/world_settings.py show
Step 3: Apply
# synchronous mode at 20 fps (0.05 s step); TM set synchronous too
python3 scripts/world_settings.py sync --fps 20
# give the step directly instead of fps
python3 scripts/world_settings.py sync --delta 0.05
# sync + headless physics (no rendering)
python3 scripts/world_settings.py sync --fps 20 --no-rendering
# restore asynchronous mode; TM set asynchronous too
python3 scripts/world_settings.py async
# change individual fields without touching sync/TM (any WorldSettings field)
python3 scripts/world_settings.py set --no-rendering off
python3 scripts/world_settings.py set --fixed-delta none # back to variable step
python3 scripts/world_settings.py set --deterministic-ragdolls on --max-culling-distance 500
python3 scripts/world_settings.py set --tile-stream-distance 2000 --actor-active-distance 1500
python3 scripts/world_settings.py set --substepping on --substeps 16 --substep-dt 0.0125
Low freedom on two fragile points: fixed_delta_seconds should stay <= 0.1 for
stable physics (the script warns and auto-raises max_substeps to keep the
substep budget), and after enabling sync you must world.tick() to advance.
Step 4: Verify
Each command prints a VERIFY block: synchronous_mode, fixed_delta_seconds
(+ derived fps), no_rendering_mode, substepping fields, and the TM sync state it
set. Confirm they match the request — e.g. sync --fps 20 ⇒ synchronous_mode = True, fixed_delta_seconds = 0.05, traffic_manager sync = True.
On exit: restore async
Leaving the server in sync mode with nothing ticking makes it appear hung to the
next client. When a sync-mode task ends, run async to hand the clock back to the
server. This is the default job's clean-exit step, not an opt-in extra.
Examples
Example 1: set up a deterministic capture loop
User says: "put the sim in sync mode at 20 fps"
python3 scripts/world_settings.py sync --fps 20. VERIFY: synchronous_mode=True,
fixed_delta_seconds=0.05, traffic_manager sync=True. Then tick from your client.
Example 2: tear down cleanly
User says: "I'm done, put it back to normal"
python3 scripts/world_settings.py async. VERIFY: synchronous_mode=False,
fixed_delta_seconds=None, traffic_manager sync=False. Server self-ticks again.
Example 3: keep settings across a map load
User says: "switch to Town02 without dropping my sync settings"
sync --fps 20 here, then the load-map skill with
--keep (reset_settings=False) so the settings survive the load; tick after.
Troubleshooting
Problem: traffic is jittery / vehicles teleport in sync mode
Cause: world is sync but the Traffic Manager is async (or vice-versa).
Solution: use sync/async here — they set both. Manually, tm.set_synchronous_mode(True).
Problem: the server looks frozen / clients time out after enabling sync
Cause: nothing is ticking it. In sync mode the world advances only on world.tick().
Solution: tick from your client, or run async to restore self-ticking.
Problem: physics unstable / warning about the substep budget
Cause: fixed_delta_seconds exceeds max_substep_delta_time * max_substeps.
Solution: keep the step <= 0.1; the script raises max_substeps to fit and warns.
Problem: sim not fully reproducible even in sync mode
Cause: the Traffic Manager's random seed is unset.
Solution: set a TM seed (owned by the traffic-manager skill) in addition to sync.
Outputs
Server state, not a file: the running world now steps synchronously or
asynchronously as asked, with the TM matched. The VERIFY block is the record.
Field-by-field reference (every WorldSettings attribute, the substep math, the
sync/TM/determinism rules) is in references/world-settings.md.