OrbitAnimation

OrbitAnimation describes an orbital (revolution) animation of an object moving around a given axis.

It moves an object, starting from startTransform, along a circular path whose plane normal is defined by axis. Over the configured duration (from the factory method or parent class), the object completes rotationCount full revolutions (1.0 = 360°, 2.0 = 720°, etc.).

Runtime behavior:

1. The orbit radius equals the magnitude of the component of startTransform.position that is perpendicular to axis.

2. The plane of motion is perpendicular to axis (axis is normalized internally).

3. rotationCount determines how many full circles are completed within the animation's total duration.

4. If orientToPath = true, the object's forward direction will continuously align to the tangent of the path (i.e., "faces travel direction"). Otherwise, only position changes.

5. spinClockwise toggles the direction of revolution (exact visual interpretation depends on your engine's handedness).

Typical use cases:

• Planet / satellite orbit visualization

• Camera orbiting around a focus object

• Decorative circular motion in UI / 3D scenes

Value & behavior notes:

• rotationCount = 1f -> one full revolution (360°).

• rotationCount = 2.5f -> two and a half revolutions (900°).

• rotationCount = 0f usually means "no orbit" (unless your framework gives it special meaning).

• A zero vector axis (0,0,0) is invalid—avoid it.

Example: Suppose you want a model (a "satellite") starting at position (2, 0, 0) to revolve counter-clockwise around the Y axis, completing 2 full orbits over 4 seconds, always facing along its path, with a 0.5s start delay, looping:

val orbit = OrbitAnimation.createOrbitAnimation(
    name = "SatelliteOrbit",
    duration = 4f,                      // 4 seconds total
    axis = Vector3(0f, 1f, 0f),         // Orbit around Y axis
    startTransform = Transform(
        position = Vector3(2f, 0f, 0f)  // Radius ≈ 2
    ),
    spinClockwise = false,              // Counter‑clockwise (depends on coordinate system)
    orientToPath = true,                // Face travel direction
    rotationCount = 2f,                 // Two full revolutions (720°)
    delay = 0.5f,                       // Start after 0.5s
    repeatMode = RepeatMode.RESTART,    // Loop from beginning
    repeatCount = -1                    // Loop indefinitely
)

val resource = AnimationResource.generate(orbit)
// Effect: The object circles the origin on the XZ plane twice in 4s, reorients to tangent,
// then restarts, creating a continuous orbital loop.