PathPhysicsMotion

@MainActor
public class PathPhysicsMotion : Moveable, TempoDriven, PropertyCollection, PropertyDataDelegate, Identifiable

PathPhysicsMotion handles a single motion operation of a coordinate point along a CGPath using a physics system to update the value with a decaying velocity. It does not directly accept PropertyData objects, but instead transforms a value between 0.0 and 1.0, representing the length of the associated path. Using this value, it updates the current point on the path.

Public Properties

  • The delay, in seconds, before a motion operation begins.

    Warning

    Setting this parameter after a motion operation has begun has no effect.

    Declaration

    Swift

    @MainActor
public var delay: TimeInterval

  • An object conforming to the ValueAssistant protocol which acts as an interface for retrieving and updating value types.

    Remark

    Because PathMotion handles its own value interpolation along a path, it only uses the NumericAssistant.

    Declaration

    Swift

    @MainActor
public var valueAssistant: any ValueAssistant<TargetType>

  • An operation identifer is assigned to a motion instance when it is moving an object’s property (via initWithObject…) and its motion operation is currently in progress. (read-only)

    Remark

    This value returns 0 if no identifer is currently assigned.

    Declaration

    Swift

    @MainActor
private(set) public var operationID: UInt { get }

Identifiable conformance

  • id

    A unique identifier.

    Declaration

    Swift

    @MainActor
public let id: UUID

Physics properties

  • An object conforming to the PhysicsSolving protocol which solves position calculation updates.

    Remark

    By default, PathPhysicsMotion will assign an instance of PhysicsSystem to this property, but you can override this with your own custom physics system.

    Declaration

    Swift

    @MainActor
public var physicsSystem: PhysicsSolving

  • The current velocity used by the physics system to calculate motion values, measured in units per second.

    Remark

    If you wish to change the velocity after initially setting it via one of the init methods, use this setter. If you change the velocity directly on the physicsSystem object, the motionProgress property won’t be accurate.

    Declaration

    Swift

    @MainActor
public var velocity: Double { get set }

  • The current friction coefficient used by the physics system.

    Remark

    A value range between 0.0 and 1.0, with 1.0 representing very high friction and 0.0 representing almost no friction (setting this property to 0.0 will actually set it a bit fractionally higher than 0.0 to avoid divide-by-zero errors during calculations).

    Declaration

    Swift

    @MainActor
public var friction: Double { get set }

  • This value is used to determine whether the object modeled by the physics system has come to rest due to deceleration.

    Remark

    The way in which PhysicsSystem applies friction means that as velocity approaches 0.0, it will be assigned smaller and smaller fractional numbers, so we need a reasonable cutoff that approximates the velocity coming to rest. The default value is the constant DEFAULT_DECAY_LIMIT, which is fine for display properties, but you may prefer other values.

    Declaration

    Swift

    @MainActor
public var velocityDecayLimit: Double

  • Specifies a time step for the physics solver, which is updated independently of motion value updates. The default value calls the physics system 120 times a second, which provides double the precision if your app is rendering at 60 fps.

    Declaration

    Swift

    @MainActor
public var physicsTimerInterval: TimeInterval

Property collection methods

  • The collection of PropertyData instances, representing the object’s properties being moved. In a PathPhysicsMotion the only PropertyData instance stored represents the internal progress along the path. To obtain the motion’s current point along the path, subscribe to one of its update methods.

    Declaration

    Swift

    @MainActor
private(set) public var properties: [PropertyData<TargetType>] { get }

Motion state properties

  • The target object whose property should be moved.

    Declaration

    Swift

    @MainActor
private(set) public var targetObject: TargetType? { get }

  • An enum which represents the current movement state of the motion operation. (read-only)

    Declaration

    Swift

    @MainActor
private(set) public var motionState: MoveableState { get }

  • A MotionDirection enum which represents the current direction of the motion operation. (read-only)

    Declaration

    Swift

    @MainActor
