Import a pedestrian 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.

python3 scripts/import_walker.py ~/models/SK_AfroBoy01_G3.fbx \
    --gender male --age child --generation 3 --speed 0.0,1.1,2.0

--gender, --age and --generation are required and asked of the user (step 0); --speed is optional, defaulting to the stock adult triple 0.0,1.7,4.0.

The FBX must be skinned to CARLA's GEN3 pedestrian rig — 26 crl_* bones. That is the whole contract: match it and the walker inherits ABP_GEN3 and every AS_*_G3 animation with no retargeting. Miss it and the import succeeds while the walker never moves, which is why the rig is checked before anything boots.

The result spawns exactly like a native CARLA pedestrian:

walker_bp = bp_lib.find('walker.pedestrian.0053')
walker = world.spawn_actor(walker_bp, world.get_random_location_from_navigation())
controller = world.spawn_actor(bp_lib.find('controller.ai.walker'),
                               carla.Transform(), attach_to=walker)
controller.start(); controller.go_to_location(world.get_random_location_from_navigation())

Pipeline, factory schema and constraints: references/walker_import.md.

Instructions

Walker Import Progress:
- [ ] Step 0: ASK THE USER for gender, age and generation (speed optional)
- [ ] Step 1: Check the INPUT FILE first — format, skinned, rig, textures
- [ ] Step 2: Check prerequisites — hand off to build-carla-ue4 on a build FAIL
- [ ] Step 3: Import — boot 1 builds the assets, boot 2 registers them
- [ ] Step 4: Verify it spawns, stands, and walks on a running server

Step 0: Ask the user for the attributes

Do this before anything else, every time. Do not infer them, do not carry them over from an earlier import, do not read them off the file name.

Three questions, and the import will not start without the answers — the CLI makes --gender, --age and --generation required precisely so this cannot be skipped:

ask	values	why it must be asked
gender	male / female / other	not derivable from a mesh at all
age	child / teenager / adult / elderly	height is measured and reported, but a 1.2 m mesh can be a child or a scaled adult
generation	1 / 2 / 3	3 is the GEN3 rig this skill imports; the user still chooses what the attribute claims

--speed is optional and defaults to 0.0,1.7,4.0 — the stock adult triple, and the same default CARLA's add_walker_to_walker_factory.py uses. Children and teenagers normally use 0.0,1.1,2.0; when the default contradicts the chosen age the importer says so rather than accepting it quietly. Ask for it only if the user cares about walking and running speed.

Every one of these is silent when wrong: nothing raises, the walker spawns happily, and the attribute is simply wrong for anyone filtering the blueprint library on gender, age or generation.

Step 1: Check the input file — ALWAYS FIRST

python3 scripts/check_input.py ~/models/SK_MyPed.fbx

Expected input, in one place:

requirement	detail
format	FBX, binary or ASCII. Nothing else is importable — .ma, .mb, .blend, .max, .c4d, .obj, USD, glTF, COLLADA all fail here
kind	a skinned/skeletal mesh. A static mesh is a prop, not a walker
rig	skinned to CARLA's GEN3 skeleton: exactly the 26 crl_* bones, no more and no fewer
textures	embedded (FBX export option "Embed Media") or texture files beside the FBX. Absolute paths from the author's machine resolve nowhere
contents	one character per file; animation is not needed and is not imported
units	authored in cm or m — the importer converts scene units

Exit codes: 0 usable, 1 rig mismatch, 2 unusable (wrong format, or not skinned).

[input] SK_AfroBoy01_G3_test.fbx  1313 KB
[input] PASS  binary FBX
[input] PASS  skinned, 26 crl_* bones
[input] PASS  rig is GEN3 — ABP_GEN3 and every AS_*_G3 animation apply as-is
[input] WARN  2 texture reference(s) are paths from another machine ...

The texture line is a warning, never fatal: the import proceeds and the walker comes out flat white. Nothing downstream can invent textures the file does not contain, so knowing it now saves judging a bad import later.

import_walker.py runs this itself and refuses on a 1 or 2, so running it alone is for triaging a file before committing to it.

Step 2: Check prerequisites

bash scripts/check_env.sh

Beyond a runnable editor, this checks the assets no step here can create — Skel__GEN3, ABP_GEN3, the donor blueprint, WalkerFactory — and whether the factory's pedestrian list is a member variable, which decides whether registration can be automatic (C1).

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.

There is no --package escape hatch here, unlike [[import-carla-prop]]: a walker is only spawnable through WalkerFactory, which is shared content. If Content/Carla is a symlink, the check says so — the walker will appear in every checkout that links it.

