Animated Actors

Animated actors are skeletal-animated 3D characters (pedestrians, workers, etc.) that follow predefined waypoint paths in the simulation world. They are purely kinematic: they do not respond to external forces or interact with the physics engine, but they provide realistic visual motion through bone-driven animation (idle, walk, run).

They are included into collision detection and can be sensed by all visual, range or LiDAR sensors, though.

Actors use the same class/instance pattern as blocks: you first define reusable actor classes (<actor:class>), then instantiate them with per-instance overrides (<actor>).

Animated 3D Models

Actor animation relies on skeletal data embedded in the 3D model file (FBX, GLB, glTF, Collada, etc.). The model must contain at least one animation clip with bone keyframes.

A free set of animated human characters ready to use:

<model_uri>https://mrpt.github.io/mvsim-models/AnimatedMenCharacters.zip/FBX/Male_Casual.fbx</model_uri>
<model_uri>https://mrpt.github.io/mvsim-models/AnimatedWomenCharacters.zip/FBX/Female_Casual.fbx</model_uri>

Available models (you can download the ZIP files above and visualize locally):

Female_Alternative.fbx
Female_Casual.fbx
Female_Dress.fbx
Female_TankTop.fbx
Smooth_Female_Alternative.fbx
Smooth_Female_Casual.fbx
Smooth_Female_Dress.fbx
Smooth_Female_TankTop.fbx
Male_Casual.fbx
Male_LongSleeve.fbx
Male_Shirt.fbx
Male_Suit.fbx
Smooth_Male_Casual.fbx
Smooth_Male_LongSleeve.fbx
Smooth_Male_Shirt.fbx
Smooth_Male_Suit.fbx

The available animation clip names for this model pack are:

  • HumanArmature|Man_Clapping

  • HumanArmature|Man_Death

  • HumanArmature|Man_Idle

  • HumanArmature|Man_Jump

  • HumanArmature|Man_Punch

  • HumanArmature|Man_Run

  • HumanArmature|Man_RunningJump

  • HumanArmature|Man_Sitting

  • HumanArmature|Man_Standing

  • HumanArmature|Man_SwordSlash

  • HumanArmature|Man_Walk

Note

Animation clip names are model-specific. MVSim will log all discovered clip names at load time to help you find the correct strings.


Actor Class Definition

<actor:class name=”…”> defines a reusable actor template with default appearance, speed, and animation mapping. Multiple <actor> instances can share one class.

XML Configuration:

<actor:class name="pedestrian">
    <walking_speed>1.4</walking_speed>
    <running_speed>3.5</running_speed>
    <height>1.75</height>
    <collision_radius>0.3</collision_radius>
    <animation_idle>HumanArmature|Man_Idle</animation_idle>
    <animation_walk>HumanArmature|Man_Walk</animation_walk>
    <animation_run>HumanArmature|Man_Run</animation_run>
    <visual>
        <model_uri>https://mrpt.github.io/mvsim-models/AnimatedMenCharacters.zip/FBX/Male_Casual.fbx</model_uri>
        <model_scale>0.0027</model_scale>
        <model_roll>90.0</model_roll>
    </visual>
</actor:class>

Subtags:

  • <walking_speed> - Walking speed in m/s (default: 1.4)

  • <running_speed> - Running speed in m/s (default: 3.5)

  • <turning_rate> - Turning rate in deg/s (default: 120)

  • <height> - Character height in meters (default: 1.75). Used for the placeholder visual

  • <collision_radius> - Radius for collision shape in meters (default: 0.3)

  • <collision_height> - Height for collision shape in meters (default: 1.7)

  • <animation_idle> - Name of the idle animation clip in the 3D model

  • <animation_walk> - Name of the walking animation clip

  • <animation_run> - Name of the running animation clip

  • <visual> - 3D model specification (see World XML definition of VisualObject). Supports the standard subtags <model_uri>, <model_scale>, <model_offset_x>, etc.


