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

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

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

Core Imports (Recommended)

The main osrs-tools export provides the most frequently used classes:

import { QuestTool, OsrsAccount, ClueScrollHelper, Item } from "osrs-tools";

// Use core API directly
const questTool = new QuestTool();
const account = OsrsAccount.fromJson({ name: "Player123" });

Subpackage Imports (Tree-Shakeable)

Import from subpackages for more granular control and better tree-shaking:

// Quest module - access all quests and quest utilities
import { QuestTool, DragonSlayerI } from "osrs-tools/quest";

// Slayer module - slayer masters and utilities
import { Duradel, SlayerMaster } from "osrs-tools/slayer";

// Account & skills
import { OsrsAccount, Skill } from "osrs-tools/account";

// Achievement diaries
import { Ardougne, DiaryName } from "osrs-tools/diary";

// Tools & utilities
import { ClueScrollHelper, experience } from "osrs-tools/tools";
import { cache, validation } from "osrs-tools/utils";

Quest System

// Access a specific quest
import { DragonSlayerI } from "osrs-tools/quest";

// Or get by name from QuestTool
import { QuestTool } from "osrs-tools";
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/slayer";

// 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/account";

// 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;

3D Item Models

import { yellowPartyhatModelPath } from "osrs-tools";

console.log(yellowPartyhatModelPath);
// "osrs-tools/models/YellowPartyhat.obj"

• Node.js: resolve the shipped asset with require.resolve(yellowPartyhatModelPath) and read it with fs.readFileSync(...).
• Bundlers: import the raw asset directly from osrs-tools/models/YellowPartyhat.obj or use a ?url suffix if your bundler supports it.

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 | Compile TypeScript to dist/ | | dev | Watch mode compilation | | test | Run test suite | | test:watch | Run tests in watch mode | | test:coverage | Generate coverage report | | lint | Lint and fix code | | format | Format code with Prettier |

Project Structure

source/                          # TypeScript source code
├── index.ts                      # Main entry point
├── runescape/
│   ├── model/
│   │   ├── account/             # Player account & skills
│   │   ├── diaries/             # Achievement diaries
│   │   ├── quest/               # Quest system
│   │   │   ├── all/             # Individual quest classes
│   │   │   └── index.ts         # Quest module export
│   │   ├── slayer/              # Slayer system
│   │   ├── Item/                # Item models
│   │   └── npc/                 # NPC data
│   ├── tools/                   # Utility tools (ClueScrollHelper, experience calc, etc.)
│   ├── utils/                   # Helper utilities (cache, validation, etc.)
│   └── errors.ts                # Custom error types
└── examples/                    # Usage examples

test/                            # Jest test suite
└── unit/
    ├── account/
    ├── diaries/
    ├── quest/
    ├── slayer/
    ├── model/
    ├── tools/
    └── utils/

dist/                            # Compiled output (generated by build)

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