Struct MotionSynthesizer

The motion synthesizer is the actual core component of Kinematica.

Namespace: Unity.Kinematica
Syntax
public struct MotionSynthesizer : IDisposable
Remarks

The motion synthesizer represents the actual core implementation of Kinematica which can be used in a pure DOTS environment directly.

It provides a raw transform buffer which represents the current character pose and does not provide any infrastructure to feed the current pose to the character.

The motion synthesizer continuously "plays" an sequence of animation poses. The current time can be changed by "pushing" a new time to the synthesizer. Upon pushing a new time, the synthesizer automatically removes any deviations between the previous pose and the new pose.

The motion synthesizer also has a convenient method of creating semantic queries, which filter the poses stored in the motion library based on tags and markers.

Last but not least, the motion synthesizer contains a task graph that consist of a hierarchy of nodes that collectively can operate on a sequence of poses to perform a user defined processing step in order to arrive at a single new "push time" each frame.

Fields

trajectory

The trajectory model maintains a representation of the simulated character movement over the global time horizon.

Declaration
public TrajectoryModel trajectory
Field Value
Type Description
TrajectoryModel

Properties

Binary

Allows direct access to the underlying Kinematica runtime asset.

Declaration
public Binary Binary { get; }
Property Value
Type Description
Binary

BlendDuration

Return blend duration between segments in seconds

Declaration
public float BlendDuration { get; }
Property Value
Type Description
Single

CurrentVelocity

Velocity from binary at current sampling time, in meters per second, in character space

Declaration
public float3 CurrentVelocity { get; }
Property Value
Type Description
float3

deltaTime

Denotes the delta time in seconds during the last update.

Declaration
public float deltaTime { get; }
Property Value
Type Description
Single

IsDebugging

Declaration
public bool IsDebugging { get; }
Property Value
Type Description
Boolean

IsValid

Declaration
public bool IsValid { get; }
Property Value
Type Description
Boolean

Query

Introduces a new semantic query expression.

Declaration
public Query Query { get; }
Property Value
Type Description
Query
See Also

Time

Denotes the current sampling time of the motion synthesizer.

Declaration
public SamplingTime Time { get; }
Property Value
Type Description
SamplingTime

TrajectoryArray

Allows access to the trajectory of the motion synthesizer.

Declaration
public NativeSlice<AffineTransform> TrajectoryArray { get; }
Property Value
Type Description
NativeSlice<AffineTransform>
Remarks

The trajectory consists out of a series of transforms that correspond to the transform of the root joint over time.

The sampling frequency and length of the trajectory is defined by the sampling rate and time horizon respectively. Both parameters are defined as a global parameter in the runtime asset.

The trajectory covers a duration which is twice as long as the time horizon. The first half of the trajectory represents the past movement of the character, whereas the second half represents the future movement of the character.

All transforms stored in the trajectory are always relative to the current character root transform, i.e. the trajectory is maintained in character space.

WorldRootTransform

Denotes the world space root transform of the character.

Declaration
public AffineTransform WorldRootTransform { get; set; }
Property Value
Type Description
AffineTransform

Methods

AddCostRecordsToFrameDebugger(IFrameDebugProvider)

Declaration
public void AddCostRecordsToFrameDebugger(IFrameDebugProvider frameDebugProvider)
Parameters
Type Name Description
IFrameDebugProvider frameDebugProvider

AdjustTrajectory(AffineTransform, Boolean)

Allows for non-continuous root displacements.

Declaration
public void AdjustTrajectory(AffineTransform deltaTransform, bool bKeepPastTrajectoryInWorldSpace = false)
Parameters
Type Name Description
AffineTransform deltaTransform

Delta transform to be applied to the character root transform.
Boolean bKeepPastTrajectoryInWorldSpace

If true, past trajectory will stay at the same location in world space, otherwise it will follow the root transform
Remarks

This method can be used to teleport the character by utilizing a displacement transform.

ClearTrajectory(NativeSlice<AffineTransform>)

Declaration
public void ClearTrajectory(NativeSlice<AffineTransform> trajectory)
Parameters
Type Name Description
NativeSlice<AffineTransform> trajectory

CreateTrajectory(Allocator)

Declaration
public Trajectory CreateTrajectory(Allocator allocator)
Parameters
Type Name Description
Allocator allocator
Returns
Type Description
Trajectory

