Build an item mod from the game files

Everything an item needs is already in your game: the arcana's model, its particles, its icons. A mod puts them under the names the plain hero uses. These are the commands we build our own mods with, in the order we run them, with the output they print.

Checked 3 November 2026

What you need

Dota 2, Node.js 24 and git. The scripts live in our repository; clone it and let modkit check tell you which optional tools the mod you have in mind needs. Recolors and items rebuilt from the game need nothing else.

git clone https://github.com/dota2modmanager/dota2-mod-manager
cd dota2-mod-manager
npm ci
npm run modkit -- check

None of the commands write into the folders the game mounts. They build a VPK in a work folder, and you install it by dragging it into the app's My mods, where it switches off in one click like any other mod.

Recolor a hero's effects

modkit recolor takes a hero and a colour, finds every particle of that hero in the game's pak01 and rewrites its colours. pack turns the folder into a VPK, and the doctor reads the result against the game before anything starts.

$ npm run modkit -- recolor terrorblade 40,120,255 --out work/mod
terrorblade: 97 of 155 particle(s) recoloured (166 colours) into work/mod
$ npm run modkit -- pack work/mod --out tb_blue.vpk
97 file(s) from work/mod into tb_blue.vpk (0.4 MB); 0 left out as the game's own
$ npm run doctor -- tb_blue.vpk
nothing found

Colours painted into textures (projected rings, colour warps) stay as they are. The script tells you so, and the skill's recolor reference explains how to edit those by hand.

Bring back an item you do not own

Start with the plan. item-plan reads the item's visuals from the item table and prints one line per change it makes, with how a mod can give it. Here is Terrorblade's arcana, cut to one line of each kind:

$ npm run item-plan -- 5957
5957 Fractal Horns of Inner Abysm: slot hero_base, for npc_dota_hero_terrorblade
  built    the hero's own model
  built    activity modifier "abysm"
  built    a picture (ability_icon)
  by hand  a sound
  by hand  a particle the item creates
  by hand  a model swap
  cannot   custom_kill_effect
  cannot   chatwheel x9

built

The app's builder already does this: the swapped hero model, the pictures, an activity modifier taken off the animations.

by hand

A mod can do it, and the line says how: a particle the item creates hangs off one the hero always has, a model goes under the stock path.

cannot

Game logic that comes with the item itself: the kill effect, chat wheel lines, voice responses. No file carries it.

Name the stock path, not the paid one. A match loads the models the server's item table names, so a mod that puts the arcana's model under its own path looks right until a reconnect and then shows the ERROR model. The builder puts every file under the plain hero's path for that reason.

Swap an icon or a portrait

modkit pictures terrorblade --out work/pics writes the hero's ability icons, portrait and minimap icon as PNG files. Edit them in any image editor, then --from work/pics compiles them back under the same names. The minimap icon also sits in a sprite sheet, and the script fills both.

Change a sound

modkit sounds terrorblade lists the hero's sound events. With --addon my_sounds --out work/mod, --layer Hero_Terrorblade.Sunder=my.wav plays your file on top of the stock one and --replace plays it instead. Sounds go through Valve's compiler, so this one needs the Dota 2 Workshop Tools (Steam, Dota 2, Properties, DLC) and Windows.

Check it before the game, then in the game

The doctor, in secondsnpm run doctor -- my_mod.vpk reads the mod against pak01: animations that still need an item's modifier, sequence numbers that differ from the game's, a child particle on the wrong attachment. "nothing found" is the answer you want.
The bench, in three minutesnpm run dota:bench -- --vpk my_mod.vpk --short starts Dota in hero demo with the mod in a free slot, films the hero close, attacking and walking, and writes verdict.json. Windows, Steam running, Dota closed.
Compare with a mod that worksBench the plain hero and a catalog mod of the same item. When yours differs, swap one resource block at a time between the two: the block that carries the bug shows up in two or three runs.

Traps that cost us a day each

The game picks animations by the clips, not the sequences. Fixing only the sequences changed nothing for a day of builds. The doctor reads both now.
A child particle past its parent's control points lands on the first one: a glow meant for the chest sat on the right eye.
A recompiled model renumbers its sequences. Online the server sends sequence numbers, so one missing clip shifts every animation after it. modkit clips puts Valve's names and numbers back.
One picture a second hides the attack. A fidget at rest looked like a swing; the bench takes 16 pictures 80 ms apart for that reason.

Rather tell an assistant?

The same scripts are a skill an AI assistant follows, with everything past this page: new models in Blender, animations, voice lines. Make Dota 2 mods with AI sets it up in one line. The full notes this page comes from are docs/item-mods.md.