Murl Engine Lua Addon API  Version 1.0 beta
Murl.Logic.ITimeline

The ITimeline interface.

The timeline is evaluated each logic tick using the IStepable interface.
A simple timeline is specified by a start/end time.
The timeline can be controlled by Start(), Pause() and Stop() calls.
All setters are taking effect immediately even if the timeline is running.

A more detailed timeline can use a loop start/end time, resulting in 3 phases:

  • Intro running from start to loop start time.
  • Loop running from loop start to loop end time several times.
  • Outro running from loop end to end time.

The number of loops specifies the counter for of the loop phase.
Endless looping can be achieved by setting number of loops to < 0.
If number of loops is 0 the loop start/end time is ignored which means the timeline simply runs from start to end time.
If the start time is equal to the loop start time the intro phase is skipped.
If the end time is equal to the loop end time the outro phase is skipped.


Table members

Methods


GetStepable()

Get the stepable interface. The ITimeline conforms to the IStepable interface.

Murl.SharedPointer.LogicIStepable GetStepable()

Returns
Murl.SharedPointer.LogicIStepable The stepable interface shared pointer.

SetAppTimeline(appTimeline)

Set the timeline callback object. The IAppTimeline::OnEvaluate() callback method is processed if the timeline's current time is set by IStepable::ProcessTick() or Rewind().

Boolean SetAppTimeline(Murl.SharedPointer.LogicIAppTimeline appTimeline)

Parameters
appTimelineThe timeline callback object.
Returns
Boolean true if successful.

Evaluate()

Evaluate the current time immediately. Process the IAppTimeline::OnEvaluate() callback method immediately. This method is rarely used after modifying the timeline's current time. This method is typically called when the timeline's current time was evaluated by IStepable::ProcessTick() within each logic tick. This method is called immediately by Reset(), ResetTo(), Rewind(), Start() with parameters and Stop() if auto rewind is enabled.

Evaluate()


Reset()

Reset the timeline. Stop the timeline, reset the WasRunning() state and call Rewind(). Finally Evaluate() is called.

Reset()


ResetTo(startTime)

Reset the timeline to a specified start time. Set the start time and call Reset(). Finally Evaluate() is called.

ResetTo(Number startTime)

Parameters
startTimeThe start time in seconds.

Start()

Start or continue the timeline. Reset the WasRunning() state. Does not modify the current time and loop.

Boolean Start()

Returns
Boolean true if successful.

Start(startTime, endTime)

Start the timeline with specified parameters. Set start/end time, calls Rewind() and Start(). Finally Evaluate() is called.

Boolean Start(Number startTime, Number endTime)

Parameters
startTimeThe start time in seconds.
endTimeThe end time in seconds.
Returns
Boolean true if successful.

Start(startTime, endTime, numberOfLoops)

Start the timeline with specified parameters. Set start/end time, number of loops, calls Rewind() and Start(). Finally Evaluate() is called.

Boolean Start(Number startTime, Number endTime, Integer numberOfLoops)

Parameters
startTimeThe start time in seconds.
endTimeThe end time in seconds.
numberOfLoopsNumber of loops.
Returns
Boolean true if successful.

Start(startTime, endTime, loopStartTime, loopEndTime, numberOfLoops)

Start the timeline with specified parameters. Set start/end time, loop start/end time, number of loops, calls Rewind() and Start(). Finally Evaluate() is called.

Boolean Start(Number startTime, Number endTime, Number loopStartTime, Number loopEndTime, Integer numberOfLoops)

Parameters
startTimeThe start time in seconds.
endTimeThe end time in seconds.
loopStartTimeThe loop start time in seconds.
loopEndTimeThe loop end time in seconds.
numberOfLoopsNumber of loops.
Returns
Boolean true if successful.

Pause()

Pause the timeline.

Boolean Pause()

Returns
Boolean true if timeline was paused, false if timeline is not running.

Stop()

Stop the timeline. Rewind() is called if auto rewind is enabled. Finally Evaluate() is called if auto rewind is enabled.

Boolean Stop()

Returns
Boolean true if timeline was stopped, false if timeline is already stopped.

Rewind()

Rewind the timeline. Sets the current time to the start time and the current loop to the start loop. Does not affect the current running state. Finally Evaluate() is called.

Boolean Rewind()

Returns
Boolean true if successful.

SetStartTime(startTime)

Set the start time.

SetStartTime(Number startTime)

Parameters
startTimeThe start time in seconds.

GetStartTime()

Get the start time.

Number GetStartTime()

Returns
Number The start time in seconds.

SetEndTime(endTime)

Set the end time.

SetEndTime(Number endTime)

Parameters
endTimeThe end time in seconds.

GetEndTime()

Get the end time.

Number GetEndTime()

Returns
Number The end time in seconds.

SetLoopStartTime(startTime)

Set the loop start time.

SetLoopStartTime(Number startTime)

Parameters
startTimeThe loop start time in seconds.

GetLoopStartTime()

Get the loop start time.

Number GetLoopStartTime()