DebugPushGroup()

Declaration
public void DebugPushGroup()

DebugReadObject<T>(DebugReference)

Declaration
public T DebugReadObject<T>(DebugReference reference)
    where T : struct, IDebugObject
Parameters
Type Name Description
DebugReference reference
Returns
Type Description
T
Type Parameters
Name Description
T

DebugWriteBlittableObject<T>(ref T, Boolean)

Declaration
public DebugIdentifier DebugWriteBlittableObject<T>(ref T obj, bool dataOnly = false)
    where T : struct, IDebugObject
Parameters
Type Name Description
T obj
Boolean dataOnly
Returns
Type Description
DebugIdentifier
Type Parameters
Name Description
T

DebugWriteUnblittableObject<T>(ref T, Boolean)

Declaration
public DebugIdentifier DebugWriteUnblittableObject<T>(ref T obj, bool dataOnly = false)
    where T : struct, IDebugObject, Serializable
Parameters
Type Name Description
T obj
Boolean dataOnly
Returns
Type Description
DebugIdentifier
Type Parameters
Name Description
T

Dispose()

Declaration
public void Dispose()

FindClosestPoseAndTrajectoryMatch(PoseSet, SamplingTime, Trajectory, Single, Single)

Declaration
public SamplingTime FindClosestPoseAndTrajectoryMatch(PoseSet candidates, SamplingTime samplingTime, Trajectory trajectory, float trajectoryWeight = 0.5F, float maxDeviation = -1F)
Parameters
Type Name Description
PoseSet candidates
SamplingTime samplingTime
Trajectory trajectory
Single trajectoryWeight
Single maxDeviation
Returns
Type Description
SamplingTime

FindClosestPoseMatch(PoseSet, SamplingTime, Single)

Declaration
public SamplingTime FindClosestPoseMatch(PoseSet candidates, SamplingTime samplingTime, float maxPoseDeviation = -1F)
Parameters
Type Name Description
PoseSet candidates
SamplingTime samplingTime
Single maxPoseDeviation
Returns
Type Description
SamplingTime

GetFrameDebugInfo()

return the currently active animation frames

Declaration
public List<IFrameRecord> GetFrameDebugInfo()
Returns
Type Description
List<IFrameRecord>

GetTrajectoryDeltaTransform(Single)

Calculates the curent root displacement transform.

Declaration
public AffineTransform GetTrajectoryDeltaTransform(float deltaTime)
Parameters
Type Name Description
Single deltaTime

Delta time in seconds.
Returns
Type Description
AffineTransform

Root displacement transform at the current sampling time.

LoopSegmentIfEndReached(SamplingTime)

Declaration
public void LoopSegmentIfEndReached(SamplingTime samplingTime)
Parameters
Type Name Description
SamplingTime samplingTime

MatchPose(PoseSet, SamplingTime, MatchOptions, Single)

Declaration
public bool MatchPose(PoseSet candidates, SamplingTime samplingTime, MatchOptions options = MatchOptions.None, float maxPoseDeviation = -1F)
Parameters
Type Name Description
PoseSet candidates
SamplingTime samplingTime
MatchOptions options
Single maxPoseDeviation
Returns
Type Description
Boolean

MatchPoseAndTrajectory(PoseSet, SamplingTime, Trajectory, MatchOptions, Single, Single, Single)

Declaration
public bool MatchPoseAndTrajectory(PoseSet candidates, SamplingTime samplingTime, Trajectory trajectory, MatchOptions options = MatchOptions.None, float trajectoryWeight = 0.6F, float minTrajectoryDeviation = 0.03F, float maxTotalDeviation = -1F)
Parameters
Type Name Description
PoseSet candidates
SamplingTime samplingTime
Trajectory trajectory
MatchOptions options
Single trajectoryWeight
Single minTrajectoryDeviation
Single maxTotalDeviation
Returns
Type Description
Boolean

PlayAtTime(SamplingTime)

Switches the pose generation stream to read from the sampling time passed as argument.

Declaration
public void PlayAtTime(SamplingTime samplingTime)
Parameters
Type Name Description
SamplingTime samplingTime

New sampling time for the pose generation.
Remarks

Animation poses are always generated continuously based on a time index. This method allows to switch to a new starting time. The motion synthesizer automatically handles any discrepancies between the old and the new pose.

