Retro NPC Swapper

Swaps modern NPC models and animations back to their 2004/2005 look, using the retro assets that are in the OSRS cache where they survived, and a bundled 2005 set where they did not.

What gets swapped

Each category can be toggled individually under NPC Toggles in the plugin config:

• Chickens
• Goblins
• Skeletons
• Zombies
• Giants
• Ghosts
• Hellhounds
• Giant Rats
• Small Scorpions
• Spiders
• Bears

Also in NPC Toggles, gated behind Use Converted 2005 Assets:

• Giants — Fire, Ice and Moss Giants
• Dragons — chromatic/metallic, KBD
• Demons
• Imps
• Cyclopes
• Guards
• Cows
• Scorpions
• Elves
• Kalphites — KQ, Guardians, Soldiers, Workers, Larvae
• Knights of the Round Table — King Arthur and his knights, Merlin, renegade knights, etc
• Varrock NPCs — Aris, Romeo, Sir Prysin, King Roald, muggers and tramps
• Chatheads — Swaps chatheads for NPCs with dialogue. Follows each NPC's own toggle.

Under Scenery:

• Mystical wall charts
• Wells
• Wardrobes
• Trees — oak and magic trees
• Picnic benches
• Dairy cows
• Fishing spots - Excluding sailing-specific spots

Requirements

The GPU or 117 HD plugin must be enabled. Models are substituted via their specific renderers, and the stock CPU renderer and 117 HD's optional Legacy renderer are not supported. The plugin will automatically detect this and stand down until a supported renderer holds the renderer slot.

Why these NPCs require the 2005 asset pack

These need converted 2005 assets because swapping IDs is not enough for them, and they fail in two different ways. Some lost the mesh outright: the adult dragon and demon meshes were removed from the OSRS cache and their IDs reused for unrelated geometry such as statues and skulls. Others kept the mesh but lost the rig: the imp and baby dragon meshes survived, but the animations behind their surviving sequence IDs were re-authored for the modern skeletons. Either way the geometry, the animation, or both have to come from the 2005 data instead of the live cache.

Scenery stand-ins draw over the live object, which stays in the scene: its clickbox and menu options are the live ones. Scenery is lit with its 2005 values, so it can read a shade darker than the live objects around it. The Varrock retextures are not supported.

How it works

• The plugin wraps the renderer's draw callbacks and hands it a prebuilt retro model whenever an eligible NPC is drawn. Retro pose and combat animations are applied through the standard Actor animation setters, and the client animates the model as usual.
• The converted-2005-asset categories take a second path. Their geometry is not something the client decoded, so the client cannot animate it — applyTransformations only accepts the client's own model type. The plugin therefore skins and lights those models itself, in Java, reading the frame index the client is already driving so the two stay in step.
• Clickboxes are untouched. The client resolves clickboxes from the original model before the draw callback runs, so interaction hitboxes stay exactly vanilla.
• Interact Highlight plugin compatibility: the Compatibility section provides a Fix Interact Highlight outlines checkbox to resolve inconsistent outline draws on retro models. Because the swap happens at draw time, anything outlining an NPC or restored scenery through the API outlines the modern mesh, which no longer matches what is on screen. With the Interact Highlight plugin enabled, and the compatibility checkbox enabled, this plugin turns off that plugin's own NPC and object hover and interact outlines and draws them around the retro model instead, using its colors and border settings; its ground item and player highlights are untouched, and all four settings are restored when this plugin stops. Note: This means the highlight will trace the rendered model while the clickbox still traces the vanilla model, so they can disagree at the edges. Turning any of those settings back on yourself in the Interact Highlight config while retro compatibility is enabled hands the outlines straight back to the Interact Highlight plugin and unticks the compatibility checkbox in this plugin.
• Nothing is downloaded. For the categories in the first list, the plugin ships only a table of numeric model and animation IDs, and every asset it displays already comes from the live game cache.
• The injected categories ship their assets. Dragons, demons, imps, guards, elves, the Knights of the Round Table, the Varrock NPCs, cows, scorpions, cyclops and the fire, ice and moss giant heads have no usable 2005 asset left in the live cache, so retro-assets.dat (~280 KB) is bundled in the jar and carries their meshes, rigs and animation clips, extracted from the February 2005 & November 2005 caches.
• Scenery is drawn by a stand-in. Static scenery is baked into the renderer's geometry when the scene loads and never passes through a per-frame draw, so the plugin asks the renderer to leave the live object out and places a stand-in object in its spot, which the draw callback dresses in the 2005 model.
• Safety settings (on by default) disable all swapping on PvP worlds and in the Wilderness.