Actor Instance

<actor name=”…” class=”…”> creates one actor in the world. Per-instance subtags override the class defaults. Each actor can define its own waypoint path.

XML Configuration:

<actor name="person1" class="pedestrian">
    <init_pose>5 10 0</init_pose>
    <path loop="true">
        <waypoint>5 10 0</waypoint>
        <waypoint>15 10 0</waypoint>
        <waypoint pause="2.0">15 10 180</waypoint>
        <waypoint animation="run">5 10 180</waypoint>
    </path>
</actor>

Attributes:

  • name - Unique name for the actor instance

  • class - Name of a previously defined <actor:class>

Subtags:

  • <init_pose> - Initial pose as x y yaw_deg (see World XML definition of Simulable entities)

  • Any <actor:class> subtag can be repeated here to override the class default

  • <path> - Waypoint path definition (see below)


Waypoint Paths

The <path> subtag defines a sequence of waypoints that the actor will follow automatically during the simulation.

Path attributes:

  • loop - "true" or "false". When true, the actor returns to the first waypoint after reaching the last one (default: true)

Waypoint format:

Each <waypoint> contains a pose string x y yaw_deg and optional attributes:

  • pause - Time in seconds to pause at this waypoint before continuing

  • animation - Override the automatic animation selection for the segment leading to this waypoint. Values: "walk" (default), "run", "idle"

Example — Looping patrol with a pause and a running segment:

<path loop="true">
    <waypoint>0 0 0</waypoint>
    <waypoint>20 0 0</waypoint>
    <waypoint pause="3.0">20 10 90</waypoint>
    <waypoint animation="run">0 10 180</waypoint>
    <waypoint>0 0 270</waypoint>
</path>

The actor automatically selects the appropriate animation clip (idle, walk, or run) based on its current movement speed. When paused at a waypoint, it plays the idle animation. The animation attribute on a waypoint forces a specific clip for the segment leading to that waypoint.


Animation State Machine

Each actor has an internal state machine that selects the active animation clip:

  • Idle — played when the actor is stationary or paused at a waypoint

  • Walking — played when moving at or below the walking speed

  • Running — played when moving above 80% of the running speed

Animation playback speed is automatically scaled to match actual movement velocity, so the walk cycle stays synchronized with the character’s ground speed.


Placeholder Visual

If no <visual> is defined (or the model file cannot be loaded), the actor is rendered as a simple cylinder+sphere placeholder whose dimensions are derived from <collision_radius> and <collision_height>.


Complete Example

<mvsim_world version="1.0">

    <actor:class name="pedestrian">
        <walking_speed>1.4</walking_speed>
        <animation_walk>HumanArmature|Man_Walk</animation_walk>
        <animation_idle>HumanArmature|Man_Idle</animation_idle>
        <animation_run>HumanArmature|Man_Run</animation_run>
        <visual>
            <model_uri>https://mrpt.github.io/mvsim-models/AnimatedMenCharacters.zip/FBX/Male_Casual.fbx</model_uri>
            <model_scale>0.0027</model_scale>
            <model_roll>90.0</model_roll>
        </visual>
    </actor:class>

    <actor name="walker1" class="pedestrian">
        <init_pose>0 0 0</init_pose>
        <path loop="true">
            <waypoint>0 0 0</waypoint>
            <waypoint>10 0 0</waypoint>
            <waypoint pause="2.0">10 5 90</waypoint>
            <waypoint>0 5 180</waypoint>
        </path>
    </actor>

    <actor name="runner1" class="pedestrian">
        <init_pose>-5 -5 45</init_pose>
        <path loop="true">
            <waypoint>-5 -5 45</waypoint>
            <waypoint animation="run">5 5 45</waypoint>
            <waypoint pause="1.0" animation="idle">5 5 225</waypoint>
            <waypoint animation="run">-5 -5 225</waypoint>
        </path>
    </actor>

</mvsim_world>