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.
- 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
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();
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
andcommon
), rare with0.1
probability and common with0.9
probability, rare has just one item and common has ten itemsIn this scenario, the rare item has
0.1
of probability, while every common item has0.09
of probability, making a specific common card more difficult to appear than the rare item
After a pool is created, just call random
function to get a item
const item = pool.random();
- Fork the project
- Commit your changes
- Push to the branch
- Create a new Pull Request
This project is licensed under the MIT license