osrs-tools 2.6.0 → 2.7.0

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

@@ -1,79 +1,69 @@
 /**
  * Helper class for OSRS Clue Scrolls
  * Handles casket opening simulation with accurate wiki-based reward odds
+ *
+ * WIKI REFERENCE: https://oldschool.runescape.wiki/w/Clue_scrolls
+ * Each tier has unique mechanics documented in the reward casket pages
  */
-import { Item } from '../Item/Item';
+import { Item } from "../Item/Item";
 /**
  * Result of opening a casket - contains all rewards obtained
  */
 export interface CasketReward {
     items: Item[];
     count: number;
+    /** Optional: master clue if obtained from certain tiers */
+    masterClue?: Item;
 }
 /**
- * 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
+ * Main ClueScrollHelper class that provides methods to simulate clue scroll rewards
  */
 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
+     *
+     * Uses tier-specific mechanics per OSRS Wiki documented behavior:
+     * - Beginner: 1-3 rewards with unique/cabbage sub-mechanic
+     * - Easy: 2-4 rewards + 1/50 master clue
+     * - Medium: 3-5 rewards (standard)
+     * - Hard: 4-6 rewards (standard)
+     * - Elite: 4-6 rewards + 1/5 master clue (bonus, doesn't consume slot)
+     * - Master: 5-7 rewards (standard)
+     *
      * @param tier The difficulty tier of the clue scroll
-     * @returns CasketReward containing all items and count
+     * @returns CasketReward containing all items, count, and optional master clue
      */
-    static openCasket(tier: 'beginner' | 'easy' | 'medium' | 'hard' | 'elite' | 'master'): CasketReward;
+    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;
+    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;
+    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[];
+    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[];
+    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[];
+    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'): {
+    static getRewardStats(tier: "beginner" | "easy" | "medium" | "hard" | "elite" | "master"): {
         tier: string;
         totalUnique: number;
         rareItems: number;

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

@@ -1 +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"}
+{"version":3,"file":"ClueScrollHelper.d.ts","sourceRoot":"","sources":["../../../../source/runescape/model/clue/ClueScrollHelper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAGpC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AA+TD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY;IAmBnG;;;;;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,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE;IASlH;;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

@@ -1,138 +1,335 @@
 /**
  * Helper class for OSRS Clue Scrolls
  * Handles casket opening simulation with accurate wiki-based reward odds
+ *
+ * WIKI REFERENCE: https://oldschool.runescape.wiki/w/Clue_scrolls
+ * Each tier has unique mechanics documented in the reward casket pages
  */
-import { getClueRewardsByTier, getClueRewardTables, } from './ClueScrollRewards';
+import { getClueRewardsByTier, getClueRewardTables } from "./ClueScrollRewards";
+//======================================================================================
+// CORE UTILITY METHODS - Weighted Selection
+//======================================================================================
 /**
- * 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
+ * Select a random item from a reward table using probability weights
+ * Higher rarity number = lower chance of selection
+ * @param rewards Table mapping item names to {item, rarity} pairs
+ * @returns A randomly selected Item based on rarity weights
  */
-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;
-            }
+function selectRandomReward(rewards) {
+    const items = [];
+    let totalWeight = 0;
+    // Convert rarity values to probability weights
+    for (const { item, rarity } of Object.values(rewards)) {
+        const probability = 1 / rarity;
+        items.push({ item, probability });
+        totalWeight += probability;
+    }
+    // Weighted random selection
+    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;
+    // Fallback (should never reach here with valid data)
+    return items[items.length - 1].item;
+}
+/**
+ * Select a reward table using weighted table selection
+ * Each table has a weight representing its probability of being selected
+ * @param tables Array of weighted reward tables for a tier
+ * @returns The selected reward table
+ */
+function selectWeightedTable(tables) {
+    const totalWeight = tables.reduce((sum, t) => sum + t.weight, 0);
+    const random = Math.random() * totalWeight;
+    let cumulative = 0;
+    for (const table of tables) {
+        cumulative += table.weight;
+        if (random < cumulative) {
+            return table.items;
         }
     }
-    /**
-     * 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);
+    // Fallback
+    return tables[0].items;
+}
+//======================================================================================
+// TIER-SPECIFIC REWARD COUNT METHODS
+//======================================================================================
+/**
+ * Beginner: 1-3 items, weighting towards 2
+ * Distribution: 25% = 1, 50% = 2, 25% = 3 (average = 2)
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(beginner)
+ */
+function getBeginnerRewardCount() {
+    const r = Math.random();
+    if (r < 0.25)
+        return 1;
+    if (r < 0.75)
+        return 2;
+    return 3;
+}
+/**
+ * Easy: 2-4 items, weighting towards 3
+ * Distribution: 25% = 2, 50% = 3, 25% = 4 (average = 3)
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(easy)
+ */
+function getEasyRewardCount() {
+    const r = Math.random();
+    if (r < 0.25)
+        return 2;
+    if (r < 0.75)
+        return 3;
+    return 4;
+}
+/**
+ * Medium: 3-5 items, uniform distribution
+ * Distribution: 33.3% each (average = 4)
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(medium)
+ */
+function getMediumRewardCount() {
+    const r = Math.random();
+    if (r < 0.333333)
+        return 3;
+    if (r < 0.666666)
+        return 4;
+    return 5;
+}
+/**
+ * Hard: 4-6 items, weighting towards 5
+ * Distribution: 25% = 4, 50% = 5, 25% = 6 (average = 5)
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(hard)
+ */
+function getHardRewardCount() {
+    const r = Math.random();
+    if (r < 0.25)
+        return 4;
+    if (r < 0.75)
+        return 5;
+    return 6;
+}
+/**
+ * Elite: 4-6 items, weighting towards 5
+ * Distribution: 25% = 4, 50% = 5, 25% = 6 (average = 5)
+ * NOTE: Master clue is separate (1/5 chance, doesn't consume a slot)
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(elite)
+ */
+function getEliteRewardCount() {
+    const r = Math.random();
+    if (r < 0.25)
+        return 4;
+    if (r < 0.75)
+        return 5;
+    return 6;
+}
+/**
+ * Master: 5-7 items, weighting towards 6
+ * Distribution: 20% = 5, 60% = 6, 20% = 7 (average = 6)
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(master)
+ */
+function getMasterRewardCount() {
+    const r = Math.random();
+    if (r < 0.2)
+        return 5;
+    if (r < 0.8)
+        return 6;
+    return 7;
+}
+//======================================================================================
+// TIER-SPECIFIC OPENING MECHANICS
+//======================================================================================
+/**
+ * Beginner casket opening with special unique/cabbage mechanics
+ *
+ * WIKI MECHANICS:
+ * - Unique/Cabbage roll: 1/12 (41/492 weight)
+ *   - When hitting this table: 50% Cabbage, 50% Specific unique item
+ *   - This is handled in the reward data structure
+ * - Black items table: 11/492 weight, then 1/18 for each item
+ * - Common items: 440/492 weight
+ *
+ * The key insight is that the weighted table selection naturally handles these
+ * mechanics since the reward data is properly structured.
+ *
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(beginner)
+ */
+function openBeginnerCasket() {
+    const rewardCount = getBeginnerRewardCount();
+    const rewards = [];
+    const tables = getClueRewardTables("beginner");
+    for (let i = 0; i < rewardCount; i++) {
+        const selectedTable = selectWeightedTable(tables);
+        const item = selectRandomReward(selectedTable);
+        rewards.push(item);
+    }
+    return { items: rewards, count: rewardCount };
+}
+/**
+ * Easy casket opening with master clue special mechanic
+ *
+ * WIKI MECHANICS:
+ * - Main rewards: 2-4 items per casket roll
+ * - Master clue scroll: SEPARATE 1/50 chance per casket opening
+ *   - Not part of the main reward slots
+ *   - Is an additional reward if rolled successfully
+ * - Unique items: High probability tier (~22.9%)
+ * - Standard items: Common weapons, armor, runes, food
+ *
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(easy)
+ */
+function openEasyCasket() {
+    const rewardCount = getEasyRewardCount();
+    const rewards = [];
+    const tables = getClueRewardTables("easy");
+    // Main rewards using weighted table selection
+    for (let i = 0; i < rewardCount; i++) {
+        const selectedTable = selectWeightedTable(tables);
+        const item = selectRandomReward(selectedTable);
+        rewards.push(item);
+    }
+    // Master clue: 1/50 chance (separate roll)
+    const masterClueRoll = Math.random();
+    let masterClue;
+    if (masterClueRoll < 1 / 50) {
+        // Get master clue from the master clue table
+        const masterTable = tables.find((t) => t.weight === 0 && "items" in t);
+        if (masterTable && "Clue scroll (master)" in masterTable.items) {
+            masterClue = masterTable.items["Clue scroll (master)"].item;
         }
-        // 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;
-            }
+    }
+    const result = { items: rewards, count: rewardCount };
+    if (masterClue) {
+        result.masterClue = masterClue;
+    }
+    return result;
+}
+/**
+ * Medium casket opening
+ * Standard weighted table selection with no special mechanics
+ *
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(medium)
+ */
+function openMediumCasket() {
+    const rewardCount = getMediumRewardCount();
+    const rewards = [];
+    const tables = getClueRewardTables("medium");
+    for (let i = 0; i < rewardCount; i++) {
+        const selectedTable = selectWeightedTable(tables);
+        const item = selectRandomReward(selectedTable);
+        rewards.push(item);
+    }
+    return { items: rewards, count: rewardCount };
+}
+/**
+ * Hard casket opening
+ * Standard weighted table selection with no special mechanics
+ *
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(hard)
+ */
+function openHardCasket() {
+    const rewardCount = getHardRewardCount();
+    const rewards = [];
+    const tables = getClueRewardTables("hard");
+    for (let i = 0; i < rewardCount; i++) {
+        const selectedTable = selectWeightedTable(tables);
+        const item = selectRandomReward(selectedTable);
+        rewards.push(item);
+    }
+    return { items: rewards, count: rewardCount };
+}
+/**
+ * Elite casket opening with master clue special mechanic
+ *
+ * WIKI MECHANICS:
+ * - Main rewards: 4-6 items per casket
+ * - Master clue scroll: 1/5 chance (20%), DOES NOT consume a reward slot
+ *   - This is an additional reward beyond the main reward count
+ *   - If obtained, casket total rewards = rewardCount + 1
+ *
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(elite)
+ */
+function openEliteCasket() {
+    const rewardCount = getEliteRewardCount();
+    const rewards = [];
+    const tables = getClueRewardTables("elite");
+    // Main rewards
+    for (let i = 0; i < rewardCount; i++) {
+        const selectedTable = selectWeightedTable(tables);
+        const item = selectRandomReward(selectedTable);
+        rewards.push(item);
+    }
+    // Master clue: 1/5 chance (20%), DOES NOT consume a slot
+    const masterClueRoll = Math.random();
+    let masterClue;
+    if (masterClueRoll < 1 / 5) {
+        const masterTable = tables.find((t) => t.weight === 0 && "items" in t);
+        if (masterTable && "Clue scroll (master)" in masterTable.items) {
+            masterClue = masterTable.items["Clue scroll (master)"].item;
         }
-        // Fallback to first table
-        return tables[0].items;
     }
+    const result = { items: rewards, count: rewardCount };
+    if (masterClue) {
+        result.masterClue = masterClue;
+    }
+    return result;
+}
+/**
+ * Master casket opening
+ * Standard weighted table selection with no special mechanics
+ *
+ * Wiki: https://oldschool.runescape.wiki/w/Reward_casket_(master)
+ */
+function openMasterCasket() {
+    const rewardCount = getMasterRewardCount();
+    const rewards = [];
+    const tables = getClueRewardTables("master");
+    for (let i = 0; i < rewardCount; i++) {
+        const selectedTable = selectWeightedTable(tables);
+        const item = selectRandomReward(selectedTable);
+        rewards.push(item);
+    }
+    return { items: rewards, count: rewardCount };
+}
+//======================================================================================
+// PUBLIC API
+//======================================================================================
+/**
+ * Main ClueScrollHelper class that provides methods to simulate clue scroll rewards
+ */
+export class ClueScrollHelper {
     /**
      * Simulate opening a clue casket and return all rewards
+     *
+     * Uses tier-specific mechanics per OSRS Wiki documented behavior:
+     * - Beginner: 1-3 rewards with unique/cabbage sub-mechanic
+     * - Easy: 2-4 rewards + 1/50 master clue
+     * - Medium: 3-5 rewards (standard)
+     * - Hard: 4-6 rewards (standard)
+     * - Elite: 4-6 rewards + 1/5 master clue (bonus, doesn't consume slot)
+     * - Master: 5-7 rewards (standard)
+     *
      * @param tier The difficulty tier of the clue scroll
-     * @returns CasketReward containing all items and count
+     * @returns CasketReward containing all items, count, and optional master clue
      */
     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);
+        switch (tier.toLowerCase()) {
+            case "beginner":
+                return openBeginnerCasket();
+            case "easy":
+                return openEasyCasket();
+            case "medium":
+                return openMediumCasket();
+            case "hard":
+                return openHardCasket();
+            case "elite":
+                return openEliteCasket();
+            case "master":
+                return openMasterCasket();
+            default:
+                throw new Error(`Unknown clue tier: ${tier}`);
         }
-        return {
-            items: rewards,
-            count: rewardCount,
-        };
     }
     /**
      * Get the probability of obtaining a specific item from a casket as a fraction
@@ -158,7 +355,7 @@ export class ClueScrollHelper {
      */
     static getPossibleRewards(tier) {
         const rewards = getClueRewardsByTier(tier);
-        return Object.values(rewards).map(r => r.item);
+        return Object.values(rewards).map((r) => r.item);
     }
     /**
      * Get all possible reward items names for a tier
@@ -190,8 +387,8 @@ export class ClueScrollHelper {
         return {
             tier,
             totalUnique: items.length,
-            rareItems: items.filter(r => r.rarity > 100).length,
-            commonItems: items.filter(r => r.rarity <= 50).length,
+            rareItems: items.filter((r) => r.rarity > 100).length,
+            commonItems: items.filter((r) => r.rarity <= 50).length,
         };
     }
 }