Principle:CARLA simulator Carla Content Asset Management
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Development |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Separating binary content assets from source code using a dedicated repository enables efficient management of large maps, 3D models, and textures required by the CARLA simulator.
Description
CARLA's content assets -- which include urban maps, vehicle meshes, pedestrian models, traffic signs, road textures, and environmental props -- are stored in a separate Git repository hosted on Bitbucket at carla-simulator/carla-content. This content repository is cloned into the Unreal/CarlaUnreal/Content/Carla directory within the CARLA source tree, where the Unreal Engine project expects to find its content assets.
The content repository uses the ue5-dev branch to align with the main CARLA source branch. Due to the binary nature of the assets (FBX meshes, PNG/TGA textures, UMAP/UASSET files), this repository leverages Git LFS (Large File Storage) to handle files that would otherwise bloat the Git history.
The content assets are essential for running the simulator with its built-in environments. Without them, CARLA can still compile but will have no maps, vehicles, or other visual assets to simulate.
Usage
This principle applies when:
- Building CARLA from source for the first time and needing the default map and asset library
- Updating content assets to match a new CARLA source version
- Understanding the separation between code and content in the CARLA project structure
- Troubleshooting missing map or asset errors when launching the simulator
Theoretical Basis
Code-content separation: Software engineering best practice for game engines and simulation platforms is to separate source code from binary content assets. Source code is small, text-based, and benefits from Git's delta compression and diff capabilities. Binary assets are large, opaque to diff algorithms, and change less frequently. By placing them in separate repositories, each can be managed with appropriate strategies:
- Source code: standard Git with branching, merging, and code review
- Content assets: Git with LFS, where large files are stored as pointer files in the main repository and the actual binary data is stored on a separate LFS server
Git LFS architecture: Git LFS replaces large files in the repository with lightweight pointer files. The actual file content is stored on a remote LFS server (in this case, Bitbucket's LFS infrastructure). When a developer clones or checks out, Git LFS automatically downloads the actual binary files referenced by the pointers. This keeps the main Git repository small and clone operations fast, while still providing version control for binary assets.
Directory placement: The content must be cloned into a specific path (Unreal/CarlaUnreal/Content/Carla) because Unreal Engine's asset registry resolves content references using the project's Content/ directory hierarchy. The CARLA Unreal project's .uproject file and plugin references expect assets to be at these conventional paths.
Branch synchronization: The content repository's ue5-dev branch is kept synchronized with the main CARLA source repository's ue5-dev branch. When source code changes reference new assets or modify existing asset paths, the corresponding content branch is updated to match. Using mismatched branches between source and content will result in missing asset warnings or runtime errors.
Practical Guide
Step 1: Ensure Git LFS is installed
git lfs --version
# If not installed: sudo apt install git-lfs && git lfs install
Step 2: Navigate to the content directory
cd CarlaUE5/Unreal/CarlaUnreal/Content
Step 3: Clone the content repository
git clone -b ue5-dev https://bitbucket.org/carla-simulator/carla-content.git Carla
This will download all maps, vehicle models, textures, and props. Expect a substantial download (multiple gigabytes) depending on the current content set.
Step 4: Verify the content
Check that the content directory contains the expected asset categories:
ls CarlaUE5/Unreal/CarlaUnreal/Content/Carla/
# Expected directories: Maps/, Static/, Blueprints/, Materials/, etc.