OSRS Tools

A modern TypeScript library for Old School RuneScape (OSRS) data and utilities. Built for developers creating tools, bots, web applications, and analytics around OSRS content.

📦 Type-safe   🚀 Well-tested   📚 Documented   🔄 Actively maintained

Live Demo

Explore the project interactively on CodeSandbox:

Table of Contents

• Features
• Installation
• Examples
• Development
• Contributing
• Support
• License

Features

✨ Quest System

• Complete quest database with requirements and rewards
• Quest dependency tracking and validation
• Experience and item reward calculations
• Quest point tracking
• Support for miniquests

🎯 Skill & Level System

• Skill level tracking and validation
• Support for boostable requirements
• Combat level calculations
• Quest point requirements

🗡️ Items & Equipment

• Comprehensive item database
• Equipment statistics
• Trading and value information
• Quest item tracking

👹 Slayer System

• Full slayer master task lists
• Task weights and assignment logic
• Slayer requirement validation
• Reward shop data

Installation

Prerequisites

• Node.js 16.x or higher
• TypeScript 4.9+

Package Installation

npm install osrs-tools

For account-related features (hiscores, stats):

npm install osrs-json-hiscores

Examples

Quest System

import { QuestTool, Quest } from 'osrs-tools';

// Get quest information
const dragonSlayer = QuestTool.getQuestByName('Dragon Slayer');
console.log(dragonSlayer.requirements);

// Check quest completion requirements
const questTool = new QuestTool();
questTool.setOsrsAccount(playerAccount);
const canComplete = questTool.canCompleteQuest(dragonSlayer);

Slayer System

import { Duradel } from 'osrs-tools';

// Get master's task list
const tasks = Duradel.tasks;

// Get random assignment
const task = Duradel.getRandomTask();
console.log(task.name); // e.g., "Abyssal demons"
console.log(task.requirements); // Shows requirements

Account Management

import { OsrsAccount } from 'osrs-tools';

// Create/load account
const account = OsrsAccount.fromJson({
  name: 'Player123',
  skills: {
    attack: { level: 60 },
    strength: { level: 55 },
    defence: { level: 50 },
  },
});

// Get skill levels
const attackLevel = account.getSkill('attack')?.level;

Documentation Links

• Full API Documentation
• Type Definitions
• Code Examples

Development

Local Setup

# Clone and setup
git clone https://github.com/jamescer/osrs-tools.git
cd osrs-tools
npm install

# Build and test
npm run build
npm test

Available Scripts

| Command | Description | | ------------ | ----------------------- | | build | Build the project | | test | Run tests | | test:watch | Run tests in watch mode | | lint | Lint the code | | format | Format the code | | docs | Generate documentation |

Contributing

We welcome contributions! We use Conventional Commits.

Getting Started

1. Fork and clone the repository

2. Create a branch (feat/amazing-feature)

3. Make your changes

4. Run tests (npm test && npm run lint)

5. Commit with conventional format:

   feat: add quest requirement validation
   fix: correct slayer task weights
   docs: update API documentation

6. Push and open a Pull Request

Guidelines

• Add tests for new features
• Update documentation for changes
• Follow existing code style
• Keep changes focused

Support

Need help or want to contribute?

• Report Issues
• Request Features
• Join Discussions

License

MIT © James Cerniglia

Credits

• Author: James Cerniglia
• Contributors: View all contributors
• Data Source: Old School RuneScape Wiki