private(set) public var motionDirection: MotionDirection { get }

  • A value between 0.0 and 1.0, which represents the current progress of a movement between two value destinations. (read-only)

    Remark

    Be aware that if this motion is isReversing or isRepeating, this value will only represent one movement. For instance, if a Motion has been set to repeat once, this value will move from 0.0 to 1.0, then reset to 0.0 again as the new repeat cycle starts. Similarly, if a Motion is set to reverse, this progress will represent each movement; first in the forward direction, then again when reversing back to the starting values.

    Declaration

    Swift

    @MainActor
private(set) public var motionProgress: Double { get set }

  • A value between 0.0 and 1.0, which represents the current progress of a motion cycle. (read-only)

    Remark

    A cycle represents the total length of a one motion operation. If isReversing is set to true, a cycle comprises two separate movements (the forward movement, which at completion will have a value of 0.5, and the movement in reverse which at completion will have a value of 1.0); otherwise a cycle is the length of one movement. Note that if isRepeating is true, each repetition will be a new cycle and thus the progress will reset to 0.0 for each repeat.

    Declaration

    Swift

    @MainActor
private(set) public var cycleProgress: Double { get set }

  • The amount of completed motion cycles. (read-only)

    Remark

    A cycle represents the total length of a one motion operation. If isReversing is set to true, a cycle comprises two separate movements (the forward movement and the movement in reverse); otherwise a cycle is the length of one movement. Note that if isRepeating is true, each repetition will be a new cycle.

    Declaration

    Swift

    @MainActor
private(set) public var cyclesCompletedCount: UInt { get }

  • A value between 0.0 and 1.0, which represents the current overall progress of the PathPhysicsMotion. This value should include all reversing and repeat motion cycles. (read-only)

    Remark

    If the motion is not repeating, this value will be equivalent to the value of cycleProgress.

    Declaration

    Swift

    @MainActor
public var totalProgress: Double { get }

Moveable protocol properties

  • A Boolean which determines whether a motion operation, when it has moved to the ending value, should move from the ending value back to the starting value.

    Declaration

    Swift

    @MainActor
public var isReversing: Bool

  • A Boolean which determines whether a motion operation should repeat. When set to true, the motion operation repeats for the number of times specified by the repeatCycles property. The default value is false.

    Note

    By design, setting this value to true without changing the repeatCycles property from its default value will cause the motion to repeat infinitely.

    Declaration

    Swift

    @MainActor
public var isRepeating: Bool

  • The number of motion cycle operations to repeat.

    Remark

    This property is only used when isRepeating is set to true. Assigning REPEAT_INFINITE to this property signals an infinite amount of motion cycle repetitions. The default value is REPEAT_INFINITE.

    Declaration

    Swift

    @MainActor
public var repeatCycles: UInt

  • Provides a delegate for updates to a Moveable object’s status, used by Moveable collections.

    Declaration

    Swift

    @MainActor
public var updateDelegate: MotionUpdateDelegate?

TempoDriven protocol properties

Notification closures

  • This closure is called when a motion operation starts.

    Remark

    This method can be chained when initializing the object.

    Seealso

    start

    Declaration

    Swift

    @discardableResult
@MainActor
public func started(_ closure: @escaping PathPhysicsMotionStarted) -> Self

  • This closure is called when a motion operation is stopped by calling the stop method.

    Remark

    This method can be chained when initializing the object.

    Seealso

    stop

    Declaration

    Swift

    @discardableResult
@MainActor
public func stopped(_ closure: @escaping PathPhysicsMotionStopped) -> Self

  • This closure is called when a motion operation update occurs and this instance’s motionState is moving.

    Remark

    This method can be chained when initializing the object.

    Seealso

    update(withTimeInterval:)

    Declaration

    Swift

    @discardableResult
@MainActor
public func updated(_ closure: @escaping PathPhysicsMotionUpdated) -> Self

  • This closure is called when a motion cycle has completed.

    Remark

    This method can be chained when initializing the object.

    Seealso

    repeating, cyclesCompletedCount

    Declaration

    Swift

    @discardableResult
