fix(Replay): improve finish detection (#425)

* chore(build): bump jest and ts-jest, and run yarn upgrade

* feat(Replay): add timeInMilliseconds getter for Event

* fix(Replay): improve finish detection

Fixes many edge cases (such as finishing with flower + apple,
or escing/dying at flower), and improves multi rec handling.

Added new tests with recs featuring these edge cases.

* fix(tests): fix ReplayFinishStateReason in old tests

Due to handling flower+apple finishes properly now, EventType.Apple
as last event doesn't count as NoTouch anymore for these cases.

Author: makitalo

__tests__/assets/replays/14be1756wow.rec

@@ -135,6 +135,28 @@ describe('Replay', () => {
     });
   });
 
+  test('getTime, finished, single, flower and apple', async () => {
+    const filePath = '__tests__/assets/replays/14be1756wow.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: true,
+      reason: ReplayFinishStateReason.Touch,
+      time: 17566,
+    });
+  });
+
+  test('getTime, finished, single, large framediff', async () => {
+    const filePath = '__tests__/assets/replays/22edahl4219.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: true,
+      reason: ReplayFinishStateReason.Touch,
+      time: 42199,
+    });
+  });
+
   test('getTime, finished, multi', async () => {
     const filePath = '__tests__/assets/replays/rec_valid_2.rec';
     const file = await readFile(filePath);
@@ -146,6 +168,50 @@ describe('Replay', () => {
     });
   });
 
+  test('getTime, finished, multi, wait 1', async () => {
+    const filePath = '__tests__/assets/replays/multi_finished_p1_waits_at_flower.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: true,
+      reason: ReplayFinishStateReason.Touch,
+      time: 8294,
+    });
+  });
+
+  test('getTime, finished, multi, wait 2', async () => {
+    const filePath = '__tests__/assets/replays/multi_finished_p2_waits_at_flower.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: true,
+      reason: ReplayFinishStateReason.Touch,
+      time: 7815,
+    });
+  });
+
+  test('getTime, finished, multi, p1 flower and p2 groundtouch', async () => {
+    const filePath = '__tests__/assets/replays/40MarAbu.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: true,
+      reason: ReplayFinishStateReason.Touch,
+      time: 37090,
+    });
+  });
+
+  test('getTime, finished, multi, large framediff', async () => {
+    const filePath = '__tests__/assets/replays/53x813.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: true,
+      reason: ReplayFinishStateReason.Touch,
+      time: 8139,
+    });
+  });
+
   test('getTime, unfinished, no event', async () => {
     const filePath = '__tests__/assets/replays/unfinished.rec';
     const file = await readFile(filePath);
@@ -168,13 +234,24 @@ describe('Replay', () => {
     });
   });
 
+  test('getTime, unfinished, single, esc', async () => {
+    const filePath = '__tests__/assets/replays/esc_at_flower.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: false,
+      reason: ReplayFinishStateReason.NoTouch,
+      time: 4867,
+    });
+  });
+
   test('getTime, unfinished, multi, event', async () => {
     const filePath = '__tests__/assets/replays/multi_event_unfinished.rec';
     const file = await readFile(filePath);
     const rec = Replay.from(file);
     expect(rec.getTime()).toEqual({
       finished: false,
-      reason: ReplayFinishStateReason.NoTouch,
+      reason: ReplayFinishStateReason.FrameDifference,
       time: 1600,
     });
   });
@@ -190,13 +267,46 @@ describe('Replay', () => {
     });
   });
 
+  test('getTime, unfinished, multi, no event', async () => {
+    const filePath = '__tests__/assets/replays/multi_unfinished_no_events.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: false,
+      reason: ReplayFinishStateReason.NoTouch,
+      time: 133,
+    });
+  });
+
+  test('getTime, unfinished, multi, esc 1', async () => {
+    const filePath = '__tests__/assets/replays/multi_unfinished_p1_escs_at_flower.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: false,
+      reason: ReplayFinishStateReason.NoTouch,
+      time: 4300,
+    });
+  });
+
+  test('getTime, unfinished, multi, esc 2', async () => {
+    const filePath = '__tests__/assets/replays/multi_unfinished_p2_escs_at_flower.rec';
+    const file = await readFile(filePath);
+    const rec = Replay.from(file);
+    expect(rec.getTime()).toEqual({
+      finished: false,
+      reason: ReplayFinishStateReason.NoTouch,
+      time: 8067,
+    });
+  });
+
   test('getTime, unfinished, single, event, framediff', async () => {
     const filePath = '__tests__/assets/replays/event_unfinished.rec';
     const file = await readFile(filePath);
     const rec = Replay.from(file);
     expect(rec.getTime()).toEqual({
       finished: false,
-      reason: ReplayFinishStateReason.NoTouch,
+      reason: ReplayFinishStateReason.FrameDifference,
       time: 8567,
     });
   });

