useTween

import { useTween } from "@carverjs/core/hooks";

import { useRef, useEffect } from "react";
import { Actor } from "@carverjs/core/components";
import { useTween } from "@carverjs/core/hooks";
import type { Group } from "@carverjs/core/types";

function BouncingBox() {
  const ref = useRef<Group>(null);
  const { tween } = useTween();

  useEffect(() => {
    if (!ref.current) return;

    const controls = tween({
      target: ref.current.position,
      to: { y: 3 },
      duration: 0.8,
      ease: "bounce.out",
      yoyo: true,
      repeat: -1,
    });

    return () => { controls.kill(); };
  }, [tween]);

  return <Actor ref={ref} type="primitive" shape="box" color="orange" />;
}

const { tween } = useTween();

// Tween a Three.js position
tween({
  target: ref.current.position,
  to: { x: 5, y: 2 },
  duration: 1,
  ease: "quad.out",
});

tween({
  target: ref.current.scale,
  from: { x: 0, y: 0, z: 0 },
  to: { x: 1, y: 1, z: 1 },
  duration: 0.5,
  ease: "back.out",
});

tween({
  target: ref.current.position,
  to: { x: 10 },
  duration: 2,
  onStart: () => console.log("started"),
  onUpdate: (progress) => console.log("progress:", progress),
  onComplete: () => console.log("done"),
});

const controls = tween({ target: obj, to: { x: 10 }, duration: 1 });

controls.pause();          // Pause
controls.resume();         // Resume
controls.kill();           // Stop and release
controls.restart();        // Replay from start
controls.seek(0.5);        // Jump to 50% progress
controls.setSpeed(2);      // Double speed
controls.chain({ ... });   // Chain another tween after completion

tween({ target: pos, to: { x: 5 }, duration: 1 })
  .chain({ target: pos, to: { y: 5 }, duration: 1 });

const { tweenNumber } = useTween();

// Animate a score counter
tweenNumber({
  from: 0,
  to: 1000,
  duration: 2,
  ease: "expo.out",
  onUpdate: (value, progress) => {
    scoreElement.textContent = Math.round(value).toString();
  },
});

const { timeline } = useTween();

const tl = timeline()
  .add({
    target: ref.current.position,
    to: { x: 5 },
    duration: 1,
    ease: "sine.inOut",
  })
  .add({
    target: ref.current.position,
    to: { y: 3 },
    duration: 0.5,
  });

timeline()
  .add({ target: pos, to: { x: 5 }, duration: 1 })
  .add({ target: pos, to: { y: 3 }, duration: 0.5 }, "-=0.3"); // overlap by 0.3s

timeline()
  .add({ target: pos, to: { x: 5 }, duration: 1 })
  .add({ target: scale, to: { x: 2, y: 2 }, duration: 1 }, "<"); // start at same time

timeline()
  .addLabel("intro")
  .add({ target: pos, to: { x: 5 }, duration: 1 })
  .addLabel("middle")
  .add({ target: rot, to: { z: Math.PI }, duration: 0.5 }, "middle+=0.2");

timeline()
  .add({ target: pos, to: { x: 5 }, duration: 1 })
  .addCallback(() => console.log("halfway!"), "+=0")
  .add({ target: pos, to: { y: 3 }, duration: 0.5 });

import { cubicBezier, steps } from "@carverjs/core/systems";

// CSS-compatible cubic bezier
tween({
  target: pos,
  to: { x: 10 },
  ease: cubicBezier(0.68, -0.55, 0.27, 1.55),
  duration: 1,
});

// Bezier as a tuple (shorthand)
tween({
  target: pos,
  to: { x: 10 },
  ease: [0.68, -0.55, 0.27, 1.55],
  duration: 1,
});

// Step easing (like CSS steps())
tween({
  target: pos,
  to: { x: 10 },
  ease: steps(5),
  duration: 1,
});

// Custom function
tween({
  target: pos,
  to: { x: 10 },
  ease: (t) => t * t * t,
  duration: 1,
});

// Repeat 3 more times (4 total plays)
tween({ target: pos, to: { y: 5 }, repeat: 3 });

// Infinite repeat with yoyo (ping-pong)
tween({ target: pos, to: { y: 5 }, repeat: -1, yoyo: true });

// Delay between repeats
tween({ target: pos, to: { y: 5 }, repeat: -1, yoyo: true, repeatDelay: 0.5 });

tween({
  target: ref.current.position,
  to: { x: 5 },
  duration: 1,
}).chain({
  target: ref.current.position,
  to: { y: 3 },
  duration: 0.5,
});

const controls = tween({ target: pos, to: { x: 10 }, duration: 1 });
await controls.finished;
console.log("tween done!");

tween({
  target: menuRef.current.position,
  to: { y: 0 },
  duration: 0.3,
  ignorePause: true,
});

const { tween, killAll } = useTween();

// Kill all tweens from this hook
killAll();

// Or kill individually
const controls = tween({ ... });
controls.kill();