Skip to main content

ID Maps

Verification boundary

This page describes the committed source behavior. It skips certifying revision-sensitive RuneLite UI, packet, or in-game outcomes; treat those as live-client verification pending unless the page records direct evidence.

com.n3plugins.sdk.idmaps.IdMapRegistry dynamically loads generated item, NPC, and object name/ID lookups.

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-240/

Cache validity requires all six map files plus id-map-manifest.json matching the clientRevision, the items, npcs, and objects categories, generatedAt, and source. When the cache remains 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 filter by ID. ItemQuery.withMappedName(...) includes RuneLite's bundled item variation groups for the current rev240 release. A mapped base name such as Ancient sceptre matches its released locked/broken/mangled variants. Existing withName(...) methods retain exact visible-name filters.

Refresh handling relies on imports. IdMapRegistry completely replaces any external Python-based wiki scraping. The RuneLite plugin skips external scripts and avoids wiki scraping during startup. After generating fresh JSON files, call IdMapRegistry.importGenerated(...) to validate and copy them into the revision cache with a manifest.