PlayAtTime(TimeIndex)

Switches the pose generation stream to read from the time index passed as argument.

Declaration
public void PlayAtTime(TimeIndex timeIndex)
Parameters
Type Name Description
TimeIndex timeIndex

New starting time index for the pose generation.
Remarks

Animation poses are always generated continuously based on a sampling time. This method allows to switch to a new starting time. The motion synthesizer automatically handles any discrepancies between the old and the new pose.

PlayFirstSequence(PoseSet)

Play the first sequence from 

queryResult

Declaration
public void PlayFirstSequence(PoseSet poseSet)
Parameters
Type Name Description
PoseSet poseSet
Remarks

This method accepts a query result (most likely obtained from a semantic query). It unconditionally extracts the first pose from the pose sequence and forwards it as the next sampling time to the internal pose stream generator.

See Also

Rewind(SamplingTime)

Retrieves the time index at the beginning of the interval that the sampling time passed as argument belongs to.

Declaration
public TimeIndex Rewind(SamplingTime samplingTime)
Parameters
Type Name Description
SamplingTime samplingTime

Sampling time for which the corresponding interval start time index should be calculated.
Returns
Type Description
TimeIndex
Remarks

This method can be used to "loop" time indices. 

[Trait, BurstCompile]
public struct Loop : Trait
{
    public void Execute(ref MotionSynthesizer synthesizer)
    {
        synthesizer.Push(synthesizer.Rewind(synthesizer.Time));
    }
}

Rewind(TimeIndex)

Retrieves the time index at the beginning of the interval that the time index passed as argument belongs to.

Declaration
public TimeIndex Rewind(TimeIndex timeIndex)
Parameters
Type Name Description
TimeIndex timeIndex

Time index for which the corresponding interval start time index should be calculated.
Returns
Type Description
TimeIndex
Remarks

This method can be used to "loop" time indices. 

[Trait, BurstCompile]
public struct Loop : Trait
{
    public void Execute(ref MotionSynthesizer synthesizer)
    {
        synthesizer.Push(synthesizer.Rewind(synthesizer.Time));
    }
}

SelectFirstPose(NativeArray<PoseSequence>)

Declaration
public TimeIndex SelectFirstPose(NativeArray<PoseSequence> sequences)
Parameters
Type Name Description
NativeArray<PoseSequence> sequences
Returns
Type Description
TimeIndex

SetWorldTransform(AffineTransform, Boolean)

Teleport character to a target transform

Declaration
public void SetWorldTransform(AffineTransform targetTransform, bool bKeepPastTrajectoryInWorldSpace = false)
Parameters
Type Name Description
AffineTransform targetTransform
Boolean bKeepPastTrajectoryInWorldSpace

If true, past trajectory will stay at the same location in world space, otherwise it will follow the root transform
Remarks

This method can be used to teleport the character by providing a target world transform

SteerRootMotion(Trajectory, Single, Single, Single, Single)

Returns the interpolated transform between the root delta transform from Kinematica binary for the current frame, and the desired delta transform.

Declaration
public AffineTransform SteerRootMotion(Trajectory desiredTrajectory, float translationWeight, float rotationWeight, float startSpeed = 0F, float endSpeed = 0.15F)
Parameters
Type Name Description
Trajectory desiredTrajectory

Desired trajectory that will be sampled from time 0 to 

_deltaTime
in order to compute the desired delta transform
Single translationWeight

Interpolation weight between the root delta position at 0, and the desired delta position at 1
Single rotationWeight

Interpolation weight between the root delta rotation at 0, and the desired delta rotation at 1
Single startSpeed

Root speed (m/s) at which steering will start to be effective, steering weight will then increase linearly as root speed increases toward 

endSpeed
Single endSpeed

Root speed (m/s) at which steering will be fully effective
Returns
Type Description
AffineTransform

Update(Single)

Update method that needs to be called each frame to advance the state of the motion synthesizer.

Declaration
public bool Update(float deltaTime)
Parameters
Type Name Description
Single deltaTime

Delta time in seconds.
Returns
Type Description
Boolean
Remarks

In a game object environment this method gets automatically called from the Kinematica component.

See Also

UpdateDebuggingStatus()

Declaration
public void UpdateDebuggingStatus()

See Also