osrs-tools 2.4.0 → 2.5.2

package/dist/runescape/model/clue/ClueScrollHelper.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Helper class for OSRS Clue Scrolls
+ * Handles casket opening simulation with accurate wiki-based reward odds
+ */
+import { Item } from '../Item/Item';
+/**
+ * Result of opening a casket - contains all rewards obtained
+ */
+export interface CasketReward {
+    items: Item[];
+    count: number;
+}
+/**
+ * Main ClueScrollHelper class that provides methods to simulate clue scroll rewards, calculate probabilities, and list possible rewards
+ *
+ * Reference: https://oldschool.runescape.wiki/w/Clue_scrolls
+ */
+export declare class ClueScrollHelper {
+    /**
+     * Select a random reward based on rarity tiers
+     * Uses item rarity values to create weighted selection
+     */
+    private static selectRandomReward;
+    /**
+     * Determine the number of rewards in a casket
+     * Different tiers have different distributions
+     * For beginner: min 1, max 3, average 2
+     * For easy: min 2, max 4, average 3
+     * For medium: min 3, max 5, average 4
+     * For hard: min 4, max 6, average 5
+     * For elite: min 4, max 6, average 5
+     * For master: min 5, max 7, average 6
+     * @returns Number of rewards based on tier
+     */
+    private static getRewardCount;
+    /**
+     * Select a reward table for the given tier (for tiers with table-based mechanics)
+     * Returns items from the selected table
+     */
+    private static selectRewardTable;
+    /**
+     * Simulate opening a clue casket and return all rewards
+     * @param tier The difficulty tier of the clue scroll
+     * @returns CasketReward containing all items and count
+     */
+    static openCasket(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): CasketReward;
+    /**
+     * Get the probability of obtaining a specific item from a casket as a fraction
+     * @param tier The difficulty tier
+     * @param itemName The item name to check probability for
+     * @returns The probability as a fraction (e.g., 0.0278 for 1/36)
+     */
+    static getItemProbability(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master', itemName: string): number;
+    /**
+     * Get the rarity denominator (X in "1 in X") for an item
+     */
+    static getItemRarity(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master', itemName: string): number;
+    /**
+     * Get all possible rewards for a tier as Item objects
+     */
+    static getPossibleRewards(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): Item[];
+    /**
+     * Get all possible reward items names for a tier
+     */
+    static getPossibleRewardNames(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): string[];
+    /**
+     * Simulate opening multiple caskets
+     * @param tier The clue tier
+     * @param count Number of caskets to open
+     * @returns Array of all reward items
+     */
+    static simulateMultiple(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master', count: number): Item[];
+    /**
+     * Get reward statistics for a tier
+     */
+    static getRewardStats(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): {
+        tier: string;
+        totalUnique: number;
+        rareItems: number;
+        commonItems: number;
+    };
+}
+//# sourceMappingURL=ClueScrollHelper.d.ts.map

package/dist/runescape/model/clue/ClueScrollHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClueScrollHelper.d.ts","sourceRoot":"","sources":["../../../../source/runescape/model/clue/ClueScrollHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAYpC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAwBjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAwC7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IA0BhC;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY;IAkBnG;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMvH;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMlH;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE;IAKrG;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE;IAK3G;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CACrB,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,EAClE,KAAK,EAAE,MAAM,GACZ,IAAI,EAAE;IAST;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG;QACzF,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB;CAWF"}

package/dist/runescape/model/clue/ClueScrollHelper.js

@@ -0,0 +1,197 @@
+/**
+ * Helper class for OSRS Clue Scrolls
+ * Handles casket opening simulation with accurate wiki-based reward odds
+ */
+import { getClueRewardsByTier, getClueRewardTables, } from './ClueScrollRewards';
+/**
+ * Main ClueScrollHelper class that provides methods to simulate clue scroll rewards, calculate probabilities, and list possible rewards
+ *
+ * Reference: https://oldschool.runescape.wiki/w/Clue_scrolls
+ */
+export class ClueScrollHelper {
+    /**
+     * Select a random reward based on rarity tiers
+     * Uses item rarity values to create weighted selection
+     */
+    static selectRandomReward(rewards) {
+        const items = [];
+        let totalWeight = 0;
+        for (const { item, rarity } of Object.values(rewards)) {
+            const probability = 1 / rarity;
+            items.push({ item, probability });
+            totalWeight += probability;
+        }
+        const random = Math.random() * totalWeight;
+        let cumulative = 0;
+        for (const { item, probability } of items) {
+            cumulative += probability;
+            if (random < cumulative) {
+                return item;
+            }
+        }
+        // Fallback to last item if rounding errors occur
+        return items[items.length - 1].item;
+    }
+    /**
+     * Determine the number of rewards in a casket
+     * Different tiers have different distributions
+     * For beginner: min 1, max 3, average 2
+     * For easy: min 2, max 4, average 3
+     * For medium: min 3, max 5, average 4
+     * For hard: min 4, max 6, average 5
+     * For elite: min 4, max 6, average 5
+     * For master: min 5, max 7, average 6
+     * @returns Number of rewards based on tier
+     */
+    static getRewardCount(tier) {
+        const random = Math.random();
+        switch (tier.toLowerCase()) {
+            case 'beginner':
+                // Distribution: 25% = 1, 50% = 2, 25% = 3 (average = 2)
+                if (random < 0.25)
+                    return 1;
+                if (random < 0.75)
+                    return 2;
+                return 3;
+            case 'easy':
+                // Distribution: 25% = 2, 50% = 3, 25% = 4 (average = 3)
+                if (random < 0.25)
+                    return 2;
+                if (random < 0.75)
+                    return 3;
+                return 4;
+            case 'medium':
+                // Distribution: 33.3% = 3, 33.3% = 4, 33.3% = 5 (average = 4)
+                if (random < 0.333)
+                    return 3;
+                if (random < 0.667)
+                    return 4;
+                return 5;
+            case 'hard':
+                // Distribution: 25% = 4, 50% = 5, 25% = 6 (average = 5)
+                if (random < 0.25)
+                    return 4;
+                if (random < 0.75)
+                    return 5;
+                return 6;
+            case 'elite':
+                // Distribution: 25% = 4, 50% = 5, 25% = 6 (average = 5)
+                // Note: Plus 1/5 chance of master clue (doesn't take a slot)
+                if (random < 0.25)
+                    return 4;
+                if (random < 0.75)
+                    return 5;
+                return 6;
+            case 'master':
+                // Distribution: 20% = 5, 60% = 6, 20% = 7 (average = 6)
+                if (random < 0.2)
+                    return 5;
+                if (random < 0.8)
+                    return 6;
+                return 7;
+            default:
+                return 2;
+        }
+    }
+    /**
+     * Select a reward table for the given tier (for tiers with table-based mechanics)
+     * Returns items from the selected table
+     */
+    static selectRewardTable(tier) {
+        const tables = getClueRewardTables(tier);
+        if (!tables) {
+            // No table structure, use flat rewards
+            return getClueRewardsByTier(tier);
+        }
+        // Calculate total weight
+        const totalWeight = tables.reduce((sum, table) => sum + table.weight, 0);
+        const random = Math.random() * totalWeight;
+        let cumulative = 0;
+        for (const table of tables) {
+            cumulative += table.weight;
+            if (random < cumulative) {
+                return table.items;
+            }
+        }
+        // Fallback to first table
+        return tables[0].items;
+    }
+    /**
+     * Simulate opening a clue casket and return all rewards
+     * @param tier The difficulty tier of the clue scroll
+     * @returns CasketReward containing all items and count
+     */
+    static openCasket(tier) {
+        const rewardCount = this.getRewardCount(tier);
+        const rewards = [];
+        for (let i = 0; i < rewardCount; i++) {
+            const rewardTable = this.selectRewardTable(tier);
+            const item = this.selectRandomReward(rewardTable);
+            rewards.push(item);
+        }
+        return {
+            items: rewards,
+            count: rewardCount,
+        };
+    }
+    /**
+     * Get the probability of obtaining a specific item from a casket as a fraction
+     * @param tier The difficulty tier
+     * @param itemName The item name to check probability for
+     * @returns The probability as a fraction (e.g., 0.0278 for 1/36)
+     */
+    static getItemProbability(tier, itemName) {
+        const rewards = getClueRewardsByTier(tier);
+        const reward = rewards[itemName];
+        return reward ? 1 / reward.rarity : 0;
+    }
+    /**
+     * Get the rarity denominator (X in "1 in X") for an item
+     */
+    static getItemRarity(tier, itemName) {
+        const rewards = getClueRewardsByTier(tier);
+        const reward = rewards[itemName];
+        return reward ? reward.rarity : 0;
+    }
+    /**
+     * Get all possible rewards for a tier as Item objects
+     */
+    static getPossibleRewards(tier) {
+        const rewards = getClueRewardsByTier(tier);
+        return Object.values(rewards).map(r => r.item);
+    }
+    /**
+     * Get all possible reward items names for a tier
+     */
+    static getPossibleRewardNames(tier) {
+        const rewards = getClueRewardsByTier(tier);
+        return Object.keys(rewards);
+    }
+    /**
+     * Simulate opening multiple caskets
+     * @param tier The clue tier
+     * @param count Number of caskets to open
+     * @returns Array of all reward items
+     */
+    static simulateMultiple(tier, count) {
+        const rewards = [];
+        for (let i = 0; i < count; i++) {
+            const casketReward = this.openCasket(tier);
+            rewards.push(...casketReward.items);
+        }
+        return rewards;
+    }
+    /**
+     * Get reward statistics for a tier
+     */
+    static getRewardStats(tier) {
+        const rewards = getClueRewardsByTier(tier);
+        const items = Object.values(rewards);
+        return {
+            tier,
+            totalUnique: items.length,
+            rareItems: items.filter(r => r.rarity > 100).length,
+            commonItems: items.filter(r => r.rarity <= 50).length,
+        };
+    }
+}

package/dist/runescape/model/clue/ClueScrollRewards.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Clue Scroll Reward Item Mappings
+ * Organizes all clue scroll rewards by tier with their correct rarity tiers
+ * Based on official OSRS Wiki data
+ */
+import { Item } from '../Item/Item';
+/**
+ * Reward odds mapping for Beginner clue scrolls
+ * Beginner caskets have a three-tier table structure based on wiki data:
+ * https://oldschool.runescape.wiki/w/Reward_casket_(beginner)
+ *
+ * Key mechanics:
+ * - Caskets contain 1-3 items (weighted towards 2)
+ * - Unique/Cabbage roll: 1/12 (41/492)
+ *   - 50% Cabbage (5-9 noted) at 1/24 overall
+ *   - 50% Specific unique at 1/360 overall (1/15 items)
+ * - Black items table: 11/492 (18 items at 1/805.1 each, or 11/8856)
+ * - Common items: 440/492 (weapons, armor, runes, misc food)
+ *
+ * Average loot value per roll: 1,427 gp
+ * Average casket value: 2,854 gp (2 rolls average)
+ * Average clues for all uniques: 597
+ */
+interface RewardTable {
+    [itemName: string]: {
+        item: Item;
+        rarity: number;
+    };
+}
+/**
+ * Beginner rewards organized by table structure
+ * Table weights define the probability of selecting each table per roll
+ *
+ * Weights represent proportions that sum to 492:
+ * - Unique/Cabbage: 41 weight = 1/12 chance (41/492)
+ * - Black items: 11 weight = 11/492 chance
+ * - Common items: 440 weight = 440/492 chance
+ */
+export declare const BEGINNER_REWARDS: {
+    tables: Array<{
+        name: string;
+        weight: number;
+        items: RewardTable;
+        description?: string;
+    }>;
+    flattened: {
+        [x: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+};
+/**
+ * Easy rewards organized by table structure
+ * Table weights represent the proportion of rolls hitting each table
+ *
+ * Beginner uses 1080 total weight units:
+ * - Unique/standard items dominate
+ * - Master clue is separate 1/50 mechanic
+ */
+export declare const EASY_REWARDS: {
+    tables: Array<{
+        name: string;
+        weight: number;
+        items: RewardTable;
+        description?: string;
+    }>;
+    flattened: {
+        [x: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+};
+/**
+ * Medium clue rewards with table-based structure
+ * Weighted table system for accurate probability distribution
+ */
+export declare const MEDIUM_REWARDS: {
+    tables: Array<{
+        name: string;
+        weight: number;
+        items: RewardTable;
+        description?: string;
+    }>;
+    flattened: {
+        [x: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+};
+/**
+ * Hard clue rewards with table-based structure
+ * 4-6 items per casket, average 5
+ */
+export declare const HARD_REWARDS: {
+    tables: Array<{
+        name: string;
+        weight: number;
+        items: RewardTable;
+        description?: string;
+    }>;
+    flattened: {
+        [x: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+};
+/**
+ * Elite clue rewards with table-based structure
+ * 4-6 items per casket, average 5
+ */
+export declare const ELITE_REWARDS: {
+    tables: Array<{
+        name: string;
+        weight: number;
+        items: RewardTable;
+        description?: string;
+    }>;
+    flattened: {
+        [x: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+};
+/**
+ * Master clue rewards with table-based structure
+ * 5-7 items per casket, average 6
+ */
+export declare const MASTER_REWARDS: {
+    tables: Array<{
+        name: string;
+        weight: number;
+        items: RewardTable;
+        description?: string;
+    }>;
+    flattened: {
+        [x: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+};
+/**
+ * Gets all reward odds for a specific clue tier
+ */
+export declare function getClueRewardsByTier(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): {
+    [itemName: string]: {
+        item: Item;
+        rarity: number;
+    };
+};
+/**
+ * Gets the table structure for a specific clue tier (if available)
+ * Returns null for tiers that don't have table-based rewards
+ */
+export declare function getClueRewardTables(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): Array<{
+    name: string;
+    weight: number;
+    items: {
+        [itemName: string]: {
+            item: Item;
+            rarity: number;
+        };
+    };
+}> | null;
+/**
+ * Gets all items for a specific tier as an array
+ */
+export declare function getClueItemsList(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): Item[];
+export {};
+//# sourceMappingURL=ClueScrollRewards.d.ts.map

package/dist/runescape/model/clue/ClueScrollRewards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClueScrollRewards.d.ts","sourceRoot":"","sources":["../../../../source/runescape/model/clue/ClueScrollRewards.ts"],"names":[],"mappings":"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"}