Garug's Gacha

Description

This repository contains a comprehensive Gacha System designed to simulate the mechanics commonly found in many popular mobile and online games. The system allows users to "pull" for items or characters, which are distributed based on predefined probabilities. This project aims to provide a flexible and extensible framework for developers looking to integrate a gacha mechanic into their applications.

Features

• Configurable Gacha Pools: Easily define different pools with unique data
• Rarity Tiers: Support for multitle rarity tiers with customizable drop rates
• Pity System: Implement a pity system to ensure users receive a high-rarity items after a certain number of pulls
• Statistics: Generate detailed statistics on pulls, including probabilities and user history

Usage

Basic Example

import { generatePool } from "garug/gacha";

// Define items and their probabilities
const items = [
  { name: "Some item", probability: 0.5 },
  { name: "Another item", probability: 0.5 },
];

// create a pool
const pool = generatePool({ items });

// get a item
const { item } = pool.random();

Defining probabilities

Instead of define a specific probability for each item, you can use rarities

const rarities = [
  { name: "common", probability: 0.5 },
  { name: "rare", probability: 0.3 },
  { name: "epic", probability: 0.15 },
  { name: "legendary", probability: 0.05 },
];

There are two different ways of rarities usage, define them on each item or group items for each rarity

// for each item
const items_a = [
  { name: "Some item", probability: "rare" },
  { name: "Another item", probability: "legendary" },
];

// grouping items
const items_b = {
  rare: [{ name: "Some item" }],
  legendary: [{ name: "Another item" }],
};

// Both are acceptable to create a pool
const pool_a = generatePool({ items: items_a, rarities });
const pool_b = generatePool({ items: items_b, rarities });
const pool_c = generatePool({ items: [...items_a, ...items_b], rarities });

[!TIP] Using rarities, take attention to quantity of items for each rarity to have desired output, for example, if you have two rarities (Lets call them rare and common), rare with 0.1 probability and common with 0.9 probability, rare has just one item and common has ten items

In this scenario, the rare item has 0.1 of probability, while every common item has 0.09 of probability, making a specific common card more difficult to appear than the rare item

Sorting a Item

After a pool is created, just call random function to get a item

const item = pool.random();

How to Contribute

1. Fork the project
2. Commit your changes
3. Push to the branch
4. Create a new Pull Request

License

This project is licensed under the MIT license