osrs-tools 2.12.0 → 2.13.0

package/dist/runescape/model/slayer/core/MortimerSlayerMaster.d.ts

@@ -1,7 +1,7 @@
 import { Mortifier } from './Mortifier';
 import { SlayerMaster } from './SlayerMaster';
 import { Task } from './Task';
-import { SlayerMasterConfig } from './types';
+import { SlayerAssignmentContext, SlayerMasterConfig } from './types';
 /**
  * Configuration for Mortimer, extending the standard SlayerMaster config with the
  * quirks that make him behave differently to every other Slayer Master.
@@ -64,8 +64,12 @@ declare class MortimerSlayerMaster extends SlayerMaster {
      * Get a set of distinct, weighted-random task choices for a Mortimer visit.
      * The number of choices scales with completedTasks (see getTaskChoiceCount()).
      * Mortimer never offers the same task twice in a single set of choices.
-     * @returns {Task[]} The offered tasks. May be shorter than requested if there aren't enough distinct unblocked tasks.
+     * @param {number} [completedTasks] - Number of tasks completed with Mortimer so far.
+     * @param {SlayerAssignmentContext} [context] - The requesting player's Slayer level, completed
+     *  quests, and unlocked rewards; tasks the player doesn't qualify for are excluded (see
+     *  {@link SlayerMaster.getAvailableTasks}).
+     * @returns {Task[]} The offered tasks. May be shorter than requested if there aren't enough distinct eligible tasks.
      */
-    getTaskChoices(completedTasks?: number): Task[];
+    getTaskChoices(completedTasks?: number, context?: SlayerAssignmentContext): Task[];
 }
 export { MortimerSlayerMaster };

package/dist/runescape/model/slayer/core/MortimerSlayerMaster.js

@@ -67,11 +67,15 @@ class MortimerSlayerMaster extends SlayerMaster {
      * Get a set of distinct, weighted-random task choices for a Mortimer visit.
      * The number of choices scales with completedTasks (see getTaskChoiceCount()).
      * Mortimer never offers the same task twice in a single set of choices.
-     * @returns {Task[]} The offered tasks. May be shorter than requested if there aren't enough distinct unblocked tasks.
+     * @param {number} [completedTasks] - Number of tasks completed with Mortimer so far.
+     * @param {SlayerAssignmentContext} [context] - The requesting player's Slayer level, completed
+     *  quests, and unlocked rewards; tasks the player doesn't qualify for are excluded (see
+     *  {@link SlayerMaster.getAvailableTasks}).
+     * @returns {Task[]} The offered tasks. May be shorter than requested if there aren't enough distinct eligible tasks.
      */
