@allemandi/gacha-engine 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: 'yarn'
+      - run: yarn install --frozen-lockfile
+      - run: yarn lint
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: 'yarn'
+      - run: yarn install --frozen-lockfile
+      - run: yarn test
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: 'yarn'
+      - run: yarn install --frozen-lockfile
+      - run: yarn build

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org/'
+          cache: 'yarn'
+
+      - run: yarn install --frozen-lockfile
+      - run: yarn build
+      
+      - run: yarn publish --non-interactive --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Lam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# 📖 @allemandi/gacha-engine
+
+[![NPM Version](https://img.shields.io/npm/v/@allemandi/gacha-engine)](https://www.npmjs.com/package/@allemandi/gacha-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/allemandi/gacha-engine/blob/main/LICENSE)
+
+> **Practical, type-safe toolkit for simulating and understanding gacha rates and rate-ups.**
+> 
+> Works in Node.js, browsers – supports ESM, CommonJS, and UMD
+
+<!-- omit from toc -->
+## 🔖 Table of Contents
+- [✨ Features](#-features)
+- [🛠️ Installation](#️-installation)
+- [🚀 Quick Usage Examples](#-quick-usage-examples)
+- [📘 API](#-api)
+- [🧪 Tests](#-tests)
+- [🔗 Related Projects](#-related-projects)
+- [🤝 Contributing](#-contributing)
+
+
+## ✨ Features
+- 🔍 Determine how many rolls are needed to reach a target probability for an item
+- 📐 Estimate cumulative probabilities over multiple rolls
+- ⚡ Lightweight and fast rarity probabilities
+
+## 🛠️ Installation
+```bash
+# Yarn
+yarn add @allemandi/gacha-engine
+
+# NPM
+npm install @allemandi/gacha-engine
+```
+
+
+## 🚀 Quick Usage Examples
+
+**ESM**
+```js
+import { GachaEngine } from '@allemandi/gacha-engine';
+
+const pools = [
+  {
+    rarity: 'SSR',
+    items: [
+      { name: 'Ultra Sword', probability: 0.01, rateUp: true },
+      { name: 'Magic Wand', probability: 0.02 },
+      { name: 'Useless SSR Loot', probability: 0.97 }
+    ]
+  },
+  {
+    rarity: 'SR',
+    items: [
+      { name: 'Steel Shield', probability: 0.1 },
+      { name: 'Healing Potion', probability: 0.2 }
+    ]
+  }
+];
+
+const rarityRates = {
+  SSR: 0.05,
+  SR: 0.3,
+};
+
+const engine = new GachaEngine({ pools, rarityRates });
+
+const dropRate = engine.getItemDropRate('Ultra Sword');
+console.log(`Drop rate for Ultra Sword: ${dropRate}`);
+
+const cumulativeProb = engine.getCumulativeProbabilityForItem('Ultra Sword', 10);
+console.log(`Probability of getting Ultra Sword in 10 rolls: ${cumulativeProb}`);
+
+const rollsNeeded = engine.getRollsForTargetProbability('Ultra Sword', 0.9);
+console.log(`Rolls needed for 90% chance: ${rollsNeeded}`);
+
+const rateUpItems = engine.getRateUpItems();
+console.log(`Current rate-up items: ${rateUpItems.join(', ')}`);
+```
+
+**CommonJS**
+```js
+const { GachaEngine } = require('@allemandi/gacha-engine');
+```
+
+**UMD**
+```html
+ <script src="https://unpkg.com/@allemandi/gacha-engine"></script>
+  <script>
+    const engine = new window.AllemandiGachaEngine.GachaEngine({
+      pools: [
+        {
+          rarity: '5★',
+          items: [{ name: 'Rate Up Character', probability: 0.008 }]
+        }
+      ]
+    });
+
+    console.log('Rate up:', engine.getItemDropRate('Rate Up Character'));
+    // Rate up: 0.008
+  </script>
+```
+
+## 📘 API
+`new GachaEngine(config: GachaEngineConfig)`
+
+Creates a new GachaEngine instance.
+
+- `config.pools`: Array of item pools, each with a rarity and list of items (each with name, probability, optional `rateUp` flag).
+
+- `config.rarityRates`: Optional object mapping rarities to base probabilities.
+
+### Methods
+`getItemDropRate(name: string): number`
+- Returns the effective drop rate of an item by name.
+
+`getRarityProbability(rarity: string): number`
+- Returns the base probability assigned to a rarity pool.
+
+`getCumulativeProbabilityForItem(name: string, rolls: number): number`
+- Returns the probability of obtaining the specified item at least once within the given number of rolls.
+
+`getRollsForTargetProbability(name: string, targetProbability: number): number`
+- Returns the minimum number of rolls needed to reach or exceed the target probability for the specified item.
+
+`getRateUpItems(): string[]`
+- Returns a list of all item names currently marked as rate-up.
+
+`getAllItemDropRates(): { name: string; dropRate: number; rarity: string }[]`
+- Returns an array of all items with their calculated drop rates and rarities.
+
+## 🧪 Tests
+
+> Available in the GitHub repo only.
+
+```bash
+# Run the test suite with Jest
+yarn test
+# or
+npm test
+```
+
+## 🔗 Related Projects
+Check out these related projects that might interest you:
+
+**[@allemandi/embed-utils](https://github.com/allemandi/embed-utils)**
+- Fast, type-safe utilities for vector embedding comparison and search.
+
+**[Embed Classify CLI](https://github.com/allemandi/embed-classify-cli)**
+- Node.js CLI tool for local text classification using word embeddings.
+
+## 🤝 Contributing
+If you have ideas, improvements, or new features:
+
+1. Fork the project
+2. Create your feature branch (git checkout -b feature/amazing-feature)
+3. Commit your changes (git commit -m 'Add some amazing feature')
+4. Push to the branch (git push origin feature/amazing-feature)
+5. Open a Pull Request

package/dist/index.cjs

@@ -0,0 +1,2 @@
+function t(t,r){(null==r||r>t.length)&&(r=t.length);for(var e=0,n=Array(r);e<r;e++)n[e]=t[e];return n}exports.GachaEngine=/*#__PURE__*/function(){function r(t){var r=t.rarityRates,e=void 0===r?{}:r,n=t.pools;this.pools=void 0,this.rarityRates=void 0,this.pools=n,this.rarityRates=e}var e=r.prototype;return e.getItemDropRate=function(r){for(var e,n=function(r){var e="undefined"!=typeof Symbol&&r[Symbol.iterator]||r["@@iterator"];if(e)return(e=e.call(r)).next.bind(e);if(Array.isArray(r)||(e=function(r,e){if(r){if("string"==typeof r)return t(r,e);var n={}.toString.call(r).slice(8,-1);return"Object"===n&&r.constructor&&(n=r.constructor.name),"Map"===n||"Set"===n?Array.from(r):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?t(r,e):void 0}}(r))){e&&(r=e);var n=0;return function(){return n>=r.length?{done:!0}:{done:!1,value:r[n++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}(this.pools);!(e=n()).done;){var o=e.value,i=o.items.find(function(t){return t.name===r});if(i){var a,u=o.items.reduce(function(t,r){return t+r.probability},0),l=null!=(a=this.rarityRates[o.rarity])?a:u;return i.probability/u*l}}throw new Error('Item "'+r+'" not found')},e.getRarityProbability=function(t){var r,e=this.pools.find(function(r){return r.rarity===t});if(!e)throw new Error('Rarity "'+t+'" not found');var n=e.items.reduce(function(t,r){return t+r.probability},0);return null!=(r=this.rarityRates[t])?r:n},e.getCumulativeProbabilityForItem=function(t,r){var e=this.getItemDropRate(t);return 1-Math.pow(1-e,r)},e.getRollsForTargetProbability=function(t,r){var e=this.getItemDropRate(t);return e<=0?Infinity:Math.ceil(Math.log(1-r)/Math.log(1-e))},e.getRateUpItems=function(){return this.pools.flatMap(function(t){return t.items.filter(function(t){return t.rateUp}).map(function(t){return t.name})})},e.getAllItemDropRates=function(){var t=this;return this.pools.flatMap(function(r){return r.items.map(function(e){return{name:e.name,dropRate:t.getItemDropRate(e.name),rarity:r.rarity}})})},r}();
+//# sourceMappingURL=index.cjs.map

package/eslint.config.mjs

@@ -0,0 +1,34 @@
+import { defineConfig } from "eslint/config";
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    recommendedConfig: js.configs.recommended,
+    allConfig: js.configs.all
+});
+
+export default defineConfig([{
+    
+    ignores: ["dist/**"],
+
+    extends: compat.extends("eslint:recommended", "plugin:@typescript-eslint/recommended"),
+
+    plugins: {
+        "@typescript-eslint": typescriptEslint,
+    },
+
+    languageOptions: {
+        parser: tsParser,
+        ecmaVersion: 2020,
+        sourceType: "module",
+    },
+
+    rules: {},
+}]);

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@allemandi/gacha-engine",
+    "version": "0.1.0",
+    "description": "Practical, type-safe toolkit for simulating and understanding gacha rates and rate-ups.",
+    "main": "dist/index.cjs",
+    "module": "dist/index.module.js",
+    "types": "./dist/index.d.ts",
+    "unpkg": "dist/index.umd.js",
+    "source": "src/index.ts",
+    "repository": "https://github.com/allemandi/gacha-engine.git",
+    "author": "allemandi <69766017+allemandi@users.noreply.github.com>",
+    "license": "MIT",
+    "type": "module",
+    "scripts": {
+        "build": "microbundle --name AllemandiGachaEngine",
+        "test": "vitest run",
+        "dev:test": "vitest",
+        "lint": "eslint src --ext .ts"
+    },
+    "keywords": [
+        "gacha",
+        "gacha-engine",
+        "rate-up",
+        "probability",
+        "simulation",
+        "gacha-simulator",
+        "lootbox",
+        "random-drop",
+        "gaming",
+        "game-probability",
+        "rolls",
+        "typescript",
+        "type-safe",
+        "drop-rate"
+    ],
+    "devDependencies": {
+        "@typescript-eslint/eslint-plugin": "^8.35.0",
+        "@typescript-eslint/parser": "^8.35.0",
+        "eslint": "^9.29.0",
+        "microbundle": "^0.15.1",
+        "typescript": "^5.8.3",
+        "vitest": "^3.2.4"
+    }
+}

package/src/gacha-engine.ts

@@ -0,0 +1,58 @@
+import { RarityInput, GachaEngineConfig } from './types';
+export class GachaEngine {
+    private pools: RarityInput[];
+    private rarityRates: Record<string, number>;
+
+    constructor({ rarityRates = {}, pools }: GachaEngineConfig) {
+        this.pools = pools;
+        this.rarityRates = rarityRates;
+    }
+
+    getItemDropRate(name: string): number {
+        for (const pool of this.pools) {
+            const item = pool.items.find(i => i.name === name);
+            if (item) {
+                const totalPoolProb = pool.items.reduce((sum, i) => sum + i.probability, 0);
+                const baseRarityRate = this.rarityRates[pool.rarity] ?? totalPoolProb;
+                return (item.probability / totalPoolProb) * baseRarityRate;
+            }
+        }
+        throw new Error(`Item "${name}" not found`);
+    }
+
+    getRarityProbability(rarity: string): number {
+        const pool = this.pools.find(p => p.rarity === rarity);
+        if (!pool) throw new Error(`Rarity "${rarity}" not found`);
+
+        const totalProb = pool.items.reduce((sum, i) => sum + i.probability, 0);
+        const baseRate = this.rarityRates[rarity] ?? totalProb;
+        return baseRate;
+    }
+
+    getCumulativeProbabilityForItem(name: string, rolls: number): number {
+        const rate = this.getItemDropRate(name);
+        return 1 - Math.pow(1 - rate, rolls);
+    }
+
+    getRollsForTargetProbability(name: string, targetProbability: number): number {
+        const rate = this.getItemDropRate(name);
+        if (rate <= 0) return Infinity;
+        return Math.ceil(Math.log(1 - targetProbability) / Math.log(1 - rate));
+    }
+
+    getRateUpItems(): string[] {
+        return this.pools.flatMap(p =>
+            p.items.filter(i => i.rateUp).map(i => i.name)
+        );
+    }
+
+    getAllItemDropRates(): { name: string; dropRate: number; rarity: string }[] {
+        return this.pools.flatMap(p =>
+            p.items.map(i => ({
+                name: i.name,
+                dropRate: this.getItemDropRate(i.name),
+                rarity: p.rarity
+            }))
+        );
+    }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { GachaEngine } from "./gacha-engine";

package/src/types.ts

@@ -0,0 +1,16 @@
+
+export interface RarityInput {
+    rarity: string;
+    items: GachaItem[];
+}
+
+export interface GachaItem {
+    name: string;
+    probability: number;
+    rateUp?: boolean;
+}
+
+export interface GachaEngineConfig {
+    rarityRates?: Record<string, number>;
+    pools: RarityInput[];
+}

package/test/index.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { GachaEngine } from '../src/gacha-engine';
+import type { RarityInput, GachaEngineConfig } from '../src/types';
+
+const mockPools: RarityInput[] = [
+    {
+        rarity: 'common',
+        items: [
+            { name: 'ItemA', probability: 0.5 },
+            { name: 'ItemB', probability: 0.5 },
+        ],
+    },
+    {
+        rarity: 'rare',
+        items: [
+            { name: 'ItemC', probability: 0.7 },
+            { name: 'ItemD', probability: 0.3, rateUp: true },
+        ],
+    },
+];
+
+const config: GachaEngineConfig = {
+    rarityRates: {
+        common: 0.8,
+        rare: 0.2,
+    },
+    pools: mockPools,
+};
+
+describe('GachaEngine', () => {
+    const engine = new GachaEngine(config);
+
+    describe('getItemDropRate', () => {
+        it('should return correct drop rate using rarityRates', () => {
+            expect(engine.getItemDropRate('ItemA')).toBeCloseTo(0.4); // 0.5 * 0.8
+            expect(engine.getItemDropRate('ItemD')).toBeCloseTo(0.06); // 0.3 * 0.2
+        });
+
+        it('throws if item does not exist', () => {
+            expect(() => engine.getItemDropRate('Unknown')).toThrow('Item "Unknown" not found');
+        });
+    });
+
+    describe('getRarityProbability', () => {
+        it('should return correct base rarity rate', () => {
+            expect(engine.getRarityProbability('common')).toBe(0.8);
+            expect(engine.getRarityProbability('rare')).toBe(0.2);
+        });
+
+        it('throws if rarity not found', () => {
+            expect(() => engine.getRarityProbability('epic')).toThrow('Rarity "epic" not found');
+        });
+    });
+
+    describe('getCumulativeProbabilityForItem', () => {
+        it('should calculate cumulative probability correctly', () => {
+            const dropRate = engine.getItemDropRate('ItemA'); // 0.4
+            const rolls = 3;
+            const expected = 1 - Math.pow(1 - dropRate, rolls);
+            expect(engine.getCumulativeProbabilityForItem('ItemA', rolls)).toBeCloseTo(expected);
+        });
+    });
+
+    describe('getRollsForTargetProbability', () => {
+        it('should calculate rolls to reach target probability', () => {
+            const target = 0.9;
+            const rate = engine.getItemDropRate('ItemA'); // 0.4
+            const expected = Math.ceil(Math.log(1 - target) / Math.log(1 - rate));
+            expect(engine.getRollsForTargetProbability('ItemA', target)).toBe(expected);
+        });
+
+        it('returns Infinity if drop rate is zero', () => {
+            const zeroRateEngine = new GachaEngine({
+                pools: [{
+                    rarity: 'none',
+                    items: [
+                        { name: 'NeverDrops', probability: 0 },
+                        { name: 'Other', probability: 1 },
+                    ],
+                }],
+            });
+
+            expect(zeroRateEngine.getRollsForTargetProbability('NeverDrops', 0.5)).toBe(Infinity);
+        });
+    });
+
+    describe('getRateUpItems', () => {
+        it('returns only rate-up item names', () => {
+            expect(engine.getRateUpItems()).toEqual(['ItemD']);
+        });
+
+        it('returns empty array if no rate-up items', () => {
+            const noRateUpEngine = new GachaEngine({
+                pools: [{
+                    rarity: 'common',
+                    items: [{ name: 'NoRateUp', probability: 1 }],
+                }],
+            });
+            expect(noRateUpEngine.getRateUpItems()).toEqual([]);
+        });
+    });
+
+    describe('getAllItemDropRates', () => {
+        it('returns all items with correct drop rates and rarities', () => {
+            const results = engine.getAllItemDropRates();
+            expect(results).toContainEqual({ name: 'ItemA', dropRate: 0.4, rarity: 'common' });
+            expect(results).toContainEqual({ name: 'ItemD', dropRate: 0.06, rarity: 'rare' });
+            expect(results).toHaveLength(4);
+        });
+    });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node'
+  }
+})