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!