Skip to main content

ID Maps

com.n3plugins.sdk.idmaps.IdMapRegistry loads generated item, NPC, and object name/ID lookups without scraping at RuneLite runtime.

Bundled maps live on the classpath under com/n3plugins/sdk/idmaps/:

  • items_name_to_id.json, items_id_to_name.json
  • npcs_name_to_id.json, npcs_id_to_name.json
  • objects_name_to_id.json, objects_id_to_name.json
  • id-map-manifest.json

The registry prefers a complete local cache for the active client revision:

RuneLite.RUNELITE_DIR/n3Plugins/id-maps/rev-238/

Cache validity requires all six map files plus id-map-manifest.json with the matching clientRevision, the items, npcs, and objects categories, generatedAt, and source. If the cache is missing, stale, incomplete, or malformed, IdMapRegistry.loadBestAvailable(...) falls back to the bundled maps.

Lookup API:

IdMapRegistry maps = IdMapRegistry.getDefault();

Optional<String> itemName = maps.itemName(995);
List<Integer> itemIds = maps.itemIds("Coins");
Optional<String> npcName = maps.npcName(3871);
List<Integer> npcIds = maps.npcIds("'Beedy-eye' Jones");
Optional<String> objectName = maps.objectName(13153);
List<Integer> objectIds = maps.objectIds("4-poster");

Query helpers:

  • ItemQuery.withMappedName(String name)
  • NPCQuery.withMappedName(String name)
  • TileObjectQuery.withMappedName(String name)

These helpers resolve IDs through the registry and then filter by ID. ItemQuery.withMappedName(...) also includes RuneLite's bundled item variation groups for the current rev239 release, so a mapped base name such as Ancient sceptre can match its released locked/broken/mangled variants. Existing withName(...) methods remain exact visible-name filters and are intentionally unchanged.

Refresh handling is explicit and import-based. osrs_wiki_scraper (2).py remains a development/offline generator; the RuneLite plugin does not run Python, import Python dependencies, or scrape the wiki during startup. After fresh JSON files exist, call IdMapRegistry.importGenerated(...) to validate and copy them into the revision cache with a manifest.