@luceosports/play-rendering 2.6.0 → 2.6.2

package/dist/types/helpers/animation.d.ts

@@ -0,0 +1,17 @@
+import { AnimationMode, LinePart, LineType } from '../types';
+export type TimelineKey = 'keyTimes' | 'keyTimesSeq';
+export type HasKeyTimes = {
+    keyTimes: number[];
+    keyTimesSeq?: number[];
+};
+export declare const getTimelineKey: (mode: AnimationMode) => TimelineKey;
+export declare const getEffectiveTimeline: (anim: HasKeyTimes, timeline: TimelineKey) => number[];
+export declare const keyTimesToChunks: (keyTimes: number[]) => [number, number][];
+export declare const deriveLineChunksWithFallback: (params: {
+    timeline: TimelineKey;
+    playerAnimation: HasKeyTimes;
+    lineAnimation: HasKeyTimes;
+    lineType: LineType;
+    lineParts: LinePart[];
+    legacySupport?: boolean;
+}) => [number, number][];

package/dist/types/models/LineModel.d.ts

@@ -15,8 +15,6 @@ export class LineModel {
     get hideLineTip(): boolean;
     get animations(): LineAnimation[];
     animationsByEndTime(mode: AnimationMode): number[];
-    get animationKeyTimeChunks(): [number, number][];
-    set animationKeyTimeChunks(value: [number, number][]);
     lastAnimEndTime(mode: AnimationMode): number;
     get firstLinePartControlPoint(): CourtPoint;
     get lastLinePartControlPoint(): CourtPoint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luceosports/play-rendering",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "main": "dist/play-rendering.js",
   "types": "dist/play-rendering.d.ts",
   "scripts": {

package/src/constants.ts

@@ -1,63 +1,65 @@
-export const SPORT_TYPE_BASKETBALL = 'BASKETBALL';
-export const SPORT_TYPE_VOLLEYBALL = 'VOLLEYBALL';
-export const SPORT_TYPE_BEACH_VOLLEYBALL = 'BEACH_VOLLEYBALL';
-export const SPORT_TYPE_FOOTBALL = 'FOOTBALL';
-export const SPORT_TYPE_LACROSSE = 'LACROSSE';
-export const SPORT_TYPE_LACROSSE_BOX = 'LACROSSE_BOX';
-export const SPORT_TYPE_SOCCER = 'SOCCER';
-export const SPORT_TYPE_HOCKEY = 'HOCKEY';
-export const SPORT_TYPE_BASEBALL = 'BASEBALL';
-export const SPORT_TYPE_SOFTBALL = 'SOFTBALL';
-
-export const COURT_TYPE_BIG3 = 'BIG3';
-export const COURT_TYPE_FIBA = 'FIBA';
-export const COURT_TYPE_NBA = 'NBA';
-export const COURT_TYPE_NCAAM = 'NCAAM';
-export const COURT_TYPE_NCAAW = 'NCAAW';
-export const COURT_TYPE_US_HIGH_SCHOOL = 'US_HIGH_SCHOOL';
-export const COURT_TYPE_US_JUNIOR_HIGH = 'US_JUNIOR_HIGH';
-export const COURT_TYPE_WNBA = 'WNBA';
-
-export const COURT_TYPE_FOOTBALL_COLLEGE = 'FOOTBALL_COLLEGE';
-export const COURT_TYPE_FOOTBALL_NFL = 'FOOTBALL_NFL';
-export const COURT_TYPE_FOOTBALL_HIGH_SCHOOL = 'FOOTBALL_HIGH_SCHOOL';
-export const COURT_TYPE_FOOTBALL_HIGH_SCHOOL_LEGACY = 'FOOTBALL';
-
-export const COURT_TYPE_VOLLEYBALL_INDOOR = 'VOLLEYBALL_INDOOR';
-
-export const COURT_TYPE_BEACH_VOLLEYBALL_NCAA = 'BEACH_VOLLEYBALL_NCAA';
-export const COURT_TYPE_BEACH_VOLLEYBALL_RECREATIONAL = 'BEACH_VOLLEYBALL_RECREATIONAL';
-
-export const COURT_TYPE_LACROSSE_US_M = 'LACROSSE_US_M';
-export const COURT_TYPE_LACROSSE_US_W = 'LACROSSE_US_W';
-
-export const COURT_TYPE_LACROSSE_BOX_US = 'LACROSSE_BOX_US';
-export const COURT_TYPE_LACROSSE_BOX_CLA = 'LACROSSE_BOX_CLA';
-
-export const COURT_TYPE_SOCCER_FIFA = 'SOCCER_FIFA';
-export const COURT_TYPE_SOCCER_NCAA = 'SOCCER_NCAA';
-export const COURT_TYPE_SOCCER_NFHS = 'SOCCER_NFHS';
-export const COURT_TYPE_SOCCER_U10 = 'SOCCER_U10';
-export const COURT_TYPE_SOCCER_U12 = 'SOCCER_U12';
-export const COURT_TYPE_SOCCER_U19 = 'SOCCER_U19';
-
-export const COURT_TYPE_HOCKEY_NHL = 'HOCKEY_NHL';
-export const COURT_TYPE_HOCKEY_INTERNATIONAL = 'HOCKEY_INTERNATIONAL';
-
-export const COURT_TYPE_BASEBALL_HIGH_SCHOOL = 'BASEBALL_HIGH_SCHOOL';
-
-export const COURT_TYPE_SOFTBALL_FP_COLLEGE = 'SOFTBALL_FP_COLLEGE';
-export const COURT_TYPE_SOFTBALL_FP_HIGH_SCHOOL = 'SOFTBALL_FP_HS';
-
-export const SHAPE_TYPE_CIRCLE = 'CIRCLE';
-export const SHAPE_TYPE_SQUARE = 'SQUARE';
-export const SHAPE_TYPE_TRIANGLE = 'TRIANGLE';
-export const SHAPE_TYPE_FOV = 'FOV';
-export const SHAPE_TYPE_XMARK = 'XMARK';
-export const SHAPE_TYPE_STRAIGHT = 'STRAIGHT';
-export const SHAPE_TYPE_CONE = 'CONE';
-export const SHAPE_TYPE_LINE_CUT = 'LINE.CUT';
-export const SHAPE_TYPE_LINE_SCREEN = 'LINE.SCREEN';
-export const SHAPE_TYPE_LINE_DRIBBLE = 'LINE.DRIBBLE';
-export const SHAPE_TYPE_LINE_PASS = 'LINE.PASS';
-export const SHAPE_TYPE_LINE_HANDOFF = 'LINE.HANDOFF';
+export const BALL_TRANSFER_LINE_DURATION_DEFAULT = 0.03;
+
+export const SPORT_TYPE_BASKETBALL = 'BASKETBALL';
+export const SPORT_TYPE_VOLLEYBALL = 'VOLLEYBALL';
+export const SPORT_TYPE_BEACH_VOLLEYBALL = 'BEACH_VOLLEYBALL';
+export const SPORT_TYPE_FOOTBALL = 'FOOTBALL';
+export const SPORT_TYPE_LACROSSE = 'LACROSSE';
+export const SPORT_TYPE_LACROSSE_BOX = 'LACROSSE_BOX';
+export const SPORT_TYPE_SOCCER = 'SOCCER';
+export const SPORT_TYPE_HOCKEY = 'HOCKEY';
+export const SPORT_TYPE_BASEBALL = 'BASEBALL';
+export const SPORT_TYPE_SOFTBALL = 'SOFTBALL';
+
+export const COURT_TYPE_BIG3 = 'BIG3';
+export const COURT_TYPE_FIBA = 'FIBA';
+export const COURT_TYPE_NBA = 'NBA';
+export const COURT_TYPE_NCAAM = 'NCAAM';
+export const COURT_TYPE_NCAAW = 'NCAAW';
+export const COURT_TYPE_US_HIGH_SCHOOL = 'US_HIGH_SCHOOL';
+export const COURT_TYPE_US_JUNIOR_HIGH = 'US_JUNIOR_HIGH';
+export const COURT_TYPE_WNBA = 'WNBA';
+
+export const COURT_TYPE_FOOTBALL_COLLEGE = 'FOOTBALL_COLLEGE';
+export const COURT_TYPE_FOOTBALL_NFL = 'FOOTBALL_NFL';
+export const COURT_TYPE_FOOTBALL_HIGH_SCHOOL = 'FOOTBALL_HIGH_SCHOOL';
+export const COURT_TYPE_FOOTBALL_HIGH_SCHOOL_LEGACY = 'FOOTBALL';
+
+export const COURT_TYPE_VOLLEYBALL_INDOOR = 'VOLLEYBALL_INDOOR';
+
+export const COURT_TYPE_BEACH_VOLLEYBALL_NCAA = 'BEACH_VOLLEYBALL_NCAA';
+export const COURT_TYPE_BEACH_VOLLEYBALL_RECREATIONAL = 'BEACH_VOLLEYBALL_RECREATIONAL';
+
+export const COURT_TYPE_LACROSSE_US_M = 'LACROSSE_US_M';
+export const COURT_TYPE_LACROSSE_US_W = 'LACROSSE_US_W';
+
+export const COURT_TYPE_LACROSSE_BOX_US = 'LACROSSE_BOX_US';
+export const COURT_TYPE_LACROSSE_BOX_CLA = 'LACROSSE_BOX_CLA';
+
+export const COURT_TYPE_SOCCER_FIFA = 'SOCCER_FIFA';
+export const COURT_TYPE_SOCCER_NCAA = 'SOCCER_NCAA';
+export const COURT_TYPE_SOCCER_NFHS = 'SOCCER_NFHS';
+export const COURT_TYPE_SOCCER_U10 = 'SOCCER_U10';
+export const COURT_TYPE_SOCCER_U12 = 'SOCCER_U12';
+export const COURT_TYPE_SOCCER_U19 = 'SOCCER_U19';
+
+export const COURT_TYPE_HOCKEY_NHL = 'HOCKEY_NHL';
+export const COURT_TYPE_HOCKEY_INTERNATIONAL = 'HOCKEY_INTERNATIONAL';
+
+export const COURT_TYPE_BASEBALL_HIGH_SCHOOL = 'BASEBALL_HIGH_SCHOOL';
+
+export const COURT_TYPE_SOFTBALL_FP_COLLEGE = 'SOFTBALL_FP_COLLEGE';
+export const COURT_TYPE_SOFTBALL_FP_HIGH_SCHOOL = 'SOFTBALL_FP_HS';
+
+export const SHAPE_TYPE_CIRCLE = 'CIRCLE';
+export const SHAPE_TYPE_SQUARE = 'SQUARE';
+export const SHAPE_TYPE_TRIANGLE = 'TRIANGLE';
+export const SHAPE_TYPE_FOV = 'FOV';
+export const SHAPE_TYPE_XMARK = 'XMARK';
+export const SHAPE_TYPE_STRAIGHT = 'STRAIGHT';
+export const SHAPE_TYPE_CONE = 'CONE';
+export const SHAPE_TYPE_LINE_CUT = 'LINE.CUT';
+export const SHAPE_TYPE_LINE_SCREEN = 'LINE.SCREEN';
+export const SHAPE_TYPE_LINE_DRIBBLE = 'LINE.DRIBBLE';
+export const SHAPE_TYPE_LINE_PASS = 'LINE.PASS';
+export const SHAPE_TYPE_LINE_HANDOFF = 'LINE.HANDOFF';

package/src/helpers/animation.ts

@@ -1,32 +1,169 @@
-import NoteModel from '../models/NoteModel';
-import ShapeModel from '../models/ShapeModel';
-import _ from 'lodash';
-import { FrameDataOptions } from '../models/FrameModel';
-
-export function computeAnimationAlpha(model: NoteModel | ShapeModel, options: FrameDataOptions) {
-  let alpha = model.hideForStatic && !options.inDrawingState ? 0 : 1;
-  if (options.animationGlobalProgress) {
-    alpha = 0;
-    const animationKeyTimeChunks = model.animations.map(a => {
-      const [startPercent, endPercent] = a.keyTimes;
-      return [startPercent, endPercent];
-    });
-    animationKeyTimeChunks.forEach(([start, end]) => {
-      const fadeInDuration = 0.03;
-      const fadeInStart = start - fadeInDuration;
-      const fadeInEnd = start;
-      const fadeOutStart = end;
-      const fadeOutEnd = end + fadeInDuration;
-      if (_.inRange(options.animationGlobalProgress, fadeInStart, fadeInEnd)) {
-        alpha = (fadeInDuration - (fadeInEnd - options.animationGlobalProgress)) * 10;
-      }
-      if (_.inRange(options.animationGlobalProgress, start, end)) {
-        alpha = 1;
-      }
-      if (_.inRange(options.animationGlobalProgress, fadeOutStart, fadeOutEnd)) {
-        alpha = (fadeOutEnd - options.animationGlobalProgress) * 10;
-      }
-    });
-  }
-  return alpha;
-}
+import NoteModel from '../models/NoteModel';
+import ShapeModel from '../models/ShapeModel';
+import _ from 'lodash';
+import { FrameDataOptions } from '../models/FrameModel';
+import { AnimationMode, Line, LinePart, LineType, Player } from '../types';
+import Bezier from '../math/Bezier';
+import { isBallTransferLineType } from './common';
+import { BALL_TRANSFER_LINE_DURATION_DEFAULT } from '../constants';
+
+export type TimelineKey = 'keyTimes' | 'keyTimesSeq';
+export type HasKeyTimes = { keyTimes: number[]; keyTimesSeq?: number[] };
+
+export const getTimelineKey = (mode: AnimationMode): TimelineKey => {
+  return mode === AnimationMode.SEQUENTIAL ? 'keyTimesSeq' : 'keyTimes';
+};
+
+export const getEffectiveTimeline = (anim: HasKeyTimes, timeline: TimelineKey): number[] => {
+  if (timeline === 'keyTimesSeq') return anim.keyTimesSeq?.length ? anim.keyTimesSeq : anim.keyTimes;
+  return anim.keyTimes;
+};
+
+export const keyTimesToChunks = (keyTimes: number[]): [number, number][] => {
+  const chunks: [number, number][] = [];
+  keyTimes.forEach((value, index) => {
+    if (index) chunks.push([keyTimes[index - 1], value]);
+  });
+  return chunks;
+};
+
+export function computeDefaultLineAnimationDuration(lineType: LineType, linePart: LinePart): number {
+  if (isBallTransferLineType(lineType)) return BALL_TRANSFER_LINE_DURATION_DEFAULT;
+  const [cp1, cp2, cp3, cp4] = linePart.controlPoints;
+  return new Bezier(cp1, cp2, cp3 ?? null, cp4 ?? null).length / 100;
+}
+
+const splitChunkByPartDurations = (params: {
+  start: number;
+  end: number;
+  lineParts: LinePart[];
+  lineType: LineType;
+}): [number, number][] => {
+  const { start, end, lineParts, lineType } = params;
+
+  const total = end - start;
+  if (!Number.isFinite(total) || total <= 0) return [[start, end]];
+
+  const durations = lineParts.map(lp => computeDefaultLineAnimationDuration(lineType, lp));
+  const sum = durations.reduce((acc, v) => acc + (Number.isFinite(v) ? v : 0), 0);
+
+  // If geometry is degenerate, fall back to equal split.
+  const weights =
+    sum > 0 ? durations.map(d => (Number.isFinite(d) ? d / sum : 0)) : lineParts.map(() => 1 / lineParts.length);
+
+  const keyTimes: number[] = [start];
+  let cursor = start;
+
+  for (let i = 0; i < weights.length; i += 1) {
+    const isLast = i === weights.length - 1;
+    const dt = isLast ? end - cursor : total * weights[i];
+    cursor += dt;
+    keyTimes.push(isLast ? end : cursor);
+  }
+
+  return keyTimesToChunks(keyTimes);
+};
+
+export const deriveLineChunksWithFallback = (params: {
+  timeline: TimelineKey;
+  playerAnimation: HasKeyTimes;
+  lineAnimation: HasKeyTimes;
+  lineType: LineType;
+  lineParts: LinePart[];
+  legacySupport?: boolean;
+}): [number, number][] => {
+  const { timeline, playerAnimation, lineAnimation, lineType, lineParts, legacySupport = true } = params;
+  const linePartsCount = lineParts.length ?? 0;
+
+  const chunks = keyTimesToChunks(getEffectiveTimeline(lineAnimation, timeline));
+  if (chunks.length === linePartsCount) return chunks;
+
+  // If there are no chunks (bad/partial data), just return as-is.
+  if (!chunks.length) return chunks;
+
+  // Prefer geometry-based splitting over player animation fallback.
+  // Typical legacy case: multi-part line stored as a single [start,end] chunk.
+  if (chunks.length === 1 && lineParts?.length) {
+    const [[start, end]] = chunks;
+    const split = splitChunkByPartDurations({ start, end, lineParts, lineType });
+    console.log('geometry based', { chunks, split, linePartsCount });
+    if (split.length === linePartsCount) return split;
+  }
+
+  console.warn('PLAYER FALLBACK ATTEMPT!!!', { chunks, linePartsCount });
+
+  // If legacy support is disabled, do not attempt reconstruction from player timeline.
+  if (!legacySupport) return chunks;
+
+  // Backward compatibility:
+  // legacy multi-part lines stored only [start,end] in the line animation timeline,
+  // so reconstruct per-part timings from the player animation timeline slice.
+  const [[start, end]] = chunks;
+  const playerTimeline = getEffectiveTimeline(playerAnimation, timeline);
+
+  const startIndex = playerTimeline.indexOf(start);
+  const endIndex = playerTimeline.indexOf(end);
+  if (startIndex < 0 || endIndex < 0) return chunks;
+
+  const sliced = playerTimeline.slice(startIndex, endIndex + 1);
+  return keyTimesToChunks(sliced);
+};
+
+export const getLineAnimationChunks = (params: {
+  mode: AnimationMode;
+  line: Line;
+  players: Player[];
+}): [number, number][] => {
+  const { mode, line, players } = params;
+
+  const timeline = getTimelineKey(mode);
+
+  const lineAnimation = line.animations?.[0] as unknown as HasKeyTimes | undefined;
+  if (!lineAnimation) return [];
+
+  const linePlayer = players.find(p => p.position === line.playerPositionOrigin);
+  const playerAnimation = (linePlayer?.animations?.[0] as unknown as HasKeyTimes | undefined) ?? undefined;
+
+  // Fast path: no player timeline available, just chunk the line timeline as-is.
+  if (!playerAnimation) {
+    return keyTimesToChunks(getEffectiveTimeline(lineAnimation, timeline));
+  }
+
+  // Full path: handle chunking + legacy reconstruction.
+  return deriveLineChunksWithFallback({
+    timeline,
+    playerAnimation,
+    lineAnimation,
+    lineType: line.type,
+    lineParts: line.lineParts,
+    legacySupport: false
+  });
+};
+
+export function computeAnimationAlpha(model: NoteModel | ShapeModel, options: FrameDataOptions) {
+  let alpha = model.hideForStatic && !options.inDrawingState ? 0 : 1;
+  if (options.animationGlobalProgress) {
+    alpha = 0;
+    const animationKeyTimeChunks = model.animations.map(a => {
+      const [startPercent, endPercent] = a.keyTimes;
+      return [startPercent, endPercent];
+    });
+    animationKeyTimeChunks.forEach(([start, end]) => {
+      const fadeInDuration = 0.03;
+      const fadeInStart = start - fadeInDuration;
+      const fadeInEnd = start;
+      const fadeOutStart = end;
+      const fadeOutEnd = end + fadeInDuration;
+      if (_.inRange(options.animationGlobalProgress, fadeInStart, fadeInEnd)) {
+        alpha = (fadeInDuration - (fadeInEnd - options.animationGlobalProgress)) * 10;
+      }
+      if (_.inRange(options.animationGlobalProgress, start, end)) {
+        alpha = 1;
+      }
+      if (_.inRange(options.animationGlobalProgress, fadeOutStart, fadeOutEnd)) {
+        alpha = (fadeOutEnd - options.animationGlobalProgress) * 10;
+      }
+    });
+  }
+  return alpha;
+}

package/src/helpers/common.ts

@@ -1,6 +1,10 @@
-import { ShapeType } from '../types';
+import { LineType, ShapeType } from '../types';
 import { ShapeModels } from '../index';
 
+export function isBallTransferLineType(type: LineType) {
+  return ['PASS', 'HANDOFF', 'SHOT'].includes(type);
+}
+
 export function animationProgress(globalProgress: number, start: number, end: number) {
   const max = end - start;
   const local = globalProgress - start;

package/src/index.ts

@@ -11,6 +11,7 @@ import * as ShapeModels from './models/ShapeModels';
 import * as Constants from './constants';
 import * as LineDrawingMath from './math/LineDrawingMath';
 import * as Helpers from './helpers/common';
+import * as AnimationHelpers from './helpers/animation';
 import Bezier from './math/Bezier';
 
 import {
@@ -34,5 +35,6 @@ export {
   CourtTypeConstants,
   SportConstants,
   SportCourtTypeMap,
-  Helpers
+  Helpers,
+  AnimationHelpers
 };

package/src/layers/line/layers/DribbleLineLayer.ts

@@ -1,50 +1,62 @@
-import _ from 'lodash';
-import { animationProgress } from '../../../helpers/common';
-import ActionLineLayer from '../base/ActionLineLayer';
-import DribbleLineTrait from '../../../traits/DribbleLineTrait';
-import { LinePart } from '../../../types';
-import { LinePartAdjusted } from '../../../models/LineModel';
-
-export default class DribbleLineLayer extends ActionLineLayer {
-  // ================ DribbleLineTrait Methods ====================
-  private convertLinePartsToDribble(lineParts: LinePart[]): LinePartAdjusted[] {
-    return [];
-  }
-  // ==============================================================
-
-  drawLineCap() {
-    if (this.allowDrawLineCap()) this.drawArrowLineCap();
-  }
-
-  setLineOptions() {
-    const lineParts = [...this.line.getLineParts()];
-    const dribbleLineParts = this.convertLinePartsToDribble(lineParts);
-
-    this.line.setLinePartsAdjusted([]);
-
-    dribbleLineParts.forEach(lp => {
-      const { controlPoints, lpIndex } = lp;
-      const [firstPoint] = controlPoints;
-
-      let animationSegment: LinePartAdjusted['animationSegment'] | undefined = undefined;
-
-      if (this.options.animationGlobalProgress) {
-        const [start, end] = this.line.animationKeyTimeChunks[lpIndex!];
-
-        if (_.inRange(this.options.animationGlobalProgress, start, end)) {
-          if (animationProgress(this.options.animationGlobalProgress, start, end) > firstPoint.time!) {
-            animationSegment = 'processed';
-          } else {
-            animationSegment = 'active';
-          }
-        } else if (this.options.animationGlobalProgress > end) {
-          animationSegment = 'processed';
-        }
-      }
-
-      this.line.addLinePartAdjusted({ ...lp, controlPoints, animationSegment });
-    });
-  }
-}
-
-Object.assign(DribbleLineLayer.prototype, DribbleLineTrait);
+import _ from 'lodash';
+import { animationProgress } from '../../../helpers/common';
+import ActionLineLayer from '../base/ActionLineLayer';
+import DribbleLineTrait from '../../../traits/DribbleLineTrait';
+import { LinePart, AnimationMode } from '../../../types';
+import { LinePartAdjusted } from '../../../models/LineModel';
+import { getLineAnimationChunks } from '../../../helpers/animation';
+
+export default class DribbleLineLayer extends ActionLineLayer {
+  // ================ DribbleLineTrait Methods ====================
+  private convertLinePartsToDribble(lineParts: LinePart[]): LinePartAdjusted[] {
+    return [];
+  }
+  // ==============================================================
+
+  drawLineCap() {
+    if (this.allowDrawLineCap()) this.drawArrowLineCap();
+  }
+
+  setLineOptions() {
+    const lineParts = [...this.line.getLineParts()];
+    const dribbleLineParts = this.convertLinePartsToDribble(lineParts);
+
+    const mode = this.options.animationMode ?? AnimationMode.SEQUENTIAL;
+
+    const chunks = getLineAnimationChunks({
+      mode,
+      line: this.line.originalData,
+      players: this.playData.players
+    });
+
+    this.line.setLinePartsAdjusted([]);
+
+    dribbleLineParts.forEach(lp => {
+      const { controlPoints, lpIndex } = lp;
+      const [firstPoint] = controlPoints;
+
+      let animationSegment: LinePartAdjusted['animationSegment'] | undefined = undefined;
+
+      if (this.options.animationGlobalProgress && lpIndex != null) {
+        const chunk = chunks[lpIndex];
+        if (chunk) {
+          const [start, end] = chunk;
+
+          if (_.inRange(this.options.animationGlobalProgress, start, end)) {
+            if (animationProgress(this.options.animationGlobalProgress, start, end) > firstPoint.time!) {
+              animationSegment = 'processed';
+            } else {
+              animationSegment = 'active';
+            }
+          } else if (this.options.animationGlobalProgress > end) {
+            animationSegment = 'processed';
+          }
+        }
+      }
+
+      this.line.addLinePartAdjusted({ ...lp, controlPoints, animationSegment });
+    });
+  }
+}
+
+Object.assign(DribbleLineLayer.prototype, DribbleLineTrait);

package/src/models/FrameModel.ts

@@ -1,6 +1,6 @@
 import _ from 'lodash';
 import Bezier from '../math/Bezier';
-import { animationProgress, transformShapeTypeToImportKey } from '../helpers/common';
+import { animationProgress, isBallTransferLineType, transformShapeTypeToImportKey } from '../helpers/common';
 import { distanceBetweenPoints, splitBezierCurveAtTVal } from '../math/LineDrawingMath';
 import CourtLayer from '../layers/CourtLayer';
 import LineLayer from '../layers/LineLayer';
@@ -24,6 +24,7 @@ import {
 import PlayModel, { PlayModelOptions, PlayStaticData } from './PlayModel';
 import { AnimationMode, Court, CourtPoint, SportType } from '../types';
 import ShapeModel from './ShapeModel';
+import { getEffectiveTimeline, getLineAnimationChunks, getTimelineKey, keyTimesToChunks } from '../helpers/animation';
 
 export type FrameData = {
   sport: SportType;
@@ -197,42 +198,73 @@ export default class FrameModel {
   }
 
   get animationProgressPlayers() {
-    const passLines = this.prevAnimationLines.filter(l => ['PASS', 'HANDOFF', 'SHOT'].includes(l.type));
+    const ballTransferLines = this.prevAnimationLines.filter(l => isBallTransferLineType(l.type));
     const { animationMode } = this.play.options;
 
-    // TODO MAYBE WE WILL SUSPEND PLAYER ANIMATIONS COMPLETELY AND RELY ONLY ON LINE ANIMATIONS TO HAVE SINGE SOURCE OF TRUTH
+    // During playback, rely ONLY on line animations as the single source of truth for player movement.
+    // Player.animations are ignored here as we treat them as legacy data.
+
+    // Only "movement" lines affect player location (origin === terminus === player position).
+    // Ball transfer lines (PASS/HANDOFF/SHOT) are used for possession only.
+    const movementLines = this.play.playData.lines.filter(l => {
+      if (isBallTransferLineType(l.type)) return false;
+      return !!l.playerPositionOrigin && l.playerPositionOrigin === l.playerPositionTerminus;
+    });
+
+    const movementLinesByPlayer = _.groupBy(movementLines, l => l.playerPositionOrigin);
 
     return this.play.playData.players.map(p => {
       const player = new PlayerModel(p);
-      player.setPossession(passLines);
+      player.setPossession(ballTransferLines);
 
-      if (!player.animations.length) return player;
+      const playerMovementLines = movementLinesByPlayer[player.position] ?? [];
+      if (!playerMovementLines.length) return player;
 
-      player.animations.forEach(animation => {
-        const keyTimes =
-          animationMode === AnimationMode.SEQUENTIAL ? animation.keyTimesSeq || animation.keyTimes : animation.keyTimes;
+      // Find active movement line segment (if any), otherwise fall back to the last completed end point.
+      let activeLocation: CourtPoint | null = null;
 
-        const keyTimesChunks: [number, number][] = [];
-        keyTimes.forEach((value, index) => {
-          if (index) keyTimesChunks.push([keyTimes[index - 1], value]);
+      for (const lineData of playerMovementLines) {
+        const chunks = getLineAnimationChunks({
+          mode: animationMode,
+          line: lineData,
+          players: this.play.playData.players
         });
 
-        keyTimesChunks.forEach(([start, end], index) => {
-          if (_.inRange(this.animationGlobalProgress, start, end)) {
-            const animProgress = this.animationProgress(start, end);
-            const bezier = new Bezier(
-              ...(animation.lineParts[index].controlPoints as ConstructorParameters<typeof Bezier>)
-            );
-            player.location = {
-              x: bezier.x(animProgress),
-              y: bezier.y(animProgress)
-            };
-          }
-        });
-      });
+        if (!chunks.length) continue;
+
+        const lineModel = new LineModel(lineData);
+        const parts = lineModel.getLineParts();
 
-      if (this.animationGlobalProgress >= player.lastAnimEndTime(animationMode)!) {
-        player.location = player.lastAnimationLastLinePartControlPoint!;
+        for (let index = 0; index < chunks.length; index += 1) {
+          const [start, end] = chunks[index];
+          if (!_.inRange(this.animationGlobalProgress, start, end)) continue;
+
+          const part = parts[index];
+          if (!part) continue;
+
+          const t = this.animationProgress(start, end);
+          const bezier = new Bezier(...(part.controlPoints as ConstructorParameters<typeof Bezier>));
+
+          activeLocation = { x: bezier.x(t), y: bezier.y(t) };
+          break;
+        }
+
+        if (activeLocation) break;
+      }
+
+      if (activeLocation) {
+        player.location = activeLocation;
+        return player;
+      }
+
+      // No active segment: put player at the end of the latest movement line that has finished.
+      const finishedMovementLines = playerMovementLines
+        .map(l => new LineModel(l))
+        .filter(lm => this.animationGlobalProgress >= lm.lastAnimEndTime(animationMode)!);
+
+      const lastFinished = _.maxBy(finishedMovementLines, lm => lm.lastAnimEndTime(animationMode)!);
+      if (lastFinished?.lastLinePartControlPoint) {
+        player.location = lastFinished.lastLinePartControlPoint;
       }
 
       return player;
@@ -246,13 +278,14 @@ export default class FrameModel {
       .map(l => {
         const line = new LineModel(l);
 
-        line.setAnimationKeyTimesChunked(
-          this.play.playData.players.find(p => p.position === line.playerPositionOrigin)!,
-          animationMode
-        );
+        const chunks = getLineAnimationChunks({
+          mode: animationMode,
+          line: l,
+          players: this.play.playData.players
+        });
 
         const linePartsAdjusted: LinePartAdjusted[] = [];
-        line.animationKeyTimeChunks.forEach(([start, end], index) => {
+        chunks.forEach(([start, end], index) => {
           if (this.animationGlobalProgressPrev < end && this.animationGlobalProgress >= end) {
             window.dispatchEvent(
               new CustomEvent('@luceosports/play-rendering:lineAnimationFinished', { detail: { id: line.id } })