در GSAP، توابع کمکی مانند random()، shuffle()، wrap() و wrapYoyo() ابزارهای قدرتمندی برای ایجاد حرکت‌های تصادفی، چرخش گسسته و انیمیشن‌های تکراری با رفتار خاص هستند. این توابع اغلب برای انیمیشن‌های پویا، کارت‌ها، چرخه‌ها و scroll effects استفاده می‌شوند.

🟢 1️⃣ ()random

• کاربرد: تولید مقدار تصادفی در یک بازه مشخص یا از بین آرایه‌ای از مقادیر.

• ساختار:

gsap.utils.random(min, max, rounding?, floating?)

مثال:

let r = gsap.utils.random(0, 100);
console.log(r); // عددی بین 0 تا 100

• اگر آرایه بدهید:

let r = gsap.utils.random(["red","green","blue"]);
console.log(r); // یکی از رنگ‌ها

• گزینه rounding برای گرد کردن به نزدیک‌ترین عدد مشخص و floating برای float/عدد اعشاری استفاده می‌شود.

🟡 2️⃣ ()shuffle

• کاربرد: ترتیب المان‌های آرایه را به صورت تصادفی تغییر می‌دهد.

• ساختار:

gsap.utils.shuffle(array)

مثال:

let arr = [1,2,3,4,5];
gsap.utils.shuffle(arr);
console.log(arr); // آرایه به شکل تصادفی

• بسیار مناسب برای Stagger و انیمیشن گروهی که می‌خواهید المان‌ها به صورت تصادفی حرکت کنند.

🟠 3️⃣ ()wrap

• کاربرد: نگه داشتن مقدار در یک محدوده به صورت چرخه‌ای.

• ساختار:

gsap.utils.wrap(min, max, value)

مثال:

let x = gsap.utils.wrap(0, 300, 350);
console.log(x); // خروجی: 50

• مناسب برای انیمیشن‌های چرخشی، موقعیت محدود یا scroll loop

• با آرایه هم می‌توان استفاده کرد:

gsap.utils.wrap(["red","green","blue"], "yellow"); // "red"

🟣 4️⃣ ()wrapYoyo

• کاربرد: شبیه wrap() اما به صورت رفت و برگشتی (yoyo) مقدار را بین حداقل و حداکثر نگه می‌دارد.

• ساختار:

gsap.utils.wrapYoyo(min, max, value)

مثال:

let y = gsap.utils.wrapYoyo(0, 100, 250);
console.log(y); // خروجی: 50 (رفت و برگشت بین 0 و 100)

• مناسب برای انیمیشن‌های پینگ پنگ یا yoyo با محدودیت.

🟤 ترکیب با GSAP

Random + Stagger

gsap.to(".box", {
  y: () => gsap.utils.random(50, 200),
  duration: 1,
  stagger: 0.2
});

Shuffle + Stagger

let items = gsap.utils.shuffle([".box1", ".box2", ".box3"]);
gsap.to(items, { x: 300, duration: 1, stagger: 0.3 });

Wrap + Tween

gsap.to(".circle", {
  x: () => gsap.utils.wrap(0, 300, Math.random()*500),
  duration: 2
});

WrapYoyo + Modifier

gsap.to(".ball", {
  x: 500,
  duration: 2,
  modifiers: {
    x: x => gsap.utils.wrapYoyo(0, 300, parseFloat(x))
  },
  repeat: -1,
  yoyo: true
});

✅ جمع‌بندی

این توابع کمک می‌کنند تا انیمیشن‌ها پویا، طبیعی، تصادفی و کنترل‌شده باشند، بدون نیاز به محاسبات پیچیده دستی.