CARLA 0.10.0 / UE5 (Chaos) compatibility on a dual-version branch by JArmandoAnaya · Pull Request #1163 · carla-simulator/scenario_runner

JArmandoAnaya · 2026-05-28T09:03:52Z

Description

ScenarioRunner now runs against the CARLA 0.10.0 server (UE5 / Chaos physics) while keeping full compatibility with CARLA 0.9.x (UE4 / PhysX) from the same source tree. The engine is auto-detected at runtime from the installed carla wheel; an SR_CARLA_VERSION env override forces a version when the wheel disagrees with the running server. Default UE5 map is Town10HD_Opt; other UE5 maps remain reachable via --configFile / --additionalScenario.

Each UE4-only API call is resolved as either a documented UE5 port or an explicit drop with a behavior-delta note in Docs/CHANGELOG.md, no hasattr-and-silently-no-op shims. Live validation on a real 0.10.0 server: three UE5-configured scenarios (FollowLeadingVehicle_1, FollowLeadingVehicleWithObstacle_1, OtherLeadingVehicle_1) all run spawn to behavior-tree tick to criteria evaluation to result reporting, with CollisionTest SUCCESS on every run.

Changes

srunner/tools/carla_compat.py (new). Runtime version detection, IS_UE5, SR_CARLA_VERSION env override, version-keyed blueprint alias and category-fallback tables.
CarlaDataProvider.create_blueprint consults the alias table on UE5 and fixes a latent np.random.choice([]) bug in the empty-filter fallback.
srunner/examples_ue5/ (new) for Town10HD_Opt configs; scenario_parser.py reads it first on UE5 with per-name dedup against examples/.
VehicleVelocityControl.__init__ skips the tire_friction = 0 setup on UE5; UE4 path unchanged. apply_physics_control discards Chaos wheel writes on the 0.10.0 build under test, no working UE5 equivalent.
RouteLightsBehavior becomes engine-aware: no set_day_night_cycle and no per-Light enumeration on UE5 (both removed in 0.10.0). Vehicle-light control preserved on both engines.
Metrics parsers branch on IS_UE5. New srunner/metrics/tools/recorder_chaos.py walks the rewritten Chaos Physics Control block and exposes a shared skip_indented_section helper used by both MetricsParser and Osc2TraceParser to walk past the new 0.10.0 recorder sections (Vehicle door animations, Weathers, Walkers Bones).
RosAgent.publish_can drops the PhysX-only CarlaEgoVehicleInfo block on UE5, emits a one-time deprecation warning pointing at the native CARLA ROS 2 bridge.
New carla-free unit tests under tests/ (42 tests) using a stub carla module and a committed 0.10.0 recorder fixture.

Where has this been tested?

CARLA versions: 0.9.x; 0.10.0
Python version: 3.10
What was run: python scenario_runner.py --scenario {FollowLeadingVehicle_1, FollowLeadingVehicleWithObstacle_1, OtherLeadingVehicle_1} --reloadWorld --sync --output, plus cd tests && python -m unittest test_carla_compat test_recorder_chaos (42 tests pass).

Possible Drawbacks

The physics_control dict shape returned by MetricsParser / Osc2TraceParser differs between engines (PhysX vs Chaos field set). Metric scripts that read these structs must branch on srunner.tools.carla_compat.IS_UE5.
On UE5 the legacy RosAgent no longer publishes PhysX-only physics fields; users must migrate to the native CARLA ROS 2 bridge for full physics telemetry.
Two-wheeler scenarios on UE5 substitute vehicle.mini.cooper because no bicycle/motorbike ships in the 0.10.0 catalogue. Scenarios run but lose visual identity.
Trajectories with sharp lateral / cornering moves track less faithfully on UE5 because apply_physics_control discards wheel-friction writes on the current 0.10.0 build.
Jenkinsfile still pulls a single CARLA tarball; the UE5 live-server matrix entry is a follow-up once tarball hosting for 0.10.0 is confirmed. The new unit suites work in any Python env without a CARLA wheel.

