Populate the scene with actors#
About Actor Movement System#
Actor Movement System, aka AMS, is an Unreal Engine plugin made by Parrot. It allows the end-user to put one or more moving targets into the scene and make them move along a given path.
These moving targets can be of several shapes. So far, human pedestrians and vehicles are supported.

Some UE4 applications coming with Parrot Sphinx include one
or several “paths”. For these apps, there is systematically
a path called DefaultPath
. By default, they are visible at run-time with
Unreal cameras.

The control of the plugin is done through the application’s command line. The next sections describe the available parameters to pass.
List available actors#
The command -list-actors
shows the available pedestrians and vehicles
that can be used. They are common for all UE4 applications.
$ parrot-ue4-empty -list-actors
== Available Characters ======================================
- Malcolm
- Stefani
- Jasper
==============================================================
== Available Vehicles ========================================
- Hatchback
- SUV
- Pickup
- SportsCar
- BoxTruck
==============================================================
List available paths#
The command -list-paths
shows the different paths predefined
in a given world level.
$ parrot-ue4-forest -level=main -list-paths
== Available Paths ===========================================
Path name : DefaultPath
==============================================================
Spawn actors#
The option -ams-path=
tells the plugin to spawn N moving targets along
the path called PathName
.
You can append several of this option in the same command line.
It is formatted as follows:
-ams-path=<PathName>,<Actor1[:<drone>]>[,<Actor2>,...]
Note
Once spawned, actors are automatically put in pause.
To make them move, set the Web dashboard parameter pause
to false
.
Here’s the command line to do that:
$ sphinx-cli param -m world actors pause false
When several actors are set in the same path, they will be spawned evenly all along the path so that the risk of collision gets reduced. That being said, if the actors do not have the same speed, collisions are likely to happen.
To have one actor being tracked by a drone, you need to append “:<drone_name>” after the name of the actor. The wildcard ‘*’ can be used if you do not want to bother with giving the right drone name. In that case, the first drone found in the simulation will be taken. Once an actor is tracked, its GPS and barometer information will be injected to the drone firmware at the place of the drone controller’s.
Example:
$ parrot-ue4-empty -ams-path="DefaultPath,Pickup:*" -ams-path=RunPath,Jasper
Note
It is not possible to assign a given drone to several actors at the same time. As a consequence, the wildcard ‘*’ should be used only once in the command line.
Warning
If you are using zsh, the wildcard ‘*’ must be escaped with ‘', or the whole string must be enclosed in double quotes (as in the example above).
The tracked actor always has a red marker above itself. The markers are kept invisible for all cameras belonging to the simulated drone.

If you want to spawn pedestrians and vehicles on the same path, pedestrians would be spawned before vehicles even if you write the vehicles names at first in the command line. This order was chosen to avoid any unwanted collision between a vehicle and a pedestrian because of their different speed.
For example:
$ parrot-ue4-empty -ams-path=DefaultPath,Pickup,SUV,Jasper,Malcolm

Take off from vehicle using AMS#
First you need to spawn a vehicle using AMS then you need to specify the name of that vehicle using the command line argument ::pose=
Command line example:
$ sphinx <my.drone>::pose="pickup" & parrot-ue4-empty -ams-path=DefaultPath,Pickup

Spawn drone near pedestrians#
First you need to spawn a pedestrian using AMS then you need to specify his name
using the command line argument ::pose=
, same thing as vehicles.
The drone are spawned 1 meter behind the selected pedestrian.
Command line example:
$ sphinx <my.drone>::pose="Jasper" & parrot-ue4-empty -ams-path=DefaultPath,Jasper

Note
All available spawn points for actors can be listed using the UE4 app’s
command line -list-spawn-points
.
More information HERE.
Lift actor’s hand#
In addition of standing, walking and running, a pedestrian can lift his right hand to a 90° angle.
First you need to spawn a pedestrian using AMS. Then using the web dashboard
(or sphinx-cli), you can set the parameter lift_hand
to raise/lower
the actor’s arm.
Note
The pedestrian must be paused to be able to lift his hand.
Here’s a command line example to set the lift_hand
parameter:
$ sphinx-cli param -m world actors lift_hand true

It’s also possible to land on the actor’s hand.

Change tracked actor#
If you have populated your scene with more than one actor, you can switch tracking from one to another.
First, you need to spawn more than one actor using AMS.
$ parrot-ue4-empty -ams-path="DefaultPath,Pickup:*" -ams-path=RunPath,Jasper
A description containing populated paths and their actors should appear once the simulation is launched.
== Paths details ===========================================
Path 'DefaultPath' includes Pickup_0
Path 'RunPath' includes Jasper_0
==============================================================
Now using the web dashboard (or sphinx-cli), you can set the
actor_to_track
parameter to change the tracked actor (or to start tracking
a new one).
Here’s a command line example to set the actor_to_track
parameter:
$ sphinx-cli param -m world actors actor_to_track Jasper_0
Customization of AMS#
You can customize some aspects of the AMS feature by bringing a YAML configuration file to UE4 app’s command line, as follows.
$ parrot-ue4-empty -config-file=</path/to/file.yaml>
Respecting the YAML format, an AMS configuration file could look like that:
Paths:
- Name: 'MyAwesomePath'
SplinePoints:
- 1.85 -9.5 0.4 Walk 15
- 15.76 -10.10 0.4 Run 20
- 17.635 0.85 0.4 Stop 5
- 17.02 12.03 0.4 Run 20
- 3.03 14.92 0.4 Walk 15
ClosedLoop: true
Tags:
- Name: 'MyAwesomeTag'
FilePath: '/path/to/MyAwesomeTag.png'
Width : 30
Height : 25
OffsetZ : 10
- Name: 'MyEvenMoreAwesomeTag'
FilePath: '/path/to/MyEvenMoreAwesomeTag.png'
Width : 50
Height : 30
OffsetX : 10
OffsetY : 5
OffsetZ : 20
Two element types can be modified: the paths and the vehicle tags.
Creating custom paths#
As shown in the configuration example, all path definitions belong to the same
dictionary entry Paths
. Each path definition must have the following fields:
Name
- The name of the path.Make sure that you don’t choose an already existing path name. You can use the command line
-list-paths
to visualize the existing paths.SplinePoints
- A list of the different waypoints of the path. Eachwaypoint is a string containing a location [x y z], an optional attitude, and an optional vehicle speed.
The location [x y z] is expressed in Gazebo’s coordinate system. You can use the Unreal app’s report window (key
P
) to visualize and retrieve the Gazebo coordinates of any desired point in the world.The optional attitude defines the behavior of the pedestrian beyond the related waypoint. It can be:
Walk
: Asks the pedestrian to walk (default value).Run
: Asks the pedestrian to run.Stop
: Asks the pedestrian to stop for 5 seconds then start walking towards the next waypoint.
The optional vehicle speed defines the new target speed in km/h for vehicles beyond the related waypoint. The default value is 15 km/h. The maximum speed for vehicles is 150 km/h.
Note
The proportional-integral-derivative controller (PID controller) used to control the vehicle speed is configured to converge relatively fast. Therefore, it is recommended to limit the speed variation between two successive waypoints.
ClosedLoop
- A boolean that defines whether the path is a closed loopor not.
To use the custom path given in the example above, just do like with the predefined paths:
$ parrot-ue4-empty -config-file=</path/to/file.yaml> -ams-path=MyAwesomePath,Jasper