OSRS Tools

A fully-typed TypeScript library of Old School RuneScape game data and logic — quests, accounts, diaries, combat achievements, slayer, clues, items, and more.

Zero runtime dependencies, dual CJS/ESM output, tree-shakeable, Node ≥ 18.

Install

npm install osrs-tools

Quick Start

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

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

const questTool = new QuestTool(account);
const dragonSlayer = QuestTool.getQuestByName("Dragon Slayer I");

console.log(questTool.canCompleteQuest(dragonSlayer));

Import from the root package or from a subpath to keep bundles small:

import { Duradel, getMasterByName } from "osrs-tools/slayer";
import { DiaryTool, getDiaryByName } from "osrs-tools/diary";
import { CombatAchievementTool } from "osrs-tools/combat-achievements";

What's included

Module	Subpath	Highlights
Quests	osrs-tools/quest	QuestTool, 189+ quests, requirement classes (level, quest, item, combat, location…)
Accounts	osrs-tools/account	OsrsAccount (hiscores-compatible), Skill enum, skill metadata
Diaries	osrs-tools/diary	10 regional achievement diaries, DiaryTool for progress checks
Combat Achievements	osrs-tools/combat-achievements	All 637 tasks across six tiers, CombatAchievementTool
Slayer	osrs-tools/slayer	9 masters, tasks, points, unlocks/extends/buys
Experience	osrs-tools/tools	XP ⇄ level conversion, full XP table
Validation	osrs-tools/utils	Skill/level validation, ValidationError
Clues, items, guilds, leagues	root osrs-tools import	ClueScrollHelper, Item, HunterGuild, league data

For the full API surface and source layout, see summary.md.

Development

git clone https://github.com/jamescer/osrs-tools.git
cd osrs-tools
npm install
npm run build
npm test

Command	Description
npm run build	Compile TypeScript to dist/
npm test	Run the test suite
npm run lint	Lint and auto-fix with ESLint
npm run format	Format with Prettier
npm run changeset	Record a change for the next release

See dev_setup.md for the full setup and release workflow.

Contributing

Contributions are welcome. We use Conventional Commits and changesets for releases.

1. Fork and clone the repo, create a branch
2. Make your change and add tests
3. npm test && npm run lint
4. npm run changeset to record a changelog entry
5. Open a pull request

Please also review our Code of Conduct and Security Policy.

License

MIT © James Cerniglia

Data sourced from the Old School RuneScape Wiki.