OSRS Item Data

A TypeScript package for parsing Old School RuneScape item IDs, names, and icon images from the OSRS Wiki.

Features

• 16,000+ OSRS Items: Pre-scraped data from the OSRS Wiki
• Image URL Generation: Automatically construct image URLs for any item
• TypeScript Support: Full type definitions included
• Flexible API: Search by ID, name, or filter items
• Variant Handling: Properly handles item variants (e.g., charged, broken, poisoned)
• Zero Dependencies: No runtime dependencies (scraper uses cheerio for build-time only)

Installation

npm install osrs-item-data

Quick Start

import { getItemById, searchItemsByName, getItemImageUrl } from 'osrs-item-data';

// Get item by ID
const item = getItemById(13263);
console.log(item);
// {
//   id: 13263,
//   name: 'Abyssal bludgeon',
//   baseName: 'Abyssal bludgeon',
//   imageUrl: 'https://oldschool.runescape.wiki/images/thumb/Abyssal_bludgeon_detail.png/120px-Abyssal_bludgeon_detail.png'
// }

// Search items by name
const items = searchItemsByName('dragon');
console.log(items.length); // All items with "dragon" in the name

// Get image URL for any item
const imageUrl = getItemImageUrl('Abyssal whip');
console.log(imageUrl);
// 'https://oldschool.runescape.wiki/images/thumb/Abyssal_whip_detail.png/120px-Abyssal_whip_detail.png'

API Reference

Item Lookup Functions

getItemById(id: number): OsrsItem | undefined

Retrieve an item by its numeric ID.

const item = getItemById(4151); // Dragon warhammer

getItemsById(id: number): OsrsItem[]

Get all items matching a specific ID (handles cases where multiple variants share IDs).

const items = getItemsById(1704); // All items with ID 1704

getItemByName(name: string): OsrsItem | undefined

Get an item by its exact name (case-sensitive).

const item = getItemByName('Twisted bow');

searchItemsByName(query: string, limit?: number): OsrsItem[]

Search for items by name (case-insensitive, partial match).

const items = searchItemsByName('godsword', 5); // First 5 items matching "godsword"

getAllItems(filter?: ItemFilter): OsrsItem[]

Get all items, optionally filtered.

// Get all items
const allItems = getAllItems();

// Get items with variants only
const variantItems = getAllItems({ hasVariant: true });

// Get first 100 items containing "rune"
const runeItems = getAllItems({
  nameContains: 'rune',
  limit: 100
});

Utility Functions

getItemImageUrl(itemName: string, options?: ImageUrlOptions): string

Construct an image URL for any item name.

// Default: 120px thumbnail with variant
const url = getItemImageUrl('Amulet of glory#4');

// Custom width
const url = getItemImageUrl('Dragon scimitar', { width: 96 });

// Full-size image
const url = getItemImageUrl('Dragon scimitar', { useThumb: false });

// Exclude variant from URL
const url = getItemImageUrl('Amulet of glory#4', { includeVariant: false });

getItemImageUrls(itemName: string, options?: ImageUrlOptions)

Get both variant and base image URLs (useful for fallback).

const { variantUrl, baseUrl } = getItemImageUrls('Amulet of glory#4');
// variantUrl: URL with (4) in filename
// baseUrl: URL without variant

parseItemName(itemName: string)

Parse an item name into base name and variant.

const { baseName, variant } = parseItemName('Corrupted scythe of vitur#Charged');
// baseName: 'Corrupted scythe of vitur'
// variant: 'Charged'

Aggregate Functions

getItemCount(): number

Get the total number of items in the dataset.

getUniqueBaseNames(): string[]

Get all unique base item names (without variants).

getItemVariants(baseName: string): OsrsItem[]

Get all variants for a specific base item name.

const variants = getItemVariants('Amulet of glory');
// Returns all glory variants: base, #1, #2, #3, #4, #5, #6

TypeScript Types

interface OsrsItem {
  id: number | number[];  // Single ID or array for items with ID ranges
  name: string;           // Full name including variant (e.g., "Amulet of glory#4")
  baseName: string;       // Name without variant (e.g., "Amulet of glory")
  variant?: string;       // Variant identifier (e.g., "4", "Charged", "(p)")
  imageUrl: string;       // Pre-constructed image URL
}

interface ImageUrlOptions {
  width?: number;         // Thumbnail width in pixels (default: 120)
  useThumb?: boolean;     // Use thumbnail vs full-size (default: true)
  includeVariant?: boolean; // Include variant in filename (default: true)
}

interface ItemFilter {
  nameContains?: string;  // Filter by name substring (case-insensitive)
  hasVariant?: boolean;   // Filter items with/without variants
  limit?: number;         // Limit number of results
}

Understanding Item Variants

OSRS items often have variants denoted by a # symbol:

• Charge levels: Amulet of glory#1 through #6
• Damage states: Ahrim's hood#100, #75, #50, #25, #broken
• Status effects: Abyssal dagger#(p), Adamant arrow#(p++)
• Item states: Corrupted scythe of vitur#Charged

The package handles these automatically:

• The # postfix is removed when constructing image URLs
• Variants are converted to parentheses format: item#variant → item(variant)_detail.png
• You can choose to include or exclude variants in image URLs

Updating Item Data

The package includes a scraper script to update item data:

npm run scrape

This fetches the latest data from the OSRS Wiki and updates src/data/items.json.

Note: You only need to run this if you're contributing to the package or want to update to the latest wiki data.

Publishing to NPM

This package is configured to publish automatically via GitHub Actions:

1. Create a release on GitHub
2. The workflow will automatically:
   • Run tests
   • Build the package
   • Publish to NPM

Setup required:

• Add NPM_TOKEN to your repository secrets
• Get your NPM token from https://www.npmjs.com/settings/[username]/tokens

Development

# Install dependencies
npm install

# Run tests
npm test

# Build package
npm run build

# Scrape latest data
npm run scrape

How It Works

1. Scraping: The scraper fetches the Item_IDs wiki page and parses the item table
2. Image URLs: Image URLs are constructed using the wiki's image naming convention
3. Special Characters: Apostrophes, parentheses, and other special characters are properly URL-encoded
4. Variants: Item variants (denoted by #) are handled by converting them to parentheses format

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run npm test to ensure all tests pass
5. Submit a pull request

License

MIT

Data Source

All item data is sourced from the Old School RuneScape Wiki, which is licensed under CC BY-NC-SA 3.0.

Disclaimer

This package is not affiliated with or endorsed by Jagex Ltd. Old School RuneScape is a registered trademark of Jagex Ltd.