Import a prop into CARLA
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.
# a directory — each subdirectory names the semantic tag for what is inside
python3 scripts/import_prop.py ~/meshes/props
# a single file — state its tag
python3 scripts/import_prop.py ~/meshes/Windmill.fbx --tag Building
Each mesh is imported into /Game/Carla/Static/<Tag>/<Name>, registered in
Content/Carla/Config/Default.Package.json, and added to PropFactory — after
which it spawns exactly like a native CARLA prop:
barrier_bp = bp_lib.find('static.prop.policebarrier')
for spawn_loc in spawn_locations:
world.spawn_actor(barrier_bp, spawn_loc)
Pipeline detail, schema and the P-lessons: references/props.md.
Instructions
Prop Import Progress:
- [ ] Step 1: Check prerequisites — hand off to build-carla-ue4 on a build FAIL
- [ ] Step 2: Import (one command, one editor boot)
- [ ] Step 3: Verify the props spawn on a running server
- [ ] (opt-in) Export as a standalone package
Step 1: Check prerequisites
bash scripts/check_env.sh
What must exist is a runnable editor for this project: UE4_ROOT, the
checkout, a built CarlaUE4Editor, and PythonScriptPlugin.
This skill never builds. On a FAIL naming UE4, CarlaUE4Editor or missing
content, stop and run [[build-carla-ue4]] against that checkout, then come back.
The check also reports whether Content/Carla is a symlink to a shared content
clone — if so, everything below lands in a tree every other checkout sees.
--package NAME keeps an import out of it.
Step 2: Import
The directory form takes each prop's tag from the first level below the path you
give — the same shape as the destination:
~/meshes/props/
├── Building/Windmill.fbx
├── Static/Bench_Modern.fbx
└── Dynamic/Crate.fbx
Any directory works. An FBX loose in the root, or under a directory that is not a
tag, is an error before the editor boots.
size is measured, not asked. EPropSize is defined by physical scale, so
the importer reads the mesh's bounding box and reports it:
[import] OK static.prop.windmill 3.2 x 3.1 x 12.4 m size=huge (measured) 412 KB
Read the dimensions: a mesh exported at the wrong scale shows up here. --size
overrides.
tag cannot be measured and is never defaulted. It sets the semantic
segmentation label, and a wrong one is labelled None with nothing raised. When
filling it in from a request rather than from directory names:
| the object is… | tag |
|---|
| bolted-down street furniture — bench, ATM, bus stop, fountain, mailbox, vending machine | Static |
| portable or knockable — bin, box, bag, cone, chair, cart, barrier | Dynamic |
| a structure with mass — kiosk, shed, windmill, tower | Building |
| a plant | Vegetation |
| a post — street light, sign post, bollard | Pole |
| road-surface debris | Other |
Say which tag you chose and why in one line, so the user can correct it before
anything is written. When the object is ambiguous, ask.
Other flags:
| flag | why |
|---|
--name | prop name for a single file; defaults to the FBX stem |
--package NAME | import into its own /Game/NAME/ tree — self-contained, exportable, touches no shared content, no factory entry |
--no-factory | skip PropFactory; the registry entry alone still makes the prop spawnable |
--mesh | nominate one mesh when a multi-mesh FBX yields several |
--verbose | stream the editor log instead of capturing it |
The importer stats every .uasset at the path it registered and fails if one is
missing or too small to hold geometry.
Step 3: Verify they spawn
Start a server ([[run-carla-server]] — the default -nullrhi mode is enough,
props need no rendering to spawn):
bash ../run-carla-server/scripts/run_server.sh Town10HD 2000 >/tmp/carla_server.log 2>&1 &
until nc -z 127.0.0.1 2000; do sleep 1; done
python3 scripts/verify_prop.py --name Windmill
pkill -x UE4Editor # clean stop — never pkill -f (run-carla-server S3)
verify_prop.py filters, finds, spawns and destroys each prop. Blueprint ids are
lowercase: static.prop.windmill.
Add --keep to leave the props standing, paired with a windowed server.
This is where the skill stops by default.
Optional: export as a standalone package
Only for --package imports, and only when the request asks to distribute the
props — the stock route has nothing separate to export:
python3 scripts/import_prop.py ~/meshes/props --package MyProps
PACKAGES=MyProps bash ../package-carla-ue4/scripts/package.sh
# -> Dist/MyProps_<tag>.tar.gz, installable into a release via ImportAssets.sh
Examples
Example 1: one prop
User says: "add this windmill FBX to CARLA as a prop"
bash scripts/check_env.sh
python3 scripts/import_prop.py ~/models/Windmill.fbx --tag Building
python3 scripts/verify_prop.py --name Windmill
Result: static.prop.windmill spawnable from any carla.Client.
Example 2: a directory of props
User says: "import all the street furniture in this folder"
Arrange it by tag once, then import in a single boot:
python3 scripts/import_prop.py ~/meshes/street_furniture
python3 scripts/verify_prop.py --package Carla # every prop in the stock set
Example 3: import and distribute (opt-in)
User says: "import these props and give me a package I can drop into a release"
Use --package MyProps, verify with --package MyProps, then
PACKAGES=MyProps bash ../package-carla-ue4/scripts/package.sh.
Troubleshooting
Error: CarlaUE4Editor not built / UE4 not built
Cause: the checkout is not built; this skill has no build step.
Solution: run [[build-carla-ue4]] against that checkout, then re-run the check.
Error: these FBX files sit directly in <dir> with no tag directory
Cause: the directory form needs <dir>/<Tag>/mesh.fbx.
Solution: move each mesh into a subdirectory named for its semantic tag, or
import it on its own with --tag.
Error: the editor produced no result
Cause: the editor died before finishing.
Solution: re-run with --verbose and read the first error, not the last.
Error: the import produced no StaticMesh
Cause: the FBX holds no static mesh geometry — skeletal-only, curves, or an
unreadable FBX version.
Solution: re-export as a static mesh FBX, with the origin of geometry at the
scene origin: that becomes the prop's anchor point.
Error: the import produced N static meshes and none was nominated
Cause: a multi-node FBX the importer could not merge, or --no-combine.
Solution: pass --mesh <object path> to choose one, or re-export as a single
mesh. Name collision hulls UCX_<MeshName> so they are absorbed rather than
imported as their own asset (P4).
Error: the editor reported success but no asset on disk at …
Cause: the import was rolled back or written elsewhere; the registry entry would
point at nothing.
Solution: re-run with --verbose; the first FBX error explains it.
Error: static.prop.<name> missing from the blueprint library
Cause: the registry entry is missing, or its path points at an asset that does
not exist (P1, P4).
Solution: check the registry file the importer printed. Note the id is
lowercased (P6).
Error: the prop spawns but semantic segmentation labels it None
Cause: a tag ATagger::GetLabelByFolderName does not recognise (P2).
Solution: re-import under a tag from the table above.
Outputs
Content/<Root>/Static/<Tag>/<Name>/<Mesh>.uasset — the imported mesh
(<Root> is Carla by default, or your --package name).Content/Carla/Config/Default.Package.json — the registration that makes each
prop spawnable as static.prop.<name>; with --package, it is
Content/<Name>/Config/<Name>.Package.json, which is also what
[[package-carla-ue4]] needs to export the package.Content/Carla/Blueprints/Props/PropFactory.uasset — the factory entry, unless
--no-factory or --package.