@MainActor
public func cycleRepeated(_ closure: @escaping PathPhysicsMotionRepeated) -> Self

  • This closure is called when the motionDirection property changes to reversing.

    Remark

    This method can be chained when initializing the object.

    Seealso

    motionDirection, reversing

    Declaration

    Swift

    @discardableResult
@MainActor
public func reversed(_ closure: @escaping PathPhysicsMotionReversed) -> Self

  • This closure is called when calling the pause method on this instance causes a motion operation to pause.

    Remark

    This method can be chained when initializing the object.

    Seealso

    pause

    Declaration

    Swift

    @discardableResult
@MainActor
public func paused(_ closure: @escaping PathPhysicsMotionPaused) -> Self

  • This closure is called when calling the resume method on this instance causes a motion operation to resume.

    Remark

    This method can be chained when initializing the object.

    Seealso

    resume

    Declaration

    Swift

    @discardableResult
@MainActor
public func resumed(_ closure: @escaping PathPhysicsMotionResumed) -> Self

  • This closure is called when a motion operation has completed (or when all motion cycles have completed, if repeating is set to true).

    Remark

    This method can be chained when initializing the object.

    Declaration

    Swift

    @discardableResult
@MainActor
public func completed(_ closure: @escaping PathPhysicsMotionCompleted) -> Self

  • The object maintaining state on the path.

    Declaration

    Swift

    @MainActor
public private(set) var pathState: PathState { get }

  • This Boolean represents whether collision detections are active in the physics simulation. If true, collisions will be checked using the start and end properties of each PropertyData object passed in to the solve(forPositions:timestamp:) method. The default value is false.

    Declaration

    Swift

    @MainActor
public var useCollisionDetection: Bool { get set }

Initialization

  • A convenience initializer.

    Declaration

    Swift

    @MainActor
public convenience init(path: CGPath, configuration: PhysicsConfiguration, startPosition: Double? = nil, endPosition: Double? = nil, edgeBehavior: PathEdgeBehavior? = nil, options: MotionOptions? = MotionOptions.none)

    Parameters

    path

    A CGPath object to use as a motion guide.
    configuration

    A configuration model containing data to set up this object’s PhysicsSystem for physics calculations.
    startPosition

    An optional starting value, corresponding to a percentage along the path’s length where the motion should begin. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 0.0.
    endPosition

    An optional ending value, corresponding to a percentage along the path’s length where the motion should end. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 1.0.
    edgeBehavior

    Determines how path edges are handled during a motion when the motion attempts to travel past the path’s edges. This is rare, but can occur in some cases such as the EasingBack and EasingElastic easing equations. The default value is stopAtEdges.
    options

    An optional options model.

  • A convenience initializer.

    Declaration

    Swift

    @MainActor
public convenience init(pathState: PathState, configuration: PhysicsConfiguration, startPosition: Double? = nil, endPosition: Double? = nil, edgeBehavior: PathEdgeBehavior? = nil, options: MotionOptions? = MotionOptions.none)

    Parameters

    path

    A state object containing information about the path to use as a motion guide.
    configuration

    A configuration model containing data to set up this object’s PhysicsSystem for physics calculations.
    startPosition

    An optional starting value, corresponding to a percentage along the path’s length where the motion should begin. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 0.0.
    endPosition

    An optional ending value, corresponding to a percentage along the path’s length where the motion should end. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 1.0.
    edgeBehavior

    Determines how path edges are handled during a motion when the motion attempts to travel past the path’s edges. This is rare, but can occur in some cases such as the EasingBack and EasingElastic easing equations. The default value is stopAtEdges.
    options

    An optional options model.

  • The initializer.

    Declaration

    Swift

    @MainActor
