Path: MoveAlongSectionWithDistance

Moves an object along a specified section of a path for a specific distance at a given speed and direction. A callback function is optionally invoked when the object finishes moving the requested distance.

This function is ideal for scenarios where precise movement control is needed — such as partial travel along a path, testing distances, or breaking long segments into smaller animated portions.

Note: This function currently supports metric units only (e.g., meters), regardless of the project’s unit setting.

Function

void MoveAlongSectionWithDistance(
    sectionId: integer, 
    obj: object, 
    speed: number, 
    acceleration: number, 
    deceleration: number, 
    backward: boolean, 
    distance: double, 
    callback: function)

void MoveAlongSectionWithDistance(
    sectionId: integer, 
    obj: object, 
    speed: number, 
    acceleration: number, 
    deceleration: number, 
    backward: boolean, 
    distance: double, 
    callback: function, 
    resetAfterFinished: boolean)

Parameters

Name Type Description
sectionId Integer The 1-based index of the section within the path that the object should follow
obj Object The object to be moved
speed Number The maximum speed (in meters per second) the object will reach during movement
acceleration Number The rate at which the object accelerates from 0 to the specified speed
deceleration Number The rate at which the object decelerates from its current speed to 0
backward Boolean If true, the object moves in reverse along the section
distance Double The distance (in meters) the object should move along the section
callback Function Callback function that will be called when the movement is complete. Pass null if no callback is required.

There is only one callback per path! Subsequent calls to this function will overwrite the callbacks previously passed, and passing null will remove a previously registered callback.
resetAfterFinished Boolean (Optional) Whether the object should reset its position on the section once movement completes. If true, future movement along the same section will begin from the start. Default is false

Return Value

None. Movement is asynchronous, and completion is signaled through the optional callback

Example

var path1;
var path2;
var ob1;
var ob2;

function OnSimulationStart()
{
    LogDebug("OnSimulationStart called");
    
    ob1 = GetComponentByNameAndType ('BasicShape1', "Basic Shape");
    ob2 = GetComponentByNameAndType ('BasicShape2', "Basic Shape");
    
    path1 = GetComponentByNameAndType ('Path1', "Path");
    path2 = GetComponentByNameAndType ('Path2', "Path");
    
    path1.MoveAlongSectionWithDistance(1, ob1, 10.0, 0.0, 0.0, false,10.0, Noop);
    path2.MoveAlongSectionWithDistance(1, ob2, 5.0, 0.0, 0.0, true,7.0, Noop); 
}

function Noop(sender,sectionID,object,backward)
{
    LogDebug("Noop: " + index);
    LogDebug("X: " + object.X + " Y: " + object.Y + " Z: " + object.Z); 
}

Another example:

var path1;
var ob1;

function OnSimulationStart()
{
    LogDebug("OnSimulationStart called");
    
    ob1 = GetComponentByNameAndType ('BasicShape1', "Basic Shape"); 
    path1 = GetComponentByNameAndType ('Path1', "Path");
    
    path1.MoveAlongSectionWithDistance(1, ob1, 10.0, 0.0, 0.0, false,10.0, null);
}