feature: Add onAdvance hook into render loop to report advancing has …

…occurred

Adding a hook to report back the end of a render loop (as requested [here](rive-app/rive-react#186)). This will add consistency with iOS and Android callbacks too.

Diffs=
2de1f249c feature: Add onAdvance hook into render loop to report advancing has occurred (#5520)

Co-authored-by: Zachary Plata <[email protected]>

.rive_head

@@ -1 +1 @@
-1292ebe56e5996ed2baec99732d630651f00cec0
+2de1f249c61ee0d1beef0ff6e10752f0a4d4ad3a

js/src/rive.ts

@@ -761,6 +761,13 @@ class Animator {
       });
     }
   }
+
+  public handleAdvancing(time: number) {
+    this.eventManager.fire({
+      type: EventType.Advance,
+      data: time,
+    });
+  }
 }
 
 // #endregion
@@ -778,13 +785,14 @@ export enum EventType {
   Stop = "stop",
   Loop = "loop",
   Draw = "draw",
+  Advance = "advance",
   StateChange = "statechange",
 }
 
 // Event fired by Rive
 export interface Event {
   type: EventType;
-  data?: string | string[] | LoopEvent;
+  data?: string | string[] | LoopEvent | number;
 }
 
 /**
@@ -944,6 +952,7 @@ export interface RiveParameters {
   onStop?: EventCallback;
   onLoop?: EventCallback;
   onStateChange?: EventCallback;
+  onAdvance?: EventCallback;
   /**
    * @deprecated Use `onLoad()` instead
    */
@@ -1071,6 +1080,7 @@ export class Rive {
     if (params.onLoop) this.on(EventType.Loop, params.onLoop);
     if (params.onStateChange)
       this.on(EventType.StateChange, params.onStateChange);
+    if (params.onAdvance) this.on(EventType.Advance, params.onAdvance);
 
     /**
      * @deprecated Use camelCase'd versions instead.
@@ -1382,6 +1392,9 @@ export class Rive {
     // Check for any state machines that had a state change
     this.animator.handleStateChanges();
 
+    // Report advanced time
+    this.animator.handleAdvancing(elapsedTime);
+
     // Add duration to create frame to durations array
     this.frameCount++;
     const after = performance.now();
@@ -1511,6 +1524,9 @@ export class Rive {
       });
       return;
     }
+    if (this.eventCleanup) {
+      this.eventCleanup();
+    }
     this.animator.pause(animationNames);
   }
 

js/test/rive.test.ts

@@ -615,6 +615,26 @@ test("Stop events are received", (done) => {
   });
 });
 
+test("Advance events are received", (done) => {
+  const canvas = document.createElement("canvas");
+  let hasAdvancedOnce = false;
+  new rive.Rive({
+    canvas: canvas,
+    buffer: oneShotRiveFileBuffer,
+    autoplay: true,
+    onAdvance: (event) => {
+      expect(event.type).toBe(rive.EventType.Advance);
+      if (hasAdvancedOnce) {
+        expect(event.data).toBeGreaterThan(0);
+        done();
+      }
+      if (!hasAdvancedOnce) {
+        hasAdvancedOnce = true;
+      }
+    },
+  });
+});
+
 test("Events can be unsubscribed from", (done) => {
   const canvas = document.createElement("canvas");
 
@@ -1025,6 +1045,35 @@ test("Playing state machines report when states have changed", (done) => {
   });
 });
 
+test("Advance event is not triggered when state machine is paused", (done) => {
+  const canvas = document.createElement("canvas");
+  const hasAdvancedMock = jest.fn();
+
+  const r = new rive.Rive({
+    canvas: canvas,
+    buffer: stateMachineFileBuffer,
+    artboard: "MyArtboard",
+    stateMachines: "StateMachine",
+    autoplay: true,
+    onPlay: () => {
+      setTimeout(() => {
+        r.pause();
+      }, 100);
+    },
+    onPause: () => {
+      const advancedCallbackCount = hasAdvancedMock.mock.calls.length;
+      setTimeout(() => {
+        // Rive draws one more frame before pausing at the end of a render loop
+        expect(hasAdvancedMock.mock.calls.length).toBe(
+          advancedCallbackCount + 1
+        );
+        done();
+      }, 50);
+    },
+    onAdvance: hasAdvancedMock,
+  });
+});
+
 // #endregion
 
 // #region scrubbing