DotA 2 How to create a custom unit


Forum Administrator
Staff member
So you've read some tutorials on how to get started, the terrain editor was pretty straight-forward, everything is looking great... and yet, you are still left wondering, how do I create a custom unit?

Unfortunately, the Dota 2 Editor does not feature a user-friendly User Interface in order for us to modify the units. Also, the number of unit models available for editing is quite low, due to the nature of Dota 2 and its restricted number of units compared to Warcraft 3 and Starcraft 2, and their numerous, unique campaign units.

That being said, you can still create custom units, but it's done slightly outside of the editor.

If you followed this simple tutorial, which everyone should have by now, you should be in possession of your map, and its addon. With it, are several folders. You will need to find your addon's root directory. First locate your steam directory, and then navigate to:

Steam/SteamApps/common/dota 2 beta/dota_ugc/game/dota_addons/YOUR_ADDON_NAME/

This is your root directory, where YOUR_ADDON_NAME is, well, the name of your addon. Let's name our addon Zergling Madness, for fun. So, under Zergling_madness there should be a list of folders.


Within these folders are the custom content of your addon, or map. Units are located under scripts/npc/npc_units_custom.txt

Opening this file into your favorite text editor will bring up the dreaded Dota 2 Unit Editor! This is what it should look like:


If you're wondering about the color, follow this link under "What you need".

Editing units is thus a data-driven process, where you list properties for the unit, and define its characteristics. Most of the challenge comes through finding the names of the characteristics you want, and to find proper paths for the various models/particles you want the unit to have.

Custom Unit Example

We're going to create a custom unit named "Guardian of Fire". Let's say we want it to have a fire feel and a small fire ability. Our guardian will be stationed next to an objective and should protect it, so it will be neutral unit.

Here is the code you should paste inside your npc_units_custom.txt file:

    // Creature: Guardian of Fire
        // General
        "Model"                        "models/items/warlock/golem/doom_of_ithogoaki/doom_of_ithogoaki.vmdl"    // Model.
        "BaseClass"                    "npc_dota_creature"
        "SoundSet"                    "Creep_Bad_Range"
        "GameSoundsFile"            "soundevents/game_sounds_creeps.vsndevts"
        "Level"                        "4"
        "ModelScale"                 "1.0"
        "CanBeDominated"            "0"

        // Abilities
        "Ability1"                    "forged_spirit_melting_strike"            // Ability 1
        "Ability2"                    ""            // Ability 2
        "Ability3"                    ""            // Ability 3
        "Ability4"                    ""            // Ability 4

        // Armor
        "ArmorPhysical"                "5"            // Physical protection.
        "MagicalResistance"            "25"        // Percentage

        // Attack
        "AttackCapabilities"        "DOTA_UNIT_CAP_RANGED_ATTACK"
        "AttackDamageMin"            "55"        // Damage range min.
        "AttackDamageMax"            "100"        // Damage range max.
        "AttackRate"                "1.5"        // Speed of attack.
        "AttackAnimationPoint"        "0.4"        // Normalized time in animation cycle to attack.
        "AttackAcquisitionRange"    "800"        // Range within a target can be acquired.
        "AttackRange"                "600"        // Range within a target can be attacked.
        "ProjectileModel"            "particles/units/heroes/hero_invoker/invoker_forged_spirit_projectile.vpcf" // Particle system model for projectile.
        "ProjectileSpeed"            "1100"        // Speed of projectile.       

        // Bounds
        "BoundsHullName"            "DOTA_HULL_SIZE_HERO"            // Hull type used for navigation/locomotion.
        "RingRadius"                "80"
        "HealthBarOffset"            "200"

        // Bounty
        "BountyXP"                    "500"        // Experience earn.
        "BountyGoldMin"                "150"        // Gold earned min.
        "BountyGoldMax"                "300"        // Gold earned max.       

        // Status
        "StatusHealth"                "2500"        // Base health.
        "StatusHealthRegen"            "3"        // Health regeneration rate.
        "StatusMana"                "200"            // Base mana.
        "StatusManaRegen"            "30.0"        // Mana regeneration rate.     
        // Vision
        "VisionDaytimeRange"        "1800"        // Range of vision during day light.
        "VisionNighttimeRange"        "800"        // Range of vision at night time.

        // Team
        "TeamName"                    "DOTA_TEAM_NEUTRALS"                        // Team name.
        "CombatClassAttack"            "DOTA_COMBAT_CLASS_ATTACK_BASIC"
        "CombatClassDefend"            "DOTA_COMBAT_CLASS_DEFEND_BASIC"
        "UnitRelationshipClass"        "DOTA_NPC_UNIT_RELATIONSHIP_TYPE_DEFAULT"

        // Inventory
        "HasInventory"                "0"

        // Movement
        "MovementCapabilities"        "DOTA_UNIT_CAP_MOVE_GROUND"
        "MovementSpeed"                "300"        // Speed.

        // Creature Data
            "CanRespawn"                "1"
            "DefaultState"                "Invade"
                    "Name"                "Invade"
                    "Aggression"        "100.0"
                    "Avoidance"            "0.0"
                    "Support"            "0.0"

