Skip to main content

Scripts

Everything in the example project that is not code is generated: the map, the poses, the sounds, the effects — and a second map whose mounts are Blueprints. Eight Python scripts in Projects/MountingAndVehicles/Scripts/ build all of it from nothing, and a ninth measures the car. This page is what each one does, how to run it, and what it taught us — because each of them hit at least one thing that does not log an error and simply produces nothing.

All of them run from a command line against the example project. Two flavours:

# A commandlet: no window, no game tick. Enough for assets.
UnrealEditor-Cmd.exe <project>.uproject -run=pythonscript -script=Scripts/<name>.py -unattended -nosplash -NullRHI

# The full editor: Slate and Play In Editor available. Needed where noted.
UnrealEditor-Cmd.exe <project>.uproject -ExecCmds="py Scripts/<name>.py" -unattended -nosplash

They can also be run from the editor's Python console (py Scripts/<name>.py). Every script is safe to run again: it deletes and rebuilds what it owns and touches nothing else.

demo_level.py — the level, once​

The ground, the plaza and its six stations (car, car against a wall, low garage, turret, horse, truck and trailer), the circuit and the access road, the signs, the lighting, the exposure, and the two generated materials everything is painted with (M_DemoSurface, M_DemoGlass).

It is a module rather than a script because it builds both maps. build() takes a path and a table of six classes — vehicle, turret, horse, trailer, track, game_mode — and everything else about the level is the same whichever table it is given. That is the only way to be sure the C++ map and the Blueprint map are the same map: there is one of them.

It removes and respawns only the actors of the classes it was given, so hand-placed actors survive a rerun.

build_demo_map.py — the C++ map​

Thirty lines: load the six C++ classes and call demo_level.build. Run it as a commandlet.

Run it again whenever a class's root component layout changes — the horse became a Character at one point, and the copy already saved in the map kept its old component data and loaded at the origin with no seats. Respawning is the fix, and re-running this is the respawn.

build_seated_pose.py — three poses and an animation set​

