پلاگین MotionPathPlugin یکی از قدرتمندترین امکانات GSAP برای حرکت دادن هر عنصر (SVG یا HTML) روی یک مسیر دلخواه است. این مسیر می‌تواند یک مسیر SVG (<path>) یا آرایه‌ای از نقاط باشد.

🟢 ۱. راه‌اندازی

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/MotionPathPlugin.min.js"></script>
<script>
  gsap.registerPlugin(MotionPathPlugin);
</script>

🟡 ۲. مثال پایه (حرکت روی مسیر SVG)

HTML

CSS

.ball {
  width: 30px; height: 30px;
  border-radius: 50%;
  background: coral;
  position: absolute;
}

JS

gsap.to(".ball", {
  duration: 5,
  repeat: -1,
  yoyo: true,
  ease: "none",
  motionPath: {
    path: "#myPath",      // مسیر
    align: "#myPath",     // چرخش مطابق مسیر
    alignOrigin: [0.5, 0.5]
  }
});

• align عنصر را به مسیر هم‌تراز می‌کند تا جهت حرکت طبیعی باشد.

• yoyo برگشت مسیر را فعال می‌کند.

🟠 ۳. مسیر از نقاط دلخواه (Array)

می‌توانید بدون SVG هم کار کنید:

gsap.to(".ball", {
  duration: 4,
  motionPath: {
    path: [
      {x:0, y:0},
      {x:200, y:100},
      {x:400, y:0}
    ],
    curviness: 1.25, // میزان خمیدگی
    autoRotate: true
  },
  repeat: -1,
  yoyo: true
});

🟣 ۴. ترکیب با ScrollTrigger

حرکت مسیر را به اسکرول گره بزنید:

gsap.to(".ball", {
  motionPath: {
    path: "#myPath",
    align: "#myPath"
  },
  scrollTrigger: {
    trigger: "#myPath",
    start: "top center",
    end: "bottom center",
    scrub: true
  }
});

• با scrub حرکت دقیقاً با اسکرول هماهنگ می‌شود.

🔵 ۵. تنظیمات کلیدی motionPath

💡 نکات حرفه‌ای

1. SVG Responsive: از viewBox استفاده کنید تا مسیر در اندازه‌های مختلف صحیح بماند.

2. Timeline: چند MotionPath را در یک Timeline قرار دهید تا توالی حرکات پیچیده بسازید.

3. Ease: معمولاً ease: "none" برای حرکت یکنواخت بهترین است.

4. Performance: برای مسیرهای پیچیده، تعداد نقاط را به حداقل لازم کاهش دهید.

✅ جمع‌بندی

• پلاگین MotionPathPlugin حرکت عناصر روی هر مسیر دلخواه را ساده می‌کند.

• مسیر می‌تواند از یک <path> در SVG یا از آرایه‌ای از نقاط باشد.

• گزینه‌های align, autoRotate, و ترکیب با ScrollTrigger کنترل کامل و انیمیشن‌های بسیار روان و چشمگیر را ممکن می‌سازند.