Improve KeyboardControlledThrustComponent

- Adopt AcceleratedValue
- Add TimeStep options
- Improve documentation and comments

Author: ShinryakuTako

Sources/OctopusKit/Components/Input/Keyboard/KeyboardControlledThrustComponent.swift

@@ -19,6 +19,10 @@ import GameplayKit
 @available(macOS 10.15, *)
 public final class KeyboardControlledThrustComponent: OctopusComponent, OctopusUpdatableComponent {
 
+    // TODO: Tests
+    
+    // DESIGN: A `resetAccelerationWhenChangingDirection` is probably not needed because the inertia and friction of the physics body should take care of that anyway, right?
+    
     public override var requiredComponents: [GKComponent.Type]? {
         [KeyboardEventComponent.self,
          PhysicsComponent.self,
@@ -30,77 +34,102 @@ public final class KeyboardControlledThrustComponent: OctopusComponent, OctopusU
     /// Change this to a different code to customize the keys.
     public var arrowDown:   UInt16 = .arrowDown
 
-    public var baseMagnitudePerSecond:      CGFloat
-    public var maximumMagnitudePerSecond:   CGFloat
-    public var acceleratedMagnitude:        CGFloat = 0
-    
-    /// The amount to increase `acceleratedMagnitude` by per second, while there is keyboard input. `acceleratedMagnitude` is reset to `baseMagnitudePerSecond` when there is no keyboard input.
-    public var accelerationPerSecond:       CGFloat
+    /// The amount of thrust to apply in a single update, with optional acceleration. Affected by `timestep`. Reset when there is no keyboard input.
+    public var magnitudePerUpdate:  AcceleratedValue<CGFloat>
 
     /// Multiplies the force by the specified value. Default: `1`. To reverse the thrust, specify a negative value like `-1`. To disable thrust, specify `0`.
-    public var factor:                      CGFloat = 1
+    public var scalingFactor:       CGFloat = 1
+    
+    /// Specifies a fixed or variable timestep for per-update changes.
+    public var timestep:            TimeStep
 
     /// - Parameters:
-    ///   - baseMagnitudePerSecond: The minimum magnitude to apply to the physics body every second.
-    ///   - maximumMagnitudePerSecond: The maximum magnitude to allow after acceleration has been applied.
-    ///   - accelerationPerSecond: The amount to increase the magnitude by per second, while there is keyboard input. The magnitude is reset to the `baseMagnitudePerSecond` when there is no keyboard input.
-    ///   - factor: Multiply the force by this factor. Default: `1`. To reverse the thrust, specify a negative value like `-1`. To disable thrust, specify `0`.
-    public init(baseMagnitudePerSecond:     CGFloat = 600,  // ÷ 60 = 10 per frame
-                maximumMagnitudePerSecond:  CGFloat = 1200, // ÷ 60 = 20 per frame
-                accelerationPerSecond:      CGFloat = 600,
-                factor:                     CGFloat = 1)
+    ///   - magnitudePerUpdate: The amount of thrust to apply every update, with optional acceleration. Affected by `timestep`.
+    ///   - scalingFactor: Multiplies the force by the specified factor. Default: `1`. To reverse the thrust, specify a negative value like `-1`. To disable thrust, specify `0`.
+    ///   - timestep: Specifies a fixed or variable timestep for per-update changes. Default: `.perSecond`
+    public init(magnitudePerUpdate: AcceleratedValue<CGFloat>,
+                scalingFactor:      CGFloat  = 1.0,
+                timestep:           TimeStep = .perSecond)
     {
-        self.baseMagnitudePerSecond     = baseMagnitudePerSecond
-        self.maximumMagnitudePerSecond  = maximumMagnitudePerSecond
-        self.accelerationPerSecond      = accelerationPerSecond
-        self.factor                     = factor
+        self.magnitudePerUpdate = magnitudePerUpdate
+        self.scalingFactor      = scalingFactor
+        self.timestep           = timestep
         super.init()
     }
 
+    /// - Parameters:
+    ///   - magnitudePerUpdate: The minimum magnitude to apply to the physics body every second. Affected by `timestep`.
+    ///   - acceleration: The amount to increase the magnitude by per second, while there is keyboard input. The magnitude is reset to the `baseMagnitudePerSecond` when there is no keyboard input. Affected by `timestep`.
+    ///   - maximum: The maximum magnitude to allow after acceleration has been applied.
+    ///   - scalingFactor: Multiplies the force by the specified factor. Default: `1`. To reverse the thrust, specify a negative value like `-1`. To disable thrust, specify `0`.
+    ///   - timestep: Specifies a fixed or variable timestep for per-update changes. Default: `.perSecond`
+    public convenience init(magnitudePerUpdate: CGFloat  = 600, // ÷ 60 = 10 per frame
+                            acceleration:       CGFloat  = 100,
+                            maximum:            CGFloat  = 900, // ÷ 60 = 15 per frame
+                            scalingFactor:      CGFloat  = 1,
+                            timestep:           TimeStep = .perSecond)
+    {
+        self.init(magnitudePerUpdate: AcceleratedValue<CGFloat>(base:    magnitudePerUpdate,
+                                                                current: magnitudePerUpdate,
+                                                                maximum: maximum,
+                                                                minimum: 0,
+                                                                acceleration: acceleration),
+                  scalingFactor: scalingFactor,
+                  timestep: timestep)
+    }
+    
     public required init?(coder aDecoder: NSCoder) { fatalError("init(coder:) has not been implemented") }
 
     @inlinable
     public override func update(deltaTime seconds: TimeInterval) {
 
+        // #0: If there is no input or valid entity for this frame, reset the acceleration and exit.
+        
         guard
             let keyboardEventComponent = coComponent(KeyboardEventComponent.self),
             !keyboardEventComponent.codesPressed.isEmpty,
             let node = entityNode,
             let physicsBody = coComponent(PhysicsComponent.self)?.physicsBody ?? node.physicsBody
             else {
-                acceleratedMagnitude = baseMagnitudePerSecond // TODO: PERFORMANCE: Figure out a better way than setting this every frame.
+                magnitudePerUpdate.reset() // TODO: PERFORMANCE: Figure out a better way than setting this every frame.
                 return
         }
 
-        // Did player press a directional arrow key?
+        // #1: Did player press a directional arrow key?
+        
         // ❕ NOTE: Don't use `switch` or `else` because we want to process multiple keypresses, to cancel out opposing directions.
 
         let codesPressed = keyboardEventComponent.codesPressed
         var direction: CGFloat = 0
 
-        if codesPressed.contains(self.arrowUp)    { direction += 1 } // ⬆️
-        if codesPressed.contains(self.arrowDown)  { direction -= 1 } // ⬇️
+        if codesPressed.contains(self.arrowUp)   { direction += 1 } // ⬆️
+        if codesPressed.contains(self.arrowDown) { direction -= 1 } // ⬇️
+        
+        // #2: Exit if multiple directional inputs cancel each other out, this prevents accumulation of acceleration when there is no movement.
+        
+        guard direction != 0 else {
+            magnitudePerUpdate.reset()
+            return
+        }
 
-        // Apply the force in relation to the node's current rotation.
+        // #3: Apply the force in relation to the node's current rotation.
 
-        var magnitudeForCurrentFrame = acceleratedMagnitude * CGFloat(seconds)
-        let vector = CGVector(radians: node.zRotation) * CGFloat(magnitudeForCurrentFrame * direction) * factor // TODO: Verify!
+        var magnitudeForCurrentFrame = timestep.applying(magnitudePerUpdate.current, deltaTime: CGFloat(seconds))
+        let vector = CGVector(radians: node.zRotation) * CGFloat(magnitudeForCurrentFrame * direction) * scalingFactor // TODO: Verify!
 
         // Apply the final vector to the body.
 
         #if LOGINPUTEVENTS
-        debugLog("acceleratedMagnitude: \(acceleratedMagnitude), magnitudeForCurrentFrame: \(magnitudeForCurrentFrame), factor: \(factor), rotation: \(node.zRotation), force: \(vector)")
+        debugLog("magnitudePerUpdate: \(magnitudePerUpdate), magnitudeForCurrentFrame: \(magnitudeForCurrentFrame), scalingFactor: \(scalingFactor), rotation: \(node.zRotation), force: \(vector)")
         #endif
 
         physicsBody.applyForce(vector)
 
-        // Apply acceleration for the next frame.
+        // #4: Apply acceleration for the next frame.
 
-        if  acceleratedMagnitude < maximumMagnitudePerSecond {
-            acceleratedMagnitude += (accelerationPerSecond * CGFloat(seconds))
-            if  acceleratedMagnitude > maximumMagnitudePerSecond {
-                acceleratedMagnitude = maximumMagnitudePerSecond
-            }
+        if  magnitudePerUpdate.isWithinBounds { // CHECK: PERFORMANCE
+            magnitudePerUpdate.update(timestep: timestep, deltaTime: CGFloat(seconds))
+            magnitudePerUpdate.clamp()
         }
     }
 }
@@ -109,7 +138,7 @@ public final class KeyboardControlledThrustComponent: OctopusComponent, OctopusU
 
 #if !canImport(AppKit)
 // TODO: Add support for iOS/tvOS keyboards.
-@available(iOS, unavailable)
+@available(iOS,  unavailable)
 @available(tvOS, unavailable)
 public final class KeyboardControlledThrustComponent: macOSExclusiveComponent {}
 #endif