Writes AS_MountSeated, AS_MountDriving and AS_MountRiding (thirty-frame single-pose sequences, solved from joint directions in the mannequin's component space) and DA_MountAnimations, the animation set whose three entries the framework scores per phase, role and mount tag. See Animation.md for the scoring and Example.md for why the riding entry names both roles.

Commandlet. The pose must be at least as long as the blend into it, or the blend never reaches it.

build_demo_audio.py — MetaSounds​

Writes MS_CarEngine and MS_CarDoor with the MetaSound builder API. The engine is a straight six built additively — the crank's harmonic series with the third order loudest and the half orders under it, a pulse-train exhaust, throttle-gated intake noise, a ladder filter, a compressor — and it exposes four inputs the car sets every frame: RPM, Throttle, Skid, Speed. The door is a click and a thump under two envelopes, with a Pitch input.

Commandlet. Three things to know:

  • MetaSoundBuilderSubsystem is an engine subsystem; the asset is written by MetaSoundEditorSubsystem.build_to_asset.
  • Node class names are (namespace, name, variant). Most are UE::<Name>::Audio|Float, but AD Envelope, Clamp and MapRange use their own name as namespace. When in doubt, add the node and list its pins; the script's Graph helper asserts on every pin it cannot find.
  • build_to_asset will not create over a name that exists — not even one deleted this session. The script overwrites an existing asset in place with build_and_overwrite_meta_sound instead, and gives each builder a fresh name, because builder names become registered class names.

build_demo_fx.py — Niagara​

Writes NS_TyreSmoke and NS_SkidMark and their materials. Niagara has no scripting API of its own for assembling emitters; the Cascade-to-Niagara converter does, and the script uses it — an empty emitter, engine modules added by path, inputs set by name, a renderer attached.

Full editor, not a commandlet: finalising an emitter builds its stack widgets, which need Slate. And the converter plugin is editor-only and enabled for the run rather than for the project:

UnrealEditor-Cmd.exe <project>.uproject -ExecCmds="py Scripts/build_demo_fx.py" -EnablePlugins=CascadeToNiagaraConverter -unattended -nosplash

An emitter built this way is invisible by default, four separate ways, none of which logs anything:

  • the conversion context starts disabled — set_enabled(True);
  • a fresh Emitter State loops once for a second — set Life Cycle Mode to Self and Loop Behavior to Infinite, or the component reports inactive before anyone looks;
  • a curve data interface made from script has its lookup table out of sync and evaluates to nothing — use Lerp_Float on Particles.NormalizedAge instead;
  • Scale Sprite Size fed from a scripted Vector2DFromFloat zeroes the sprites — set the size at spawn instead.

Attributes a module does not expose as inputs go through set_parameter_directly("Particles.X", ...); that is how the skid ribbon gets its up-facing vector.

bp_authoring.py — writing Blueprints from Python​

Not specific to this plugin: the layer between unreal.BlueprintGraphEditor, which speaks in nodes and pins, and a script that would rather say mul(a, b). A Blueprint adds components, variables and graphs; a Graph lays nodes out and wires them; every helper takes and returns either a literal or a Pin, so a chain of maths reads as a chain of calls.

Five things in it are load-bearing, and each was a crash or a silent wrong answer before it was a rule:

  • find_input_pin does not return None when there is no such pin. It returns an invalid pin struct, which is truthy — so every is None check written against it passes, and the failure surfaces much later as a connection that would not connect. is_valid() is the real question.
  • The arithmetic nodes have wildcard pins until something is plugged in. Multiply(B=0.6, A=pin) refuses the 0.6 while Multiply(A=pin, B=0.6) works, so the helper wires every connection first and sets every literal second, whatever order the caller wrote them in.
  • A Blueprint float is real. get_basic_type_by_name("float") is not an error: it is a warning in the log and an int variable, which then quietly rounds every number you put in it.
  • A call to the Blueprint's own function resolves against the skeleton class, SKEL_<Name>_C, in its own package. The generated class does not have the function until the compile at the end, and a call resolved against that one simply comes back as no such function.
  • Compile once, at the end, and save after that. A Get node for a component binds to the generated class that existed when it was made; compiling again throws that class away, and saving a Blueprint whose nodes point at a dead property asserts inside CoreUObject.

build_blueprint_demo.py — the same map, in Blueprint​

Writes six Blueprints into /Game/DemoBP — the car, the horse, the turret, the trailer, two wheels and a game mode — and then calls demo_level.build with them. Roughly nine hundred nodes in total, of which five hundred are the car.

Each run builds one Blueprint and stops. Run it until it writes the map:

Remove-Item -Recurse -Force Content\DemoBP, Content\Maps\Lvl_MountingDemo_BP.umap
do {
& UnrealEditor-Cmd.exe "<abs>\MountingAndVehicles.uproject" -run=pythonscript `
-script="<abs>\Scriptsuild_blueprint_demo.py" -unattended -nosplash
} until (Test-Path Content\Maps\Lvl_MountingDemo_BP.umap)

That is not a style choice. Two Blueprints built in one editor session that both override the same inherited interface event — Apply Driver Input, here — take the editor down on the second one, at a different node each time, in the interactive editor and in a commandlet alike. Each of these Blueprints builds perfectly on its own, so the build is resumable and the loop runs it to the end. It costs an editor start per Blueprint and nothing else.

Three more things this hit that do not announce themselves:

  • -script= wants an absolute path. A relative one is resolved against the engine's Binaries folder rather than the project, and the error names a file that was never there.
  • Collision is not BodyInstance.CollisionEnabled. Writing the enum into the body instance looks like it works and reads back correctly on the template — and is then thrown away, because the body reloads its collision from its profile and the profile still says block everything. On the car that was ninety colliders welded to a simulating chassis: it shook itself apart on the spot and would not pull away, while every number you could read said the collision was off. set_collision_profile_name("NoCollision") is the one that sticks.
  • Enhanced Input action events cannot be created from a script. create_node_from_name has no name for them. That is why the Blueprint map borrows the C++ character as its player.

tune_handling.py — the car, in numbers​

Starts Play In Editor, takes the pole car to open ground inside the circuit, and puts it through what a keyboard driver does: full lock at 60, 100 and 140 km/h held for a second and a half and released, a left-right flick at 100, a full brake from 120, a handbrake turn at 70. For each it reports the peak slip angle, the peak yaw rate, the heading gained with the key down, the heading it kept gaining after release, and the speed kept. The targets are in the script's header and in the report it writes to Saved/HandlingReport.txt:

slip while cornering    <= 6 deg      grip, not drift
overshoot after release <= 20 deg the car stops turning when you stop asking
yaw rate at 100 km/h >= 35 deg/s a tap of the key is a change of direction
speed kept, 1.5 s lock >= 80 % the corner does not scrub the car to a halt

Full editor. It sets Play settings to Standalone for the session and does not save them. Change a number in EDMountExampleVehicle.h or EDMountExampleWheel.cpp, build, run this, read the table: that is the whole loop, and it is the reason the car's handling is a set of measurements rather than a set of opinions.

Testing anything networked from Python​

A caution that applies to any script that pokes at the framework in Play In Editor: every call from Python into the engine runs under the editor's script-execution guard, and under it a Server RPC executes locally. A probe that calls RequestMount from Python on a client will see the server never seat anyone and conclude the framework is broken. It is not. Drive the game through real input instead — EnhancedInputLocalPlayerSubsystem.inject_input_vector_for_action on the client's local player — which is processed by the input system on the next tick, outside the guard.