osrs-tools
Version:
A comprehensive TypeScript library for Old School RuneScape (OSRS) data and utilities, including quest data, skill requirements, and game item information
208 lines (207 loc) • 7.57 kB
JavaScript
/**
* QUICK REFERENCE GUIDE
* How to Implement Drops for a New NPC
* ==========================================
*/
// ============================================================================
// PATTERN 1: Simple Combat NPC (Bones + Coins)
// ============================================================================
// Use this for most common creatures
import { Npc } from '../Npc';
import { NpcDrop } from '../NpcDrop';
import { DROP_RATES, createDragonDrops, createDemonDrops, createBossNPCDrops } from './DropImplementationUtils';
const SimpleNpcDrops = [
new NpcDrop('Bones', 1, 'Always'), // Guaranteed
new NpcDrop('Coins', [25, 75], 'Always'), // Guaranteed loot
new NpcDrop('Clue Scroll (Easy)', 1, DROP_RATES.UNCOMMON_1_256), // Clue drop
];
// ============================================================================
// PATTERN 2: Slayer Creature (Bones + Special Loot + Rare)
// ============================================================================
// Use for Slayer-specific creatures
const SlayerCreatureDrops = [
new NpcDrop('Bones', 1, 'Always'),
new NpcDrop('Granite Dust', [4, 8], 'Always'),
new NpcDrop('Granite Maul', 1, '1/256'),
];
// ============================================================================
// PATTERN 3: Dragon (Use createDragonDrops)
// ============================================================================
// Use for all dragon types
const DragonDrops = createDragonDrops({
tier: 'baby', // 'baby' | 'chromatic' | 'metallic' | 'elder'
hasUniqueDrops: false,
});
// ============================================================================
// PATTERN 4: Demon (Use createDemonDrops)
// ============================================================================
// Use for all demon types
const DemonDrops = createDemonDrops({
tier: 'lesser', // 'lesser' | 'greater' | 'black' | 'abyssal'
});
// ============================================================================
// PATTERN 5: Boss with Multi-Roll (Use createBossNPCDrops)
// ============================================================================
// Use for bosses with multiple guaranteed drops + 1/512 unique
const BossDrops = createBossNPCDrops({
primaryDrops: [
new NpcDrop('Boss Essence', 1, 'Always'),
new NpcDrop('Coins', [1000, 5000], 'Always'),
],
rareDrops: [
{ item: new NpcDrop('Unique Item 1', 1, 'Always'), weight: 1 },
{ item: new NpcDrop('Unique Item 2', 1, 'Always'), weight: 1 },
],
uniqueRate: '1/512',
});
// ============================================================================
// COMPLETE EXAMPLE: One Simple NPC
// ============================================================================
export const Rat = new Npc(1, 'Rat', 'A small rat.', false, 1, 'https://oldschool.runescape.wiki/w/Rat', 3, false, true, false, false, false, false, false, ['Melee'], 1, 5, 15, ['Various'], [
new NpcDrop('Bones', 1, 'Always'),
], ['Stab']);
// ============================================================================
// WORKFLOW
// ============================================================================
/**
* For each NPC, follow these steps:
*
* 1. RESEARCH
* - Open OSRS Wiki page
* - Find "Drops" section
* - Note all items, quantities, drop rates
* - Look for quest-only or conditional drops
*
* 2. CATEGORIZE
* - Is this NPC similar to others? (Dragons, demons, etc.)
* - Can we use a template? (createDragonDrops, etc.)
* - Or should we write custom drops?
*
* 3. IMPLEMENT
* - Copy pattern that matches your NPC
* - Replace itemIds with actual items
* - Use DROP_RATES constants for readable fractions
* - Add wiki URL to NPC constructor
*
* 4. TEST
* - Run: npm test
* - Verify no syntax errors
* - Check drop rates make sense
*
* 5. VALIDATE
* - Use validateNPCDrops() to check for errors
* - Compare with wiki - do drops match?
* - Check for missing items
*
* 6. COMMIT
* - git add source/runescape/model/npc/npcs/YourNPC.ts
* - git commit -m "Add drops for YourNPC"
* - Push to your branch
*/
// ============================================================================
// COMMON NPC CATEGORIES & ESTIMATED TIME
// ============================================================================
/**
* BOSSES (30 NPCs)
* - Time per: 10-15 mins (complex research)
* - Template: createBossNPCDrops()
* - Total est: 5-7.5 hours
* - Value: HIGH (players farm these extensively)
*
* DRAGONS (20 NPCs)
* - Time per: 2-3 mins (template does most work)
* - Template: createDragonDrops()
* - Total est: 40-60 mins
* - Value: MEDIUM (Slayer, PvM)
*
* DEMONS (15 NPCs)
* - Time per: 2-3 mins (template does most work)
* - Template: createDemonDrops()
* - Total est: 30-45 mins
* - Value: MEDIUM (Slayer)
*
* SLAYER CREATURES (30 NPCs)
* - Time per: 3-5 mins (simple but varied)
* - Template: Custom for each subtype
* - Total est: 90-150 mins (1.5-2.5 hours)
* - Value: MEDIUM-HIGH (frequent killing)
*
* ANIMALS (20 NPCs)
* - Time per: 1-2 mins (simple, low loot complexity)
* - Template: SimpleNpcDrops pattern
* - Total est: 20-40 mins
* - Value: LOW (rarely killed for loot)
*
* QUEST NPCS (15 NPCs)
* - Time per: 5-10 mins (may have no drops)
* - Template: Varies or empty
* - Total est: 75-150 mins (1.25-2.5 hours)
* - Value: LOW (not used for loot)
*
* TOTAL ESTIMATE: 8-12.5 hours spread over 1-2 weeks
*/
// ============================================================================
// DROP RATES QUICK REFERENCE
// ============================================================================
/**
* Available constants in DROP_RATES:
*
* ALWAYS = '100%'
* COMMON_1_2 = '1/2'
* COMMON_1_4 = '1/4'
* COMMON_1_8 = '1/8'
* FREQUENT_1_16 = '1/16'
* FREQUENT_1_32 = '1/32'
* UNCOMMON_1_64 = '1/64'
* UNCOMMON_1_128 = '1/128'
* RARE_1_256 = '1/256'
* RARE_1_512 = '1/512'
* VERY_RARE_1_1024 = '1/1024'
* VERY_RARE_1_2048 = '1/2048'
*
* Or use custom strings like:
* new NpcDrop('Item', 1, '3/512') // Unusual rates
*/
// ============================================================================
// VALIDATION CHECKLIST
// ============================================================================
/**
* Before committing each NPC:
*
* ✓ Wiki URL is included and correct
* ✓ Drop rates match wiki (check wiki vs code)
* ✓ Item IDs are real items in the system
* ✓ Quantities make sense (not 999 of an item)
* ✓ No typos in item names
* ✓ Drop table is not empty (unless intentional)
* ✓ No duplicate item entries in same table
* ✓ Build passes: npm run build
* ✓ Tests pass: npm test
* ✓ Code style matches team standards
* ✓ Comment explains non-obvious drops (if any)
*/
// ============================================================================
// USEFUL COMMANDS
// ============================================================================
/**
* # Build and test
* npm run build
* npm test
* npm test test/unit/npc/NpcDrop.test.ts
*
* # Check for compile errors in NPC files only
* npx tsc source/runescape/model/npc/**\/*.ts --noEmit
*
* # Check specific NPC
* git diff source/runescape/model/npc/npcs/YourNPC.ts
*
* # Run tests for NPCs only
* npm test -- --testPathPattern="npc"
*/
export default {
SimpleNpcDrops,
SlayerCreatureDrops,
DragonDrops,
DemonDrops,
BossDrops,
};