Let's explain the important lines, shall we, and what we can do with them?

First of all, "npc_dota_creature_guardian_fire" is the in-editor name of your unit. It's the reference to it. Make it an obvious name.

"Model" is the model of the unit. Here, I chose a special warlock golem model. What's really important about this line is that you need to have the full path. One way to find it is to open the asset browser, which is always opened with the editor, and type in at the top "golem". You will see a list of models and particles. Click on the model ending with "doom_of_ithogoaki". It should show up, animated, to the right. In the bottom right corner of the screen, there should be a line named "Asset relative path". That's where you find your model's path. Select it, copy it, and paste it in your code. There you go!

"BaseClass" is what the unit actually is. npc_dota_hero is, well, a hero. Among other choices are npc_dota_tower, a building which can attack. npc_dota_building, a building which can't attack, and many more. Our choice here is npc_dota_creature, a unit which isn't a hero. There are lots of different kinds of base classes.

The next lines are pretty straightforward, until the abilities. A non-hero unit can have hero abilities, but they will always be maxed out in levels. So, a 4-levels ability will always be level 4 on a non-hero unit. You can also give units normal abilities, which is what we did here. Be careful to give the unit the correct name of the ability.

"AttackCapabilities" 3 choices here.
"AttackRate" can be as low as 0.01 for a very, very fast attack. The rest of the options are balance details, set whatever you want. Testing is the key here.

"ProjectileModel" this is like the model above. You find it in the asset browser, and it is very important to put the correct path of the particle, or else nothing will show up (which is annoying). See "Model" above for more information.

Hull size isn't very important, it's aesthetic, what matters is that the health bar can be offset compared to the unit's model size. Generally useless.

Give it the bounty you want, health you want, these are balance matters.

"TeamName" There are 4 teams in dota currently:
"CombatClass" refers to the attack and defense property of the unit. Heroes have the best attack and defense, while others have more reduction to their outgoing damage. Test it for whatever purpose you may have for your unit.

The deal at the end is the tricky part. The "States". Units will cast their spells, or not, depending on those states. This unit, for example, will always cast its most aggressive spell, due to its 100% aggression stance. You can toy with those settings and see what does what, but I'm not entirely sure still if those are based on % of HP or pure probabilities. Anyhow, higher "Support" value tends to cast defensive spells, while higher "Aggression" value means more offensive spells.
Last edited:
General chit-chat
Help Users
  • No one is chatting at the moment.
  • Ghan Ghan:
    I really do not want to move to California otherwise I might consider it.
  • The Helper The Helper:
    yeah California is not anywhere you really want to live
  • The Helper The Helper:
    That is why I did not take the job Blizzard offered me back in the day, there is no way I could have moved my family there on what they were offering, not even close and that was like 20 years ago
  • The Helper The Helper:
    yeah they wanted me on the tech support team when they did not get me they got one of the next MVPs in Dinobot
  • The Helper The Helper:
    Dinobot was one of the youngest of the MVPs tkron probably could have worked for Blizzard but he had a good job in Chicago doing business programming already
  • The Helper The Helper:
    Dinobot probably still works for Blizzard would love to reconnect with that guy
  • The Helper The Helper:
    I wonder what ever happened to Wargasm?
  • The Helper The Helper:
    This new version of Xenforo really is awesome
  • Ghan Ghan:
    Wargasm is still around. He works for the domain registrar where is kept.
  • Varine Varine:
    Is sqrage still around?
  • The Helper The Helper:
    I have not seen him on lately the forum says he was last on 2 years ago
  • The Helper The Helper:
    How are you doing Varine have not seen you around in a minute
  • thewrongvine thewrongvine:
    lol I live in CA
  • thewrongvine thewrongvine:
    I've got some friends in animation department who have been applying for Blizzard, doing interviews and such. They said the workplace seems nice, though now it'd be all remote work I suppose
  • The Helper The Helper:
    good for them I live close to Austin and am trying to get my kids interested in getting into Games but not having much luck. I would never let them move to Cali.
  • The Helper The Helper:
    unless it was huge money
  • The Helper The Helper:
    and even then with the taxes I really could never let them move there
  • thewrongvine thewrongvine:
    Haha fair enough, I have no interest in CA at all as a living place either. Really only here just for the work in LA, but hopefully once I get settled enough in my work, I can move out
  • Ghan Ghan:
  • jonas jonas:
    " a traditionally-sized California family of one person ":cool:

    Members online

    No members online now.


    Hive Workshop