Returns
Number The loop start time in seconds.

SetLoopEndTime(endTime)

Set the loop end time.

SetLoopEndTime(Number endTime)

Parameters
endTimeThe loop end time in seconds.

GetLoopEndTime()

Get the loop end time.

Number GetLoopEndTime()

Returns
Number The loop end time in seconds.

SetNumberOfLoops(numberOfLoops)

Set the number of loops.

SetNumberOfLoops(Integer numberOfLoops)

Parameters
numberOfLoopsNumber of loops.

GetNumberOfLoops()

Get the number of loops.

Integer GetNumberOfLoops()

Returns
Integer The number of loops.

SetTimeScale(timeScale)

Set the time scale factor. The recent tick duration is multiplied by the time scale factor and added to the current time each logic tick. The default time scale factor is 1.

SetTimeScale(Number timeScale)

Parameters
timeScaleThe time scale factor.

GetTimeScale()

Get the time scale factor.

Number GetTimeScale()

Returns
Number true The time scale factor.

SetAutoRewindEnabled(enabled)

Enable/disable automatic rewind. Automatic rewind is calling Rewind() when the timeline is stopped.

SetAutoRewindEnabled(Boolean enabled)

Parameters
enabledEnable automatic rewind if true.

IsAutoRewindEnabled()

Check if automatic rewind is enabled.

Boolean IsAutoRewindEnabled()

Returns
Boolean true if automatic rewind.

IsRunning()

Check if the timeline is running. A timeline can be started by calling Start() and stopped by calling Stop().

Boolean IsRunning()

Returns
Boolean true if running.

IsPaused()

Check if the timeline is paused. A timeline can be paused by calling Pause() and continued by calling Start().

Boolean IsPaused()

Returns
Boolean true if paused.

IsStopped()

Check if the timeline is stopped. A timeline can be stopped by calling Stop() and started by calling Start().

Boolean IsStopped()

Returns
Boolean true if stopped.

WasStarted()

Check if the timeline was started from stopped state.

Boolean WasStarted()

Returns
Boolean true if started.

WasRunning()

Check if the timeline has stopped running. If the timeline is stopped this state is true within the current logic tick only and will be cleared at the next logic tick.
(!) This state remains unchanged if the processor holding the timeline's observer is set to inactive within the current logic tick. In such a case the Reset() method can be called to clear the state.

Boolean WasRunning()

Returns
Boolean true if stopped.

IsOrWasRunning()

Check if the timeline is or was running. Returns (IsRunning() || WasRunning()) state.

Boolean IsOrWasRunning()

Returns
Boolean true if IsRunning() or WasRunning() is true.

HasPassedTime(time)

Check if the current time has passed a specified time within the most recent tick. Does not consider loops, for evaluating loops see HasPassedLoop().

Boolean HasPassedTime(Number time)

Parameters
timeThe time to check in seconds.
Returns
Boolean true if the current time has passed a specified time within the most recent tick.

HasPassedLoop(loop)

Check if the current loop has passed a specified loop number within the most recent tick. If the loop number to check is negative, true is returned each time the current loop has changed.

Boolean HasPassedLoop(Integer loop)

Parameters
loopThe loop number to check.
Returns
Boolean true if the current loop has passed a specified loop within the most recent tick.

GetCurrentTime()

Get the current time. This method does not consider loops, for evaluating loops see GetCurrentLoop().

Number GetCurrentTime()

Returns
Number The current time in seconds.

GetRemainingTime()

Get the remaining time. This method calculates GetEndTime() - GetCurrentTime() which does not consider loops, for evaluating loops see GetCurrentLoop().

Number GetRemainingTime()

Returns
Number The remaining time in seconds.

SetCurrentTime(time)

Set the current time. This method does not consider loops, for setting loops see SetCurrentLoop().

SetCurrentTime(Number time)

Parameters
timeThe current time to set in seconds.

GetCurrentLoop()

Get the current loop. The current loop provides the following information for n loops:

  • 0 Intro running from start to loop start time.
  • 1 .. n Loop running from loop start to loop end time.
  • n + 1 Outro running from loop end to end time.

Integer GetCurrentLoop()

Returns
Integer The current loop, 0 if number of loops is 0.

GetRemainingLoops()

Get the remaining loops. Calculates GetNumberOfLoops() - GetCurrentLoop().

Integer GetRemainingLoops()

Returns
Integer The remaining loops, -1 if number of loops is < 0, 0 if number of loops is 0 or intro/outro is running.

SetCurrentLoop(loop)

Set the current loop. The current loop represents the following information for n loops:

  • 0 Intro running from start to loop start time.
  • 1 .. n Loop running from loop start to loop end time.
  • n + 1 Outro running from loop end to end time.

Boolean SetCurrentLoop(Integer loop)

Parameters
loopThe current loop to set.
Returns
Boolean true if successful, false if the loop number is out of range.

GetCurrentState()

Get the current animation state.

Murl.IEnums.AnimationState GetCurrentState()

Returns
Murl.IEnums.AnimationState The current animation state.