Step 3: Import

python3 scripts/import_walker.py ~/models/SK_AfroBoy01_G3.fbx \
    --gender male --age child --generation 3 --speed 0.0,1.1,2.0

The id is allocated for you: 4 digits, max + 1. Re-importing the same walker updates its existing entry in place instead of appending a duplicate. --id overrides.

Height is measured and reported as the visible height (unscaled bounds × the blueprint's mesh scale), with a note when it contradicts the chosen --age. The unscaled figure is ~1.84 m for every GEN3 mesh whatever the character, so only the scaled one means anything (C3).

Collision is inherited from the donor — mesh scale, capsule and offset are a generation-wide convention, not a fit to the mesh (C3). The importer warns when the new mesh's bounds drift more than 10% from the donor's, and names the overrides.

Materials are imported raw and reported per slot, with what is bound to each:

[walker] persisted  8 asset(s) saved in the mesh folder
[walker] materials  6 slots: 0 unassigned, 6 blank from the FBX, 0 taken from the donor
[walker]            - blinn1: blank FBX material - blinn1.blinn1
[walker] WARNING    6 slot(s) have no usable material — the walker renders FLAT WHITE.

An FBX that embeds no textures still declares material NAMES, so the import writes one blank white material per slot. Nothing can recover textures the file does not contain — check it first with strings file.fbx | grep -iE '\.(png|tga|jpg)'. --materials donor binds a donor's textured MI_* by slot name, which only looks right when the mesh shares the donor's UV layout; see C4 before trusting it.

Hair is inherited from the donor unless you say otherwise. The line reading hair ... (INHERITED from the donor) means this walker is wearing another character's hairstyle. --groom /Game/... sets it.

Other flags:

flag	why
--name	asset name; defaults to the FBX stem
--donor	which GEN3 blueprint to duplicate (default BP_Walker_AB001_G3)
--materials {none,donor}	donor binds materials by slot name; default imports raw
--capsule-half-height, --capsule-radius, --mesh-z, --mesh-scale	override the inherited GEN3 collision convention
--no-share-physics	do not reuse the donor's physics asset if the import made none
--wheelchair	set can_use_wheelchair on the definition
--id	force a 4-digit factory id instead of max + 1
--no-register	build the assets, leave WalkerFactory alone (not spawnable)
--register-only	register an already-built blueprint, skipping the import
--mesh	nominate one mesh when a multi-character FBX yields several
--verbose	stream the editor log instead of capturing it

The two boots

Boot 1 (-run=pythonscript) imports the mesh and builds the blueprint. Boot 2 (a full editor session) runs CARLA's own registration script:

Unreal/CarlaUE4/Plugins/CarlaTools/Content/Python/add_walker_to_walker_factory.py

The walker counterpart of add_vehicle_to_vehicle_factory.py: it appends the entry to WalkerFactory.Pedestrians and compiles + saves the blueprint through Kismet, which is what pressing Compile and Save does. It lives in the CARLA repo, not in this skill, and is runnable by hand:

UE4Editor CarlaUE4.uproject -ExecutePythonScript="add_walker_to_walker_factory.py \
    -w /Game/Carla/Blueprints/Walkers/BP_Walker_MyKid --gender male --age child \
    --generation 3 --speed 0.0,1.1,2.0"

Two boots rather than one because a failed import must never reach the factory, and because the commandlet cannot compile blueprints.

If the list is not a member variable the importer says so before spending the second boot and prints a paste-ready entry instead:

 REGISTRATION SKIPPED — no 'Pedestrians' member variable in WalkerFactory
    (Id="0053",Class=BlueprintGeneratedClass'"/Game/…/BP_Walker_X.BP_Walker_X_C"',
     Gender=Male,Age=Child,Speed=(0.000000,1.100000,2.000000),Generation=3,bCanUseWheelChair=False)

Exit code 3: the mesh and blueprint are built and correct, and one paste in Class Defaults finishes it. Promoting the list is a one-time content change (C1) after which this is fully automatic.

Step 4: Verify

Walkers need a running server. Assume one is already up — do not start one; if the connection fails, say so and let the user start it.

python3 scripts/verify_walker.py --id 0053

A server keeps content in memory from its startup, so it must be restarted after an import for the check to mean anything.

Four checks, because each catches a different way an import looks fine and is not:

check	what it catches
in the library and spawns	a missing or broken factory entry
get_bones() returns 26 crl_* bones	a blueprint whose SkeletalMesh is None
bounding-box bottom within 0.6 m of the road	a capsule/offset that does not fit this mesh
moves ≥ 0.3 m under an AI controller	a mesh the GEN3 animations do not drive

The ground check uses the bounding box, not the actor's z: a walker's origin is its capsule centre and a GEN3 capsule is 1.86 m around a 1.2 m body, so actor z against the road fails on stock walkers (C3).

--keep leaves the walker walking, for looking at it with a windowed server.

Examples

Example 1: a child pedestrian

User says: "add this kid FBX to CARLA as a pedestrian"

# step 0: ask gender / age / generation first
bash scripts/check_env.sh
python3 scripts/import_walker.py ~/models/SK_AfroBoy01_G3.fbx \
    --gender male --age child --generation 3 --speed 0.0,1.1,2.0
python3 scripts/verify_walker.py --id 0053      # after the user restarts the server

Example 2: an adult, default speed, its own hair

python3 scripts/import_walker.py ~/models/SK_EuroWoman04.fbx \
    --gender female --age adult --generation 3 \
    --groom /Game/Carla/Static/Hair/Hair_Types/AfroGirl_V01/twoTailAfro_eyebrows

Example 3: build now, register later

python3 scripts/import_walker.py ~/models/SK_Guard.fbx \
    --gender other --age adult --generation 3 --no-register
# later
python3 scripts/import_walker.py ~/models/SK_Guard.fbx --register-only \
    --name SK_Guard --gender other --age adult --generation 3

Troubleshooting

rig is NOT GEN3 / missing crl_... Cause: the FBX is skinned to a different skeleton. Solution: re-export skinned to the GEN3 rig, or retarget first. --skip-input-check imports anyway and gives a walker that cannot animate.

no skin cluster — this is not a skinned mesh Cause: the FBX holds static geometry. Solution: that is a prop — use [[import-carla-prop]].

the import produced no SkeletalMesh Cause: an unreadable FBX version, or curves/static data only. Solution: re-run with --verbose and read the first FBX error, not the last.

the mesh was bound to <X>, not Skel__GEN3 Cause: UE refused the existing skeleton, nearly always because bone names differ from what check_input.py compares (joint structure is not checked). Solution: compare the rig against Skel__GEN3 bone by bone.

REGISTRATION SKIPPED Cause: WalkerFactory's pedestrian list is still a function-local variable (C1). Solution: promote it once in the editor, or paste the emitted entry.

Walker spawns but is invisible Cause: the blueprint's SkeletalMesh is None, which is what a recompile after the CDO was written produces (C2). Solution: re-import.

Walker spawns but is flat white Cause: the FBX carries no textures, so every slot got a blank material (C4). Solution: re-export the FBX with Embed Media, supply the texture files, or --materials donor if the mesh shares the donor's UVs.

Walker floats above or sinks into the pavement Cause: the inherited capsule and mesh offset do not fit this mesh (C3). Solution: verify_walker.py reports the offset; re-run with --capsule-half-height / --mesh-z, or check the FBX scale.

Walker stands still while the controller runs Cause: the anim class is not ABP_GEN3, or the mesh is on a foreign skeleton. Solution: check the donor was a GEN3 walker; --donor selects another.

Walker does not ragdoll when killed Cause: no physics asset on the mesh. Solution: the import creates <Name>_PhysicsAsset; if it did not, the donor's is shared instead, and --no-share-physics disables even that.

Every walker load logs Failed to load .../GEN3/Nos_/AS_walkingG3 Cause: the stock GEN3 blueprints reference an animation absent from the shipped content. Harmless — ABP_GEN3 drives the walker. Solution: nothing to fix; the import clears that slot in its copy.

Outputs

• Content/Carla/Static/Pedestrian/<Name>/Meshes/SK_<Name>.uasset — the mesh, bound to Skel__GEN3. The Pedestrian folder is required: Tagger.cpp:32 derives the Pedestrians segmentation label from that folder name.
• …/Meshes/<Name>_PhysicsAsset.uasset — created by the import (ragdoll on death).
• …/Meshes/*.uasset — the FBX's own materials, one package per slot (C4).
• Content/Carla/Blueprints/Walkers/BP_Walker_<Name>.uasset — the walker, duplicated from the donor, repointed and resized.
• Content/Carla/Blueprints/Walkers/WalkerFactory.uasset — the entry that makes it spawnable as walker.pedestrian.<id>; untouched with --no-register or when the pedestrian list is not a member variable.