__tests__/assets/replays/22edahl4219.rec

@@ -41,9 +41,9 @@
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-prettier": "^4.0.0",
     "fs-extra": "^9.0.1",
-    "jest": "^24.7.1",
+    "jest": "^25.0.0",
     "prettier": "^2.0.5",
-    "ts-jest": "^24.0.2",
+    "ts-jest": "^25.0.0",
     "ts-loader": "^9.2.6",
     "typedoc": "^0.22.4",
     "typescript": "^4.0.2",

__tests__/assets/replays/40MarAbu.rec

@@ -10,6 +10,10 @@ export default class Event {
     this.touchInfo = 0;
     this.groundInfo = 0;
   }
+
+  get timeInMilliseconds(): number {
+    return this.time * (0.001 / (0.182 * 0.0024)) * 1000;
+  }
 }
 
 export enum EventType {

__tests__/assets/replays/53x813.rec

@@ -111,19 +111,20 @@ export default class Replay {
 
     let offset = 0;
     for (let i = 0; i < numEvents; i++) {
-      const time = buffer.readDoubleLE(offset);
+      const event = new Event();
+      event.time = buffer.readDoubleLE(offset);
       offset += 8;
-      const touchInfo = buffer.readInt16LE(offset);
+      event.touchInfo = buffer.readInt16LE(offset);
       offset += 2;
-      const type = buffer.readUInt8(offset);
+      event.type = buffer.readUInt8(offset);
       offset += 2; // 1 + 1 padding
-      const groundInfo = buffer.readFloatLE(offset);
+      event.groundInfo = buffer.readFloatLE(offset);
       offset += 4;
-      if (type < 0 || type > 7) {
-        throw new Error(`Invalid event type value=${type} at event offset=${offset}`);
+      if (event.type < 0 || event.type > 7) {
+        throw new Error(`Invalid event type value=${event.type} at event offset=${offset}`);
       }
 
-      events.push({ time, touchInfo, type, groundInfo });
+      events.push(event);
     }
 
     return events;
@@ -230,49 +231,121 @@ export default class Replay {
    * Get time of replay in milliseconds.
    */
   public getTime(): FinishState {
-    // First check if last event was a touch event in ride(s) event data.
-    const lastEvent = this.rides.reduce((prev: undefined | Event, ride) => {
-      const prevTime = prev ? prev.time : 0;
-      const lastRideEvent = ride.events.length > 0 ? ride.events[ride.events.length - 1] : undefined;
-      const lastRideEventTime = lastRideEvent ? lastRideEvent.time : 0;
-      if (lastRideEventTime > prevTime) {
-        return lastRideEvent;
-      }
-      return prev;
+    // First get the last event of (each) ride.
+    const lastEvents = this.rides.map((ride) =>
+      ride.events.length > 0 ? ride.events[ride.events.length - 1] : undefined,
+    );
+
+    // Time of each ride's last event, in milliseconds.
+    const lastEventTimes = lastEvents.map((event: undefined | Event) => (event ? event.timeInMilliseconds : undefined));
+
+    // Time of the final event(s) (= the event(s) with the highest time), in milliseconds.
+    const finalEventTime = lastEventTimes.reduce((prev: undefined | number, time: undefined | number) => {
+      if (!prev) {
+        return time;
+      } else if (!time) {
+        return prev;
+      } else return time > prev ? time : prev;
     }, undefined);
 
-    // Highest frame time.
-    const maxFrames = this.rides.reduce((prev, ride) => {
-      return ride.frames.length > prev ? ride.frames.length : prev;
+    // Get all Touch/Apple events with finalEventTime. Other events with finalEventTime are filtered out.
+    // (For example player 2 might have a GroundTouch event with the same time as player 1's flower Touch.)
+    const finalEvents = <Event[]>[];
+    for (const ride of this.rides) {
+      const touchOrAppleEvents = ride.events.filter(
+        (event) =>
+          event.timeInMilliseconds === finalEventTime &&
+          (event.type === EventType.Touch || event.type === EventType.Apple),
+      );
+      finalEvents.push(...touchOrAppleEvents);
+    }
+
+    // Time of each ride's last frame, in milliseconds.
+    const FrameDuration = 1000 / 30.0;
+    const lastFrameTimes = this.rides.map((ride) => ride.frames.length * FrameDuration);
+
+    // Highest frame time, in milliseconds.
+    const finalFrameTime = lastFrameTimes.reduce((prev, time) => {
+      return time > prev ? time : prev;
     }, 0);
-    const maxFrameTime = maxFrames * 33.333;
 
-    // If no touch event, return approximate frame time.
-    if ((lastEvent && lastEvent.type !== EventType.Touch) || !lastEvent) {
+    // Not finished if the final events don't include a Touch or Apple event, so return approximate frame time.
+    if (finalEvents.length === 0) {
       return {
         finished: false,
         reason: ReplayFinishStateReason.NoTouch,
-        time: Math.round(maxFrameTime),
+        time: Math.round(finalFrameTime),
       };
     }
 
-    // Set to highest event time.
-    const maxEventTime = lastEvent.time * (0.001 / (0.182 * 0.0024)) * 1000;
+    // Info about whether each ride's last event is within ~1 frame of time from the end of that ride.
+    // In finished rides, flower Touch is sometimes slightly more than FrameDuration away from the end,
+    // so a small extra tolerance is allowed. (In singleplayer replays, the extra time can range at least
+    // from 6.0e-13 to 4.9e-8 ms, and in multiplayer replays at least from 0.333 ms to 3.333 ms.)
+    const extraTolerance = this.rides.length > 1 ? 3.5 : 1.0e-7;
+    const rideHasLastFrameEvent = lastFrameTimes.map((lastFrameTime, idx) => {
+      const lastEventTime = lastEventTimes[idx];
+      return lastEventTime ? lastFrameTime <= lastEventTime + FrameDuration + extraTolerance : false;
+    });
 
-    // If event difference to frame time is >1 frames of time, probably not finished?
-    if (maxFrameTime > maxEventTime + 33.333) {
+    // If the highest event time is not within ~1 frame of time from the end, probably not finished?
+    const finalEventIdx = lastEventTimes.lastIndexOf(finalEventTime);
+    if (!rideHasLastFrameEvent[finalEventIdx]) {
       return {
         finished: false,
         reason: ReplayFinishStateReason.FrameDifference,
-        time: Math.round(maxFrameTime),
+        time: Math.round(finalFrameTime),
       };
     }
 
-    // Otherwise probably finished?
+    // For multiplayer replays where one player waits at the flower for the other to take an apple.
+    let waitingAtFlower = false;
+    let endsWithAppleTake = false;
+
+    let isFinished = false;
+    for (const [idx, ride] of this.rides.entries()) {
+      // Potentially finished, if ride ends in a Touch or Apple event.
+      const lastEvent = lastEvents[idx];
+      if (lastEvent && rideHasLastFrameEvent[idx] && !isFinished) {
+        if (lastEvent.type === EventType.Touch) {
+          if (
+            ride.events.length >= 2 &&
+            ride.events[ride.events.length - 2].type === EventType.Touch &&
+            ride.events[ride.events.length - 2].time !== lastEvent.time
+          ) {
+            // Probably ended at flower, but not all apples were taken.
+            isFinished = false;
+            waitingAtFlower = true;
+          } else {
+            // Otherwise probably finished, but false positives are possible (e.g., dying to killer).
+            isFinished = true;
+          }
+        } else if (lastEvent.type === EventType.Apple) {
+          endsWithAppleTake = true;
+          if (ride.events.length >= 3) {
+            const endAppleCount = ride.events.filter(
+              (event) => event.type === EventType.Apple && event.time === lastEvent.time,
+            ).length;
+            const endTouchEventCount = ride.events.filter(
+              (event) => event.type === EventType.Touch && event.time === lastEvent.time,
+            ).length;
+            if (endTouchEventCount >= endAppleCount + 1) {
+              // Apple(s) and flower taken at the same time. N apples and a flower will
+              // generate (at least) N+1 Touch events, followed by N Apple events.
+              isFinished = true;
+            }
+          }
+        }
+      }
+    }
+
+    // Multiplayer finish.
+    if (waitingAtFlower && endsWithAppleTake) isFinished = true;
+
     return {
-      finished: true,
-      reason: ReplayFinishStateReason.Touch,
-      time: Math.floor(maxEventTime),
+      finished: isFinished,
+      reason: isFinished ? ReplayFinishStateReason.Touch : ReplayFinishStateReason.NoTouch,
+      time: isFinished && finalEventTime ? Math.floor(finalEventTime) : Math.round(finalFrameTime),
     };
   }