gamified

Gamified

Gamified is a toolkit for web developers looking to add engaging gamification and reward systems to their applications. Easily animate rewards like coins or tokens—and soon much more!

Live Demo

https://github.com/user-attachments/assets/099e900e-d461-40ee-a096-5e1472e165cf

https://gamified-example.vercel.app/

Features

• Collecting Animation Hook: Animate items (e.g., coins, tokens) moving from a source element to a target element with customizable physics and timing.
• Future Components:
  • Scratch-offs
  • Slot machines
  • Wheel spinners
    All designed to be easily customizable and compostable.

Installation

Install Gamified via npm:

npm install gamified

Usage

Collecting Animation Hook

The useCollectingAnimation hook allows you to animate the collection of items from one element (the source) to another (the target). It supports a variety of customization options for element size, animation duration, randomness in motion, and more.

Example

Below is a sample usage of the hook in a React component:

import React, { useRef } from 'react';
import { useCollectingAnimation } from 'gamified';

const App = () => {
  const sourceRef = useRef(null);
  const targetRef = useRef(null);

  const { startAnimation, isAnimating, progress, debugInfo } = useCollectingAnimation({
    sourceRef,
    targetRef,
    elements: ['💰'], // Can be strings, numbers, or JSX elements.
    count: 20, // Total number of items to animate.
    batchCount: 4, // Number of batches to split the animation.
    batchDelay: 250, // Delay (in ms) between batches.
    elementSize: 40, // Size of each animated element.
    onComplete: () => console.log('Animation complete'),
    onReached: () => console.log('First element reached the target'),
    debug: true,
  });

  return (
    <div>
      <div ref={sourceRef} style={{ position: 'absolute', top: 50, left: 50 }}>
        Source
      </div>
      <div ref={targetRef} style={{ position: 'absolute', top: 300, left: 300 }}>
        Target
      </div>
      <button onClick={startAnimation} disabled={isAnimating}>
        Start Animation
      </button>
      <div>Progress: {Math.floor(progress * 100)}%</div>
      {debugInfo && <div>Debug: {debugInfo}</div>}
    </div>
  );
};

export default App;

API Reference

useCollectingAnimation(options)

Parameters:

Option	Type	Default	Description
sourceRef	RefObject<HTMLElement>	Required	Reference to the source element (starting point) for the animation.
targetRef	RefObject<HTMLElement>	Required	Reference to the target element (destination) for the animation.
elements	React.ReactNode[]	Required	Array of elements (icons, tokens, etc.) to animate.
count	number	15	Total number of elements to animate.
batchCount	number	3	Number of batches to split the animation into.
batchDelay	number (ms)	300	Delay between each batch in milliseconds.
elementSize	number (px)	30	Size of each animated element.
durationRange	[number, number]	[800, 1500]	Range for animation duration (ms).
arcHeightRange	[number, number]	[80, 150]	Range for the arc height (px).
pathRandomness	number	50	Degree of randomness for the animation path.
startOffsetRange	[number, number]	[-15, 15]	Random offset range for the starting position.
endOffsetRange	[number, number]	[-20, 20]	Random offset range for the ending position.
zIndexRange	[number, number]	[9000, 9100]	Range for the z-index of the animated elements.
shrinkAtEnd	number (0-1)	0.3	Fraction to shrink the element by the end of the animation.
onComplete	() => void	undefined	Callback fired when the entire animation completes.
onReached	() => void	undefined	Callback fired when the first element reaches the target (threshold).
reachThreshold	number (0-1)	0.85	Progress fraction when an element is considered to be "reaching" the target.
debug	boolean	false	Enable debug mode to log internal state and animation details.

Returns:

An object containing:

• startAnimation: Function to trigger the animation.
• isAnimating: Boolean flag indicating if an animation is currently in progress.
• isReachingTarget: Boolean flag indicating if any element is in the "reaching" state.
• reachingCount: Number of elements that have reached the threshold.
• completedCount: Number of elements that have completed their animation.
• totalCount: Total number of elements scheduled for animation.
• progress: Overall animation progress as a fraction (completedCount / totalCount).
• debugInfo: Debug messages when debug mode is enabled.

Future Roadmap

Gamified is only getting started! Upcoming components include:

• Scratch-offs: Add an interactive layer of chance with digital scratch-off cards.
• Slot Machines: Integrate slot machine animations that users can spin for rewards.
• Wheel Spinners: Create customizable wheel spinners for prize selection.

All new components will follow the same principles of high customizability and composability, making them easy to integrate into any web application.

Contributing

Contributions are welcome! Feel free to submit issues or pull requests on our GitHub repository.

License

This project is licensed under the MIT License.

Elevate your application's engagement with Gamified—where every interaction can be a rewarding experience!