public init(pathState: PathState, velocity: Double, friction: Double, restitution: Double? = nil, useCollisionDetection: Bool? = nil, startPosition: Double? = nil, endPosition: Double? = nil, edgeBehavior: PathEdgeBehavior? = nil, options: MotionOptions? = MotionOptions.none)

    Parameters

    path

    A state object containing information about the path to use as a motion guide.
    velocity

    The velocity used to calculate new values in the PhysicsSolving system. Any values are accepted due to the differing ranges of velocity magnitude required for various motion applications. Experiment to see what suits your needs best.
    friction

    The friction used to calculate new values in the PhysicsSolving system. Acceptable values are 0.0 (almost no friction) to 1.0 (no movement); values outside of this range will be clamped to the nearest edge.
    startPosition

    An optional starting value, corresponding to a percentage along the path’s length where the motion should begin. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 0.0.
    endPosition

    An optional ending value, corresponding to a percentage along the path’s length where the motion should end. The range must be between 0.0 and 1.0; values outside that range will be clamped to the minimum or maximum value. The default value is 1.0.
    edgeBehavior

    Determines how path edges are handled during a motion when the motion attempts to travel past the path’s edges. This is rare, but can occur in some cases such as the EasingBack and EasingElastic easing equations. The default value is stopAtEdges.
    options

    An optional options model.

Public methods

  • Adds a delay before the motion operation will begin.

    Declaration

    Swift

    @discardableResult
@MainActor
public func afterDelay(_ amount: TimeInterval) -> PathPhysicsMotion

    Parameters

    amount

    The number of seconds to wait.

    Return Value

    A reference to this PathPhysicsMotion instance, for the purpose of chaining multiple calls to this method.

  • Specifies that a motion cycle should repeat and the number of times it should do so. When no value is provided, the motion will repeat infinitely.

    Remark

    When this method is used there is no need to specify repeats in the options parameter of the init method.

    Seealso

    repeating, repeatCycles

    Declaration

    Swift

    @discardableResult
@MainActor
public func repeats(_ numberOfCycles: UInt = REPEAT_INFINITE) -> PathPhysicsMotion

    Parameters

    numberOfCycles

    The number of motion cycles to repeat. The default value is REPEAT_INFINITE.

    Return Value

    A reference to this PathPhysicsMotion instance, for the purpose of chaining multiple calls to this method.

  • Specifies that a motion, when it has moved to the ending value, should move from the ending value back to the starting value.

    Remark

    When this method is used there is no need to specify reverses in the options parameter of the init method.

    Seealso

    reversing, reverseEasing

    Declaration

    Swift

    @discardableResult
@MainActor
public func reverses() -> PathPhysicsMotion

    Return Value

    A reference to this PathPhysicsMotion instance, for the purpose of chaining multiple calls to this method.

  • setupPerformanceMode() Asynchronous

    Sets up performance mode, generating an internal lookup table for faster position calculations. To use the performance mode, this method must be used before calling start().

    Note

    With large paths, the lookup table generation could take a second or longer to complete. Be aware that the lookup table generation runs synchronously on another dispatch queue, blocking the return of this async call until the generation has completed. Be sure to call this method as early as possible to give the operation time to complete before your PathMotion needs to begin.

    Declaration

    Swift

    @MainActor
public func setupPerformanceMode() async

    Parameters

    lookupCapacity

    An optional capacity that caps the maximum lookup table amount.

  • Declaration

    Swift

    @MainActor
public func cleanupResources()

Moveable protocol methods

  • Declaration

    Swift

    @MainActor
public func update(withTimeInterval currentTime: TimeInterval)

  • Declaration

    Swift

    @discardableResult
@MainActor
public func start() -> Self

  • Declaration

    Swift

    @MainActor
public func stop()

  • Declaration

    Swift

    @MainActor
public func pause()

  • Declaration

    Swift

    @MainActor
public func resume()

  • Resets the motion to its initial state.

    Declaration

    Swift

    @MainActor
public func reset()

TempoDriven methods

TempoDelegate methods

  • Declaration

    Swift

    @MainActor
public func tempoBeatUpdate(_ timestamp: TimeInterval)

PropertyDataDelegate methods

  • Declaration

    Swift

    @MainActor
public func didUpdate(_ startValue: Double)