CarlaAir: putting a multirotor inside the same Unreal process as CARLA

What the single-process composition actually buys

The usual way to simulate a drone and a car together is to run two simulators and bridge them, which means two physics loops, two clocks, a pipe between them, and a latency figure you have to subtract from every measurement. CarlaAir's claim is that all of that goes away. The README describes a composition in which a single Unreal Engine game mode inherits CARLA's game mode and pulls in AirSim, with roughly 35 lines changed across about three upstream files.

That is the whole architectural thesis, and it deserves a fair reading rather than being dismissed as marketing. Because there is one process, there is one tick, so a vehicle and a drone sampled at the same simulation step see the same world state. The README states exact coordinate alignment, with zero error between CARLA's left-handed frame and AirSim's NED frame, which is the kind of detail that normally requires a calibration step bolted onto a bridge. Communication overhead is quoted as under 0.5 ms, against the 1 to 5 ms the README attributes to bridge-based co-simulation.

The two API servers run on separate ports so existing clients keep working: CARLA RPC on 2000, AirSim RPC on 41451. A CARLA Python script and an AirSim script both talk to the same world, which is the mechanism behind the claim that existing scripts run unmodified.

Sensor modalities and what frame alignment buys a perception study

The sensor story is what makes this useful for perception work rather than only for demos. The README lists up to 18 modalities: RGB, depth, semantic segmentation, instance segmentation, LiDAR, radar, surface normals, IMU, GNSS and barometry. The part that matters is that all of them are frame-aligned across air and ground, so a camera on the drone and a camera on the vehicle are genuinely comparable rather than approximately comparable after a hand-rolled transform.

The `examples/` directory backs this up in a small way. `examples/sensor_gallery.py` is what you would expect from a project making sensor claims, and `examples/air_ground_sync.py` is the air-ground synchronization demonstration. `examples/ros2/` arrived later, in April 2026, described as minimal vehicle and drone sensor bridges plus an RViz 2 preset that works on Humble without building `carla-ros-bridge` from source. That last detail is worth something to anyone who has lost a weekend getting a ROS bridge to compile against a simulator build.

`examples/switch_maps.py` and `examples/walk_pedestrian.py` suggest the world is not a single fixed town. `auto_traffic.py` at the repository root matches the traffic generation described in the release notes.

A version line that moved fast through 0.1.x

This is a young project with a quick release cadence and a version number that has not yet left the zeroes. v0.1.6 shipped on 2026-03-19 as the initial public release and already contained the single game mode design plus a launcher script. v0.1.7 followed on 2026-03-24 with what the project calls stability work, a recording toolkit and one-click environment setup.

The release notes are specific about which engineering problems were actually solved, which helps when you are deciding whether a research dependency is a moving target. v0.1.6 replaced a custom bounce collision system with UE4 native Sweep so the drone stops on impact instead of deflecting, and added ground clamping to stop it clipping through terrain. v0.1.5 added a 12-direction collision system and a bilingual help overlay on the H key. v0.1.7 fixed VSync behaviour and traffic stability.

A third release, `v0.1.7-win11-x86_64`, published on 2026-04-16, is about packaging rather than code. GitHub caps individual release assets at 2 GiB, so the Windows archive is split into four numbered parts that have to be concatenated, and the notes supply a SHA256 for the rebuilt zip. Expect the same treatment from other research simulators: the binary is roughly 18 GB according to the v0.1.6 notes, which is why it lives on external hosting. The last push to the repository was on 2026-08-14.

Getting it running from the launcher script

Prebuilt executables exist for Ubuntu 20.04 and 22.04 and for Windows 11, hosted on Baidu Pan and Hugging Face rather than in the repository. That matters outside China, where Baidu Pan is awkward to fetch programmatically and the Hugging Face copy is the practical route. The supported stack is CARLA 0.9.16, AirSim 1.8.1, Python 3.8 or newer, and Unreal Engine 4 according to the release notes.

Building from source means the standard Unreal plus CARLA plus AirSim arrangement rather than a single command. The top-level `Makefile` is a thin dispatcher: it includes a shared variables file, then branches on the host OS to pick a Windows or Linux recipe.

include Util/BuildTools/Vars.mk
ifeq ($(OS),Windows_NT)
include Util/BuildTools/Windows.mk
endif

The launcher named in the release notes is `carlaAir.sh`, which auto-detects the Vulkan ICD, kills a previous instance and spawns traffic.

./carlaAir.sh

Traffic generation also has a standalone script at the repository root.

python auto_traffic.py

Two in-simulator controls appear in the release notes. The P key toggles between a physics mode with realistic collision and an invincible noclip mode, which is handy while you are placing a scenario, and the H key opens the bilingual status overlay.

Three licence signals that do not agree

Three different licence claims live in this repository and they conflict, so the file itself is the only authority. The repository's licence metadata field is unset. The README badge reads a custom non-commercial licence. The v0.1.7 release page renders a badge that reads MIT. A custom non-commercial licence and MIT are very different instruments: one restricts commercial use, the other does not.

A reader who trusts the MIT badge could ship something into a commercial setting that a custom licence forbids. A reader who trusts the README badge would correctly assume restrictions apply but still would not know which terms, because the badge names no licence file. The practical move is to open `LICENSE` in the repository root and read it before doing anything with the binaries. This is not legal advice and no reading of the terms is offered here, but the ambiguity is worth naming, because this is exactly the kind of thing that gets discovered after a lot of work has already been built on it.

The base projects carry their own terms. CARLA is licensed separately from the simulator it forks and AirSim has its own history, so the terms covering a given CarlaAir build depend on which layers an experiment actually exercises.

Reading the performance table as author claims

The README publishes a small table of measured figures, worth quoting with attribution rather than as settled fact. A moderate joint configuration of vehicles, one drone and eight sensors is reported at 19.8 plus or minus 1.1 FPS, with communication overhead under 0.5 ms. A three-hour stability run is reported alongside 357 spawn operations. Compatibility is reported as 89 of 89 CARLA API tests passing.

These are the authors' own numbers on their own hardware, and the project does not publish the machine, the map, or the vehicle count behind the 19.8 FPS figure. If your workload is heavier than vehicles plus one drone plus eight sensors, that 20 FPS ceiling matters a lot, because joint air-ground workloads with many sensors are exactly where a UE4 renderer becomes the bottleneck. Nothing in the README says what happens with a second drone.

There is a paper behind all of this, arXiv 2603.28032, linked from the README along with a PDF under `docs/pdf/` and a project page at carla-air.com. The paper reached the top of Hugging Face Daily Papers on 2026-04-01. At version 0.1.7 the paper is the more informative document, because the README is the project explaining itself and the paper is the project being examined. The fair summary is that the composition idea is sound and cheap to try, the numbers are single-machine and thin on detail, and the licence needs reading before it reaches a commercial setting.

Editorial conclusion

CarlaAir is worth an afternoon if your research needs a drone and a car reacting to each other inside the same traffic simulation, because the single-process composition removes the co-simulation latency that usually makes joint perception benchmarks awkward. It is the wrong tool if you need a supported production simulator, a permissive licence, or Windows support you can rely on: the Windows build exists only as a separate source branch and a four-part archive split for GitHub asset limits. The engineering is real and the numbers come from the authors' own runs, while the licence signal is contradictory across three different places in the repository. Start by reading the LICENSE file rather than any badge, then check the port layout in CarlaAir_Release before you plan an experiment around it.

Frequently asked questions

Official sources

1. Issues
2. louiszengCN/CarlaAir on GitHub
3. README
4. Releases