https://github.com/littensy/ripple

🎨 An elegant motion library for Roblox
https://github.com/littensy/ripple

Last synced: 5 days ago
JSON representation

🎨 An elegant motion library for Roblox

• Host: GitHub
• URL: https://github.com/littensy/ripple
• Owner: littensy
• License: mit
• Created: 2023-07-30T01:55:48.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-09-16T03:09:24.000Z (4 months ago)
• Last Synced: 2025-01-01T06:08:57.637Z (12 days ago)
• Language: Luau
• Size: 86.9 KB
• Stars: 31
• Watchers: 1
• Forks: 12
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-react-lua - **Repository**
• awesome-react-lua - **Repository**

README

        
# 🎨 Ripple

**Ripple** is a simple, lightweight, and easy-to-use Roblox library for creating simple transitions and animations. It is inspired by [roact-spring](https://github.com/chriscerie/roact-spring) and is primarily intended to be a general-use alternative to [Flipper](https://github.com/Reselim/Flipper) for [Roblox-TS](https://roblox-ts.com).

You may use Ripple with or without Roact. Currently, there is no package for using Ripple with Roact.

## 📦 Installation

Ripple is available on [NPM](https://www.npmjs.com/package/@rbxts/ripple) and can be installed with the following commands:

```bash

npm install @rbxts/ripple

yarn add @rbxts/ripple

pnpm add @rbxts/ripple

```

```toml

# Wally

Ripple = "littensy/ripple@version"

```

## 📚 Documentation

To see Ripple in action, check out the [example repository](https://github.com/littensy/rbxts-react-example).

### ⚡ Quick Start

Call `createMotion` to create an animation.

Use the `spring`, `linear`, `immediate`, and `tween` methods to set the goal of your animation.

```typescript

import { Motion, MotionGoal, config, createMotion } from "@rbxts/ripple";

const motion = createMotion(Vector3.zero, { start: true });

motion.spring(Vector3.one, config.spring.stiff);

motion.onStep((value, deltaTime) => {

	print(value, deltaTime);

});

print(motion.get());

```

You can also apply different goal types to specific properties using the `to` method:

```typescript

const motion = createMotion({ x: 0, y: 0 });

motion.to({

	x: spring(100, config.spring.stiff),

	y: linear(100),

});

```

### ⚛️ Usage with React

#### `useMotion(initialValue)`

Creates a memoized Motion object set to the given initial value.

Returns a binding that updates with the Motion, along with the Motion object.

```typescript

function MyComponent() {

	const [binding, motion] = useMotion(0);

	// ...

}

```

```typescript

export function useMotion(initialValue: number): LuaTuple<[Binding, Motion]>;

export function useMotion(initialValue: T): LuaTuple<[Binding, Motion]>;

export function useMotion(initialValue: T) {

	const motion = useMemo(() => {

		return createMotion(initialValue);

	}, []);

	const [binding, setValue] = useBinding(initialValue);

	useEventListener(RunService.Heartbeat, (delta) => {

		const value = motion.step(delta);

		if (value !== binding.getValue()) {

			setValue(value);

		}

	});

	return $tuple(binding, motion);

}

```

#### `useSpring(value, springConfig?)`

Applies spring animations to the given value, and updates the goal with the latest value on every re-render.

Returns a binding that updates with the Motion.

```typescript

function MyComponent({ someValue }: Props) {

	const binding = useSpring(someValue);

	// ...

}

```

```typescript

export function useSpring(goal: number | Binding, options?: SpringOptions): Binding;

export function useSpring(goal: T | Binding, options?: SpringOptions): Binding;

export function useSpring(goal: MotionGoal | Binding, options?: SpringOptions) {

	const [binding, motion] = useMotion(getBindingValue(goal));

	const previousValue = useRef(getBindingValue(goal));

	useEventListener(RunService.Heartbeat, () => {

		const currentValue = getBindingValue(goal);

		if (currentValue !== previousValue.current) {

			previousValue.current = currentValue;

			motion.spring(currentValue, options);

		}

	});

	return binding;

}

```

### 📝 License

Ripple is licensed under the MIT License.