There is currently no sanctioned RuneLite API for overriding NPC models, which is why the plugin utilizes the GPU or 117 HD renderer's draw callbacks.

Development tools & flags

• ./gradlew run starts a development client with the plugin loaded.
• ./gradlew generateNpcMappings regenerates npc-mappings.json from a local 2005 cache (original source: https://archive.openrs2.org/caches/runescape/2572) placed in retrocache/2005cache (the cache itself is not committed - if you want to generate your own you will need to download it yourself).
• ./gradlew compareRetroModels -Pmodels=<ids> -Pfindmoved decodes a model from both caches and compares vertex count, face count and palette, which settles whether an ID still holds its 2005 asset. Byte comparison cannot: Jagex re-encoded every model for the v2/v3 format markers. -Pfindmoved rescans the whole live model index to separate "the mesh moved to a new ID" from "the mesh is gone". The match is exact, so read a REPLACED verdict by its magnitude — the chicken drifted by one face and reports REPLACED while rendering perfectly. -Pfacediff adds the two measurements that settle what the palette alone cannot: what share of the 2005 vertex positions the live mesh still has — 97% for the preserved chicken and 100% for the skeleton, against 479 vertices becoming 68 for a genuinely reused ID — and, face by face, which 2005 color became which live one. That second number is what a correction recolor has to be built from: the cow body 3341 is 98% the same geometry with its whole hide repainted, and a distinct-palette diff cannot say which color became which. Faces are matched by position in space, because re-encoding reorders both the faces and the vertices.
• ./gradlew dumpRetroNpcDefinitions -Pnpc=<ids/name> -Pmax=200 prints 2005 NPC definitions (IDs or a name substring, e.g. goblin (-Pnpc=goblin)) with their opcode 40 recolor pairs. npc-mappings.json keeps only the lowest-id row per name, so it cannot answer a question about one particular NPC among several sharing a name, which is every family whose 2005 varieties were one mesh in several palettes.
• ./gradlew dumpNpcDefinitions -Pnpc=<id> prints live-cache NPC definitions (IDs or a name substring) — models, scales and pose animations, for comparing against the retro definition.
• ./gradlew dumpRetroObjectDefinitions -Pobj=<ids/name> prints 2005 object (scenery) definitions — models, size, scale, lighting and recolors. Many 2005 object IDs now belong to something else, so the live definition at the same ID is no guide to the 2005 one.
• ./gradlew dumpObjectDefinitions -Pobj=<ids/name> prints live-cache object definitions; -Pmodels=<ids> instead lists every live object drawing those models, which is how a scenery swap finds every copy of a replaced mesh.
• ./gradlew generateRetroAssets rebuilds retro-assets.dat from the local 2005 cache. It bundles the meshes the live cache no longer has, the rigs those meshes are skinned to, and the 2005 animation clips, resampled onto the live sequences' frame counts so the frame index the client drives still lines up. It needs the Feburary 2005 cache and the November 2005 cache (build 346), which the dairy cow and the Lletya elves come from: extract the cache/ folder of its zip to retrocache/nov2005cache, or point -PretroNovDir=<path> at it. Only the entries that ask for it read it — that build re-authored the human and cow rigs, so don't point -PretroDir at it to regenerate everything else. The Nov elves' meshes, clips and rigs are stored under keys of their own, apart from the February human kit that shares their ids.
• ./gradlew verifyRetroRigs measures reach — the share of a clip's transform ops that land on vertex groups the mesh actually has. A rig authored for a different mesh scores 47-68%, against 96-100% for a mesh animated by its own rig. This is what separates "the sequence ID survived" from "the frames behind it still fit". Read it by magnitude rather than as a threshold: a correct pairing of a partial kit with a full player animation scores lower by construction — the 2005 guard clips reach 65-80% and are right — so reach rules out a gross mismatch rather than proving a fit. RetroClipReachTest enforces a per-clip floor against the shipped bundle.

Other Model-Swapping Plugin Compatibility

The Custom Servants plugin runs alongside this plugin, together or on its own. Any NPC it has a custom model for is left to it entirely: this plugin swaps neither that NPC's model, its animations nor its chathead. Every other NPC is swapped as usual. The Fix Interact Highlight outlines option can be on in this plugin or Custom Servants (or both): only one draws Interact Highlight's NPC outlines at a time, each around whichever plugin's model is on screen.

If you'd like to report a bug or request a feature, please create an issue here