OldSchoolJS
A NodeJS library for doing everything OSRS related. Access the OSRS hiscores, news, worlds, wiki, items, simulating killing monsters, and opening clue caskets - and more.
For discussion, help or questions - please join https://discord.gg/ob and then our #developers channel.
Automatically generated docs are available at: https://docs.oldschool.gg/
Hiscores
Docs: https://docs.oldschool.gg/classes/hiscores.html
Possible account types: normal, ironman, ultimate, hardcore, deadman, seasonal
You can also pass virtualLevels: true to receive their stats back in virtual level format, with their skill levels able to go up to 120.
import { Hiscores } from 'oldschooljs';
const lynxTitan = await Hiscores.fetch('Lynx Titan');
const ironHyger = await Hiscores.fetch('Iron Hyger', { type: 'ironman' });Items
import { Items } from 'oldschooljs';Getting an Item by ID
const twistedBow = Items.get(20997);
if (twistedBow) console.log(twistedBow);Getting an Item by Name
const dragonDagger = Items.get('dragon dagger(p++)');
if (dragonDagger) console.log(dragonDagger);Find items by any properties
const dragonItems = Items.filter(item => item.name.includes('Dragon'));
console.log(`Found ${dragonItems.size} Dragon Items!`);
for (const item of dragonItems.values()) {
console.log(item.name);
}Monster Killing Simulator
Allows you to simulate killing monsters. The loot is returned in an object, where the key is the item ID and the quantity is the value.
import { Monsters } from 'oldschooljs';Simulating 100 Kills of every Monster
Monsters.map(monster => monster.kill(100));Simulating 100 Corp beast kills
Monsters.CorporealBeast.kill(100);
Monsters.find(monster => monster.name.aliases.includes('corp')).kill(100);
Monsters.get(319).kill(100);Clue Scroll Simulating
Allows you to simulate opening clue scroll caskets. The rewards are returned in a format containing the item ID and the quantity.
import { Clues } from 'oldschooljs';console.log(Clues.Beginner.open(1));
console.log(Clues.Master.open(5));
console.log(Clues.Elite.open());Banks
Docs: https://docs.oldschool.gg/classes/bank.html
The bank class provides a powerful and ergonomic way to construct and interact with item banks.
const bank = new Bank().add('Twisted bow');
const otherBank = new Bank().add('Coal');
const lootTable = new LootTable().add(;
bank
.add(otherBank)
.add({ Coal: 1 })
.add('Coal')
.add('Coal', 500)
.add({ 124: 500 })
.add(lootTable.roll())
.add(CorporealBeast.kill());
console.log(bank.values());Loot Tables
Docs: https://docs.oldschool.gg/classes/loottable.html
For a good demonstration of using Loot tables, refer to the oldschooljs code for Monsters and Clues, which all use loottables, a good example is Corp: https://github.com/oldschoolgg/oldschooljs/blob/master/src/simulation/monsters/bosses/CorporealBeast.ts
Here is a trimmed-down example of corp:
const CorporealBeastTable = new LootTable()
.add('Spirit shield', 1, 8)
.add('Holy elixir', 1, 3)
.oneIn(585, SigilTable)
.tertiary(5000, 'Pet dark core');
CorporealBeastTable.roll();News
import { News } from 'oldschooljs';Be careful with fetching news articles too often, as the website will ratelimit you after roughly 30 requests in a short period. Whenever a fetch is done, the News collection will have any new articles cached.
Rather than fetching articles on demand, you may want to
Fetch recent news articles
const recentArticles = await News.fetchRecent();
const mostRecentArticle = recentArticles.first();Get news articles for a specific month
const monthOfArticles = await News.filter(article => article.year === 2018 && article.month === 12);
console.log(`There were ${monthOfArticles.size} articles in that month.`);Fetch news articles for a specific month
This will fetch news articles for a specific month, i.e it wont be cached. In most cases you can just use News.filter() instead of this.
const monthOfArticles = await News.fetchMonth({ year: 2018, month: 12 });
console.log(`There were ${monthOfArticles.size} articles in that month.`);List every available news article
If you want this to be up to 100% up to date, you need to call News.fetchNewArticles() to fetch newly released articles that aren't cached by oldschooljs.
for (const article of News.values()) {
console.log(article);
}Worlds
import { Worlds } from 'oldschooljs';Fetch and cache all worlds
You must call this atleast once to be able to use Worlds. To keep worlds up to date, fetching once at startup and then once every few days is enough. If you need an up to date playercount of worlds, you can call it more often or on demand.
await Worlds.fetch();Getting a particular world
You can use either form of numbering, giving 301 and 1 will both give you World 1.
const worldOne = Worlds.get(301);
const worldTwo = Worlds.get(2);Filtering Worlds
const australianWorlds = Worlds.filter(world => world.location === 'Australia');
console.log(`There are ${australianWorlds.size} Australian Worlds!`);Iterating over worlds
for (const world of Worlds.values()) {
console.log(world);
}Wiki
import { Wiki } from 'oldschooljs';Searching for pages
const searchResults = await Wiki.search('Twisted bow');
if (searchResults.length === 0) console.log('Found no results');
else console.log(`Search found these pages: ${searchResults.map(page => page.title)}`);Picking random pages
const randomPages = await Wiki.random(10);
console.log(`Search found these pages: ${searchResults.map(page => page.title)}`);Fetch page by ID
const twistedBowPage = await Wiki.fetchPage(82098);
console.log(twistedBowPage);Polls
import { Polls } from 'oldschooljs';Iterating over worlds
for (const poll of Polls.values()) {
console.log(poll.title);
}Getting all polls in a year
const pollsFrom2013 = Polls.filter(poll => new Date(poll.datePosted).getFullYear() === 2013);
console.log(pollsFrom2013.size);Utilities
import { Util } from 'oldschooljs';Checking if a username is valid
console.log(Util.isValidUsername(username)); // trueConverting numbers to and from KMB syntax
KMB Syntax is how numbers are often formatted in runescape, for example: 5k, 1.5m, 5m, 1b, etc.
Util.toKMB(5); // '5'
Util.toKMB(1000); // '1k'
Util.toKMB(1000000); // '1m'
Util.toKMB(1200000000); // '1.2b'Util.fromKMB('5'); // 5
Util.fromKMB('1k'); // 1000
Util.fromKMB('1m'); // 1000000
Util.fromKMB('1.2b'); // 1200000000Planned features
- Ability to ping worlds?
- CrystalMathLabs
- Simulating: killing monsters, opening clue scrolls, pets (like in osbot)
- Quests (e.g. containing all wiki data on quests)
- fetch wiki page by item ID?