-    getTaskChoices(completedTasks = 0) {
+    getTaskChoices(completedTasks = 0, context) {
         const choiceCount = this.getTaskChoiceCount(completedTasks);
-        const remainingTasks = this.getAvailableTasks().slice();
+        const remainingTasks = this.getAvailableTasks(context).slice();
         const choices = [];
         while (choices.length < choiceCount && remainingTasks.length > 0) {
             const totalWeight = remainingTasks.reduce((total, task) => total + (task.weight || 0), 0);

package/dist/runescape/model/slayer/core/SlayerMaster.d.ts

@@ -1,5 +1,5 @@
 import { Task } from './Task';
-import { SlayerMasterConfig } from './types';
+import { SlayerAssignmentContext, SlayerMasterConfig } from './types';
 /**
  * SlayerMaster class represents a Slayer Master in the game.
  * It encapsulates the properties and methods related to a Slayer Master,
@@ -51,9 +51,32 @@ declare class SlayerMaster {
     /**
      * Get a random task based on the weighting system of the tasks.
      * Tasks with higher weights have a higher chance of being selected.
+     * @param {SlayerAssignmentContext} [context] - The requesting player's Slayer level, completed
+     *  quests, and unlocked rewards. When provided, tasks the player doesn't qualify for are
+     *  excluded from both the candidate pool and the weight sum, per the task weighting formula
+     *  (see https://oldschool.runescape.wiki/w/Slayer#Task_weighting). When omitted, only blocked
+     *  tasks are excluded.
      * @returns {Task | null} A randomly selected task or null if no tasks are available.
      */
-    getRandomTask(): Task | null;
+    getRandomTask(context?: SlayerAssignmentContext): Task | null;
+    /**
+     * Get the percentage chance of being assigned each currently available task:
+     * (w / S) * 100, where w is a task's weight and S is the sum of weights of every task
+     * the player currently qualifies for (blocked, toggled-off, and requirement-locked tasks
+     * excluded from S). Reference: https://oldschool.runescape.wiki/w/Slayer#Task_weighting
+     * @param {SlayerAssignmentContext} [context] - The requesting player's Slayer level, completed
+     *  quests, and unlocked rewards. When omitted, only blocked tasks are excluded from S.
+     * @returns {Map<string, number>} Task name to percentage chance (0-100), for eligible tasks only.
+     */
+    getTaskChances(context?: SlayerAssignmentContext): Map<string, number>;
+    /**
+     * Get the percentage chance of being assigned a specific task, by name (case insensitive).
+     * @param {string} taskName - Name of the task to check.
+     * @param {SlayerAssignmentContext} [context] - See {@link getTaskChances}.
+     * @returns {number} The percentage chance (0-100) of being assigned this task, or 0 if the
+     *  task doesn't exist or isn't currently available to the player.
+     */
+    getTaskChance(taskName: string, context?: SlayerAssignmentContext): number;
     /**
      * Block a task so it will no longer be returned by getRandomTask().
      * Mirrors the in-game block list: only tasks this master actually assigns can be blocked.
@@ -76,9 +99,14 @@ declare class SlayerMaster {
      */
     getBlockedTasks(): string[];
     /**
-     * Get the tasks this master can currently assign, excluding blocked ones.
+     * Get the tasks this master can currently assign: excludes blocked tasks, and - when a
+     * player context is given - also excludes tasks whose Slayer level, combat level, skill,
+     * quest, or unlock requirements the player doesn't yet meet. A boosted Slayer level never
+     * unlocks a task; pass the player's base level.
+     * @param {SlayerAssignmentContext} [context] - The requesting player's stats/unlocks. When
+     *  omitted, requirement eligibility isn't checked (only the block list is applied).
      */
-    getAvailableTasks(): Task[];
+    getAvailableTasks(context?: SlayerAssignmentContext): Task[];
     /**
      * Get the total weight of tasks
      */

package/dist/runescape/model/slayer/core/SlayerMaster.js

@@ -1,3 +1,4 @@
+import { meetsRequirements } from './eligibility';
 /**
  * SlayerMaster class represents a Slayer Master in the game.
  * It encapsulates the properties and methods related to a Slayer Master,
@@ -95,12 +96,17 @@ class SlayerMaster {
     /**
      * Get a random task based on the weighting system of the tasks.
      * Tasks with higher weights have a higher chance of being selected.
+     * @param {SlayerAssignmentContext} [context] - The requesting player's Slayer level, completed
+     *  quests, and unlocked rewards. When provided, tasks the player doesn't qualify for are
+     *  excluded from both the candidate pool and the weight sum, per the task weighting formula
+     *  (see https://oldschool.runescape.wiki/w/Slayer#Task_weighting). When omitted, only blocked
+     *  tasks are excluded.
      * @returns {Task | null} A randomly selected task or null if no tasks are available.
      */
-    getRandomTask() {
-        const availableTasks = this.getAvailableTasks();
+    getRandomTask(context) {
+        const availableTasks = this.getAvailableTasks(context);
         if (availableTasks.length === 0)
-            return null; // Return null if there are no unblocked tasks
+            return null; // Return null if there are no eligible tasks
         const availableWeight = availableTasks.reduce((total, task) => total + (task.weight || 0), 0);
         if (availableWeight <= 0)
             return null;
@@ -114,6 +120,41 @@ class SlayerMaster {
         }
         return null; // Fallback in case no task is selected (shouldn't happen if weights are correct)
     }
+    /**
+     * Get the percentage chance of being assigned each currently available task:
+     * (w / S) * 100, where w is a task's weight and S is the sum of weights of every task
+     * the player currently qualifies for (blocked, toggled-off, and requirement-locked tasks
+     * excluded from S). Reference: https://oldschool.runescape.wiki/w/Slayer#Task_weighting
+     * @param {SlayerAssignmentContext} [context] - The requesting player's Slayer level, completed
+     *  quests, and unlocked rewards. When omitted, only blocked tasks are excluded from S.
+     * @returns {Map<string, number>} Task name to percentage chance (0-100), for eligible tasks only.
+     */
+    getTaskChances(context) {
+        const availableTasks = this.getAvailableTasks(context);
+        const availableWeight = availableTasks.reduce((total, task) => total + (task.weight || 0), 0);
+        const chances = new Map();
+        if (availableWeight <= 0)
+            return chances;
+        for (const task of availableTasks) {
+            chances.set(task.getName(), ((task.weight || 0) / availableWeight) * 100);
+        }
+        return chances;
+    }
+    /**
+     * Get the percentage chance of being assigned a specific task, by name (case insensitive).
+     * @param {string} taskName - Name of the task to check.
+     * @param {SlayerAssignmentContext} [context] - See {@link getTaskChances}.
+     * @returns {number} The percentage chance (0-100) of being assigned this task, or 0 if the
+     *  task doesn't exist or isn't currently available to the player.
+     */
+    getTaskChance(taskName, context) {
+        const normalized = taskName.toLowerCase();
+        for (const [name, chance] of this.getTaskChances(context)) {
+            if (name.toLowerCase() === normalized)
+                return chance;
+        }
+        return 0;
+    }
     /**
      * Block a task so it will no longer be returned by getRandomTask().
      * Mirrors the in-game block list: only tasks this master actually assigns can be blocked.
@@ -149,10 +190,21 @@ class SlayerMaster {
         return Array.from(this.blockedTasks);
     }
     /**
-     * Get the tasks this master can currently assign, excluding blocked ones.
-     */
-    getAvailableTasks() {
-        return this.tasks.filter(task => !this.isTaskBlocked(task.getName()));
+     * Get the tasks this master can currently assign: excludes blocked tasks, and - when a
+     * player context is given - also excludes tasks whose Slayer level, combat level, skill,
+     * quest, or unlock requirements the player doesn't yet meet. A boosted Slayer level never
+     * unlocks a task; pass the player's base level.
+     * @param {SlayerAssignmentContext} [context] - The requesting player's stats/unlocks. When
+     *  omitted, requirement eligibility isn't checked (only the block list is applied).
+     */
+    getAvailableTasks(context) {
+        return this.tasks.filter(task => {
+            if (this.isTaskBlocked(task.getName()))
+                return false;
+            if (!context)
+                return true;
+            return meetsRequirements(task.getRequirements(), context);
+        });
     }
     /**
      * Get the total weight of tasks

package/dist/runescape/model/slayer/core/eligibility.d.ts

@@ -0,0 +1,7 @@
+import { Requirement } from '../../Requirement';
+import { SlayerAssignmentContext } from './types';
+/**
+ * Checks whether every requirement in the list is satisfied by the given player context.
+ * A task with no requirements is always eligible.
+ */
+export declare function meetsRequirements(requirements: Requirement[], context: SlayerAssignmentContext): boolean;

package/dist/runescape/model/slayer/core/eligibility.js

@@ -0,0 +1,41 @@
+import { RequirementType, } from '../../Requirement';
+function toLowerCaseSet(values) {
+    const result = new Set();
+    if (!values)
+        return result;
+    for (const value of values)
+        result.add(value.toLowerCase());
+    return result;
+}
+/**
+ * Checks whether a single requirement is satisfied by the given player context.
+ * Requirement types that don't gate task assignment (e.g. items to bring) are
+ * always treated as satisfied - only Slayer level, combat level, skill level,
+ * quest, and Slayer unlock requirements can block an assignment.
+ */
+function meetsRequirement(requirement, context) {
+    switch (requirement.type) {
+        case RequirementType.SlayerLevel:
+            return (context.slayerLevel ?? 0) >= requirement.level;
+        case RequirementType.CombatLevel:
+            return (context.combatLevel ?? 0) >= requirement.level;
+        case RequirementType.Level: {
+            const levelRequirement = requirement;
+            const playerLevel = context.skillLevels?.[levelRequirement.skillName] ?? 0;
+            return playerLevel >= levelRequirement.level;
+        }
+        case RequirementType.Quest:
+            return toLowerCaseSet(context.completedQuests).has(requirement.questName.toLowerCase());
+        case RequirementType.SlayerUnlock:
+            return toLowerCaseSet(context.unlockedRewards).has(requirement.name.toLowerCase());
+        default:
+            return true;
+    }
+}
+/**
+ * Checks whether every requirement in the list is satisfied by the given player context.
+ * A task with no requirements is always eligible.
+ */
+export function meetsRequirements(requirements, context) {
+    return requirements.every(requirement => meetsRequirement(requirement, context));
+}

package/dist/runescape/model/slayer/core/index.d.ts

@@ -10,5 +10,5 @@ export { MortimerSlayerMaster } from './MortimerSlayerMaster';
 export { SlayerMaster } from './SlayerMaster';
 export type { TaskJson } from './Task';
 export { Task } from './Task';
-export type { SlayerMasterConfig, TaskDefinition, TaskOptions, TaskQuantity } from './types';
+export type { SlayerAssignmentContext, SlayerMasterConfig, TaskDefinition, TaskOptions, TaskQuantity, } from './types';
 export { POINTS_TABLE, SlayerBoss, SlayerLocation, TASK_DEFAULTS } from './types';

package/dist/runescape/model/slayer/core/types.d.ts

@@ -94,6 +94,24 @@ export interface TaskDefinition {
  * Builder options for creating tasks (alias for TaskDefinition)
  */
 export type TaskOptions = TaskDefinition;
+/**
+ * Describes what a specific player currently has access to, for the purposes of
+ * filtering which Slayer tasks a master is allowed to assign them.
+ * All fields are optional; an omitted field is treated as "player has none of these"
+ * (e.g. no completed quests), which is the conservative/safe default for eligibility checks.
+ */
+export interface SlayerAssignmentContext {
+    /** The player's base (unboosted) Slayer level. Boosts never unlock higher-tier tasks. */
+    slayerLevel?: number;
+    /** The player's combat level. */
+    combatLevel?: number;
+    /** Names of quests the player has completed (case-insensitive). */
+    completedQuests?: Iterable<string>;
+    /** Names of Slayer unlocks the player has purchased with reward points (case-insensitive). */
+    unlockedRewards?: Iterable<string>;
+    /** Base skill levels keyed by skill name, for tasks with non-Slayer skill requirements. */
+    skillLevels?: Partial<Record<string, number>>;
+}
 /**
  * Slayer Master configuration interface
  */

package/dist/runescape/model/slayer/index.d.ts

@@ -3,7 +3,7 @@
  * Complete slayer system including masters, tasks, rewards, and utilities
  * Reference: https://oldschool.runescape.wiki/w/Slayer
  */
-export type { MortifierConfig, MortimerSlayerMasterConfig, SlayerMasterConfig, TaskDefinition, TaskOptions, TaskQuantity, } from './core';
+export type { MortifierConfig, MortimerSlayerMasterConfig, SlayerAssignmentContext, SlayerMasterConfig, TaskDefinition, TaskOptions, TaskQuantity, } from './core';
 export { Assignment, getAvailableMortifiers, getMortifierByName, Mortifier, MORTIFIERS, MortimerSlayerMaster, SlayerMaster, Task, } from './core';
 export { POINTS_TABLE, SlayerBoss, SlayerLocation, TASK_DEFAULTS } from './core';
 export type { SlayerMasterProgression } from './masters';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osrs-tools",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "A comprehensive TypeScript library for Old School RuneScape (OSRS) data and utilities, including quest data, skill requirements, and general game information",
   "license": "MIT",
   "sideEffects": false,