Introduces srunner/tools/carla_compat.py with cached version detection (IS_UE5 / IS_UE4 / CARLA_VERSION constants, SR_CARLA_VERSION env override) and version-aware blueprint id alias + category fallback tables. Rewires CarlaDataProvider.create_blueprint to translate legacy 0.9.x ids through the compat layer so scenarios that hardcode model names such as vehicle.lincoln.mkz_2017 or vehicle.tesla.model3 spawn cleanly on a CARLA 0.10.0 server. The 0.9.x path is a strict passthrough. Also fixes a latent bug in the missing-blueprint fallback: when the category fallback resolved to an empty filter, np.random.choice([]) raised uncaught. The new path tries the category fallback, then vehicle.*, then raises a diagnostic ValueError.

The legacy srunner/examples/*.xml configs target Town01-Town05, which do not ship with CARLA 0.10.0. On UE5 servers, the scenario parser now also reads srunner/examples_ue5/*.xml first; entries there override the legacy configs by scenario name. On 0.9.x the new directory is ignored. Initial coverage: - FollowLeadingVehicle_1 + FollowLeadingVehicleWithObstacle_1 at a Town10 spawn with 90 m of clear road before the next junction. - OtherLeadingVehicle_1 at a Town10 spawn with 170 m clear and a same-direction left lane for the parallel vehicle. Ego model keeps the legacy id vehicle.lincoln.mkz_2017; the carla_compat alias map translates it to vehicle.lincoln.mkz on UE5, so the same config can be reused on 0.9.x as well. Validated end-to-end against a live 0.10.0 server: both scenarios load Town10HD_Opt, spawn ego + others via the compat layer, tick the behavior tree, and report CollisionTest SUCCESS. The expected TIMEOUT comes from running --scenario without --agent, which is identical behavior to 0.9.x.

PhysX exposed WheelPhysicsControl.tire_friction; setting it to 0 was the existing trick to stop set_target_velocity from being decelerated by ground friction. Chaos removed tire_friction and exposes friction_force_multiplier as its documented friction-scaling parameter, but live probing on CARLA 0.10.0 (Town10HD_Opt, vehicle.lincoln.mkz) shows apply_physics_control silently discards wheel-attribute writes in this build — both tire_friction and friction_force_multiplier writes are accepted but the read-back keeps the default 3.5. Other UE5 candidates also fail: set_simulate_physics(False) kills set_target_velocity motion outright; enable_constant_velocity either lags badly when re-called per tick or, when called once at setup, becomes a sticky override that blocks subsequent set_target_velocity updates. No documented working UE5 API zeros wheel friction for this controller's kinematic-injection use. Per the project's "real port OR explicit drop" rule, this is a drop: on UE5 the friction-zeroing block is skipped entirely. The controller continues to work for heading-aligned trajectories (live probe: 5.05 m over 5 s @ 1 m/s target, 101% of expected). Behavior delta: sharp lateral / cornering motion will track less faithfully on UE5 until upstream carla-ue5 either fixes apply_physics_control or exposes another per-wheel friction-override path. UE4 path (tire_friction = 0) is unchanged.

Retroactive doc pass for the three feature/ue5-0.10.0-compat commits that have landed so far. Per the documentation rule, runtime-visible changes must be reflected in Docs/ before opening a PR. CHANGELOG.md: new "Unreleased — CARLA 0.10.0 / UE5 compatibility" section covering the auto-version-detection layer (carla_compat), the blueprint alias table and per-category fallback rebuild in CarlaDataProvider, the version-aware scenario_parser glob with examples_ue5/ priority + name dedup, the new Town10HD_Opt configs for FollowLeadingVehicle and OtherLeadingVehicle, the empty-fallback ValueError fix, the VehicleVelocityControl UE5 friction-zero drop, and the lateral-tracking behavior delta. getting_scenariorunner.md: new "Running against CARLA 0.10.0 (UE5)" section covering wheel install, the Town10HD_Opt default, the SR_CARLA_VERSION override, an example invocation, and the VehicleVelocityControl cornering-degradation note.

LightManager was removed in CARLA 0.10.0 (Chaos). The route-lights behavior used it for two separate things, with different UE5 outcomes: G4a: set_day_night_cycle(False/True). Drops on UE5. The behavior already gates night-mode off weather.sun_altitude_angle (the documented UE5 day/night control), and UE5 has no auto sun motion to disable. G4b: per-Light get_all_lights / turn_on / turn_off enumeration. Drops on UE5. MapLayer.StreetLights is a map-layer load flag, not a runtime per-Light toggle, and no documented UE5 API exposes per-Light runtime control. The vehicle-light portion (Vehicle.set_light_state / get_light_state) is preserved on both engines. On UE5, __init__ now sets self._light_manager = None and emits a one-time INFO line so users know street lights are not being controlled. _turn_close_lights_on, _turn_all_lights_off, and terminate gate the LightManager calls with `if self._light_manager is not None:`. Live validation on Town10HD_Opt: __init__ no longer raises AttributeError on world.get_lightmanager(); update() under weather.sun_altitude_angle = -30° sets ego light state to Position|LowBeam (mask 3); update() under sun_altitude_angle = 75° clears it back to 0; terminate() runs cleanly. UE4 path is unchanged. Docs/CHANGELOG.md and Docs/getting_scenariorunner.md updated per the documentation rule.

All three UE5-configured scenarios run end-to-end on a live CARLA 0.10.0 server (Town10HD_Opt) with the full compat stack (G1 alias layer + G2 examples_ue5 configs + G3 friction-zero drop + G4 LightManager port-and-drop) integrated: FollowLeadingVehicle_1 60.05 s game, CollisionTest SUCCESS FollowLeadingVehicleWithObstacle_1 120.05 s game, CollisionTest SUCCESS OtherLeadingVehicle_1 80.05 s game, CollisionTest SUCCESS Each run executes spawn → behavior-tree tick → criteria evaluation → result writer rendering → actor cleanup. TIMEOUT is the expected global result in --scenario mode (no --agent drives the ego, so completion conditions never trigger). FollowLeadingVehicleWithObstacle_1 exercises the alias table's bicycle → vehicle.mini.cooper substitution; OtherLeadingVehicle_1 exercises vehicle.audi.tt → vehicle.ue4.audi.tt. Both substitutions fire transparently inside CarlaDataProvider.create_blueprint.

G5 (port). Branch metrics_parser.py and osc2_trace_parser.py on IS_UE5. On 0.9.x the existing PhysX Physics Control walker is untouched. On 0.10.0 a new srunner/metrics/tools/recorder_chaos.py owns the rewritten block — Chaos field set (friction_force_multiplier, cornering_stiffness, max_brake_torque, forward_gear_ratios, ...) from carla-ue5/Docs/python_api.md §carla.VehiclePhysicsControl and §carla.WheelPhysicsControl, the new 'wheel #N:' one-line tokenizer, and the indented 'gear N: ratio X' lists. Live-validated against a real Town10HD_Opt recorder dump from a 0.10.0 server (vehicle.lincoln.mkz, 40 frames): scalars, booleans, vectors, wheels[], torque/steering curves and center_of_mass all populate; the list-attribute readback gap (std::vector<float> to-Python converter) is binding-side and noted in the docs. Both parsers also walk past the new top-level recorder sections introduced by 0.10.0 (Vehicle door animations, Weathers, Walkers Bones) so downstream blocks remain reachable. G6 (drop). RosAgent.publish_can omits the PhysX-only CarlaEgoVehicleInfo fields on UE5 (tire_friction, damping_rate, moi, damping_rate_full_throttle, damping_rate_zero_throttle_clutch_disengaged, use_gear_autobox, clutch_strength) and emits a one-time deprecation warning pointing at the native CARLA ROS 2 bridge. Only the fields that survive the engine swap (mass, drag_coefficient, center_of_mass) are populated. Per §5.0: no Chaos→PhysX field translation — downstream ROS consumers parse PhysX semantics. UE4 behavior unchanged. Docs: CHANGELOG and getting_scenariorunner updated with the new maintenance + behavior-delta bullets per the project documentation rule.

tests/test_carla_compat.py (16 tests) — reloads srunner.tools.carla_compat under SR_CARLA_VERSION env override to exercise both engine paths from one process. Covers version detection at threshold and above, IS_UE5 / IS_UE4 flags, resolve_blueprint_id translations (rename, substitute, walker remap, unknown-id passthrough, non-string inputs) and actor_blueprint_categories fallback dicts for both 0.9.x and 0.10.x. tests/test_recorder_chaos.py (25 tests) — installs a minimal stub `carla` module before importing the targets so the suite is carla-free. Three groups: - Wheel-line tokenizer: scalars, booleans, vector fields, the `max_hand_brake_torque` → `max_handbrake_torque` remap, empty-value handling (`axle_type: offset: ...`), runtime-field skip (wheel_index / location / velocity / external_torque_combine_method / lateral_slip_graph / sweep_*), unknown-field skip. - Physics Control block walker via a MockParser: actor key, scalar population, use_gear_auto_box → use_automatic_gears remap, empty differential_type doesn't crash, MOI is not silently aliased to rev_up_moi, center_of_mass / torque_curve / steering_curve / gear-ratio lists / wheels[] population, terminator exit, empty-block handling. - End-to-end MetricsParser / Osc2TraceParser on a committed 0.10.0 Town10HD_Opt recorder fixture (~58 KB at tests/fixtures/) — verifies the section-skip handlers for `Vehicle door animations`, `Weathers`, `Walkers Bones` actually clear the way to the Physics Control block, and that the two parser classes agree on the resulting shape. Run from `tests/`: PYTHONPATH=<repo root> python -m unittest test_carla_compat test_recorder_chaos All 41 tests pass. The Jenkins matrix extension is deferred — that needs infra-side coordination on whether the 0.10.0 server tarball is hosted at the same S3 prefix as the 0.9.x ones.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds CARLA 0.10.0+ (UE5 / Chaos) compatibility across ScenarioRunner by introducing runtime version detection, UE5-aware blueprint/config selection, and Chaos recorder parsing, with supporting docs and tests.

Changes:

Introduces srunner/tools/carla_compat.py for CARLA version detection + blueprint/category translation (IS_UE5 / IS_UE4).
Updates scenario/config parsing, blueprint selection, lights behavior, velocity control, ROS agent, and recorder metrics parsers to branch appropriately for UE5.
Adds UE5 example scenario configs, end-to-end Chaos recorder parsing tests, and documentation/changelog updates.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`srunner/tools/carla_compat.py`	Adds runtime CARLA version detection and UE5 translation tables for blueprints and category fallbacks.
`srunner/tools/scenario_parser.py`	Prefers `examples_ue5/` on UE5 and dedupes scenario names so UE5 configs override legacy ones.
`srunner/scenariomanager/carla_data_provider.py`	Applies blueprint-id translation and improves fallback behavior when a model is missing.
`srunner/scenariomanager/lights_sim.py`	Skips LightManager usage on UE5 (API removed) and keeps vehicle light control.
`srunner/scenariomanager/actorcontrols/vehicle_velocity_control.py`	Disables PhysX-only friction-zeroing setup on UE5.
`srunner/metrics/tools/recorder_chaos.py`	Adds Chaos-format Physics Control block walker and wheel tokenizer.
`srunner/metrics/tools/metrics_parser.py`	Adds UE5 section-skip handlers and routes Physics Control parsing to Chaos walker on UE5.
`srunner/metrics/tools/osc2_trace_parser.py`	Mirrors MetricsParser UE5 skips + Chaos physics control parsing on UE5.
`srunner/autoagents/ros_agent.py`	Avoids populating PhysX-only ROS message fields on UE5 with one-time warning.
`tests/test_carla_compat.py`	Adds unit tests for version detection, aliases, and category fallbacks.
`tests/test_recorder_chaos.py`	Adds carla-free tests for Chaos recorder parsing + fixture-based integration checks.
`srunner/examples_ue5/*.xml`	Adds Town10HD_Opt UE5 example scenario configs.
`Docs/getting_scenariorunner.md` / `Docs/CHANGELOG.md`	Documents UE5 usage and summarizes behavior deltas.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…iene - recorder_chaos: add `axle_type` -> `axel_type` field alias so the recorder spelling lands on the (mis-spelled) Chaos binding attribute. - recorder_chaos: harden `_parse_vector2d_list` against an unmatched `(` with `find` instead of `index`, plus per-pair float guard. Best-effort per the module contract. - scenario_parser: sort each glob result so the example-config dedup is deterministic across filesystems. - lights_sim: latch the UE5 LightManager-disabled print to once per process via a class-level flag. - carla_compat: surface a clear RuntimeError if the carla wheel metadata is missing and `SR_CARLA_VERSION` is unset. - tests: restore `SR_CARLA_VERSION` in `tearDownModule` so the suite is hermetic when other test files run in the same process.

Copilot

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

srunner/tools/scenario_parser.py:146

parse_scenario_configuration() now dedupes scenario names so UE5 examples_ue5/ overrides win, but get_list_of_scenarios() does not dedupe. That can cause duplicate scenario names to appear in listings on UE5 (one from examples_ue5, one from legacy examples). Consider applying the same per-scenario-name dedupe in get_list_of_scenarios() (preserving the same priority order) to keep its output consistent with actual selection behavior.

        """

        list_of_config_files = _collect_example_config_files(["xml", "xosc"])
        if additional_config_file_name != '':
            list_of_config_files.append(additional_config_file_name)

        scenarios = []

- recorder_chaos: move the empty-value guard ahead of the bool branches so an empty `use_gear_auto_box =` doesn't coerce to False. - recorder_chaos: factor the 0.10.0 section-skip pattern into `skip_indented_section`, called from both metrics_parser and osc2_trace_parser. Shrinks six 4-line blocks to one helper. - carla_compat: read the wheel version via `importlib.metadata.version` (the dedicated API) instead of `metadata(...)["Version"]`. Drops the KeyError case from the error wrap. - tests: cover the alias path explicitly (`axel_type` must also not be set when the recorder spelling has no value), and add a regression for the empty-bool case.

JArmandoAnaya added 8 commits May 28, 2026 00:28

Copilot AI review requested due to automatic review settings May 28, 2026 09:03

Copilot AI reviewed May 28, 2026

View reviewed changes

JArmandoAnaya force-pushed the feature/ue5-0.10.0-compat branch from 85b3e47 to 5273f84 Compare May 28, 2026 09:10

JArmandoAnaya requested a review from Copilot May 28, 2026 09:40

Copilot AI reviewed May 28, 2026

View reviewed changes

JArmandoAnaya mentioned this pull request May 28, 2026

CARLA 0.10.0 / UE5 (Chaos) compatibility: ScenarioRunner does not run against the UE5 server #1164

Open

JArmandoAnaya marked this pull request as draft May 28, 2026 17:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CARLA 0.10.0 / UE5 (Chaos) compatibility on a dual-version branch#1163

CARLA 0.10.0 / UE5 (Chaos) compatibility on a dual-version branch#1163
JArmandoAnaya wants to merge 10 commits into
carla-simulator:masterfrom
JArmandoAnaya:feature/ue5-0.10.0-compat

JArmandoAnaya commented May 28, 2026 •

edited by germanros1987

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

JArmandoAnaya commented May 28, 2026 • edited by germanros1987 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Where has this been tested?

Possible Drawbacks

Related

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JArmandoAnaya commented May 28, 2026 •

edited by germanros1987

Loading