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.