Cosmetic lua library

edited August 2015 in Tools

I wrote a library for myself to use in my projects since I think it's quite useful so I would share it.


Github Link:

CosmeticLib will help swapping cosmetic become easier including

  1. Equipping item based on its item_id to specified slot name for unit
  2. Equipping item based on its item_id to replace currently equipped item based on its item_id for unit
  3. Equipping specific set to the unit
  4. Equipping default cosmetic items to the unit
  5. Remove cosmetic from specific slot of the unit
  6. Remove all cosmetics from the unit
  7. Getting the list of slots available for the unit based on hero name
  8. Getting the list of items available for the unit based on hero name
  9. Getting the list of set items available for the unit based on hero name
  10. Getting item id based on item name.
  11. Getting item id based on model name.

Incoming feature:

  1. Auto-swapping ward
  2. Auto-swapping courier
  3. Particle placing, due to hidden placing by valve, this may have to wait til later patch


  • Removing cosmetic will result in deattach all existing particles. It will remain there in the game forever unless attachable cosmetic is attached to the slot again. The best way to avoid this is to have a place to dump all particles in the map if you plan to override any equipped cosmetic with the ones from different slot or from other heroes.
  • In order for cosmetic for specified hero to show up, you need to precache model_folder accordingly in the precache block in addon_game_mode.lua such as
PrecacheResource( "model_folder", "models/heroes/drow", context )
PrecacheResource( "model_folder", "models/items/drow", context )

Test console commands are also available by enable cheat in the lobby and set sv_cheats 1 in console. The following is the link to the library:

The library contains 2 files

  1. CosmeticLib.lua, this file contains the lua library
  2. CosmeticLib.txt, this file is a README where you can find all available functions

To use in your addon, simple write the following line to the top of your addon_game_mode.lua

require( 'CosmeticLib' )

If there is anything I can do to improve the existing library or include any other feature, feel free to leave a comment or send me a message.


  • Posts: 1,670

    This Is Awesome! :kreygasm:

    World of Dota here we go

    The concept of Modding Community doesn't go well together with Competitive Business
    My Project Page || My GitHub Profile ||

  • DunDun
    Posts: 123

    8/8 :gaben:

  • edited March 2015 Posts: 858

    Ooh, nice... couple comments though

    I can tell you're not a native LUA programmer if unit ~= nil do -> if unit do

    `if CosmeticLib._Couriers == nil then
        CosmeticLib._Couriers = {}

    -> CosmeticLib._Couriers = CosmeticLib._Couriers or {}


    Are you attempting to use the underscores as a method of private functions? If so, you probably want to use the local keyword


    kv checker -
    panorama video series -

    My pet project This Cursed World/Crestfallen (name pending)

  • edited March 2015 Posts: 1,670

    ( ^ You just need a single ~~~ before and after the code block :blush: )

    As for the _underscored stuff, Valve's holdout_example has a comment on the top of the page which recommends:

    "Underscore prefix such as "_function()" denotes a local function and is used to improve readability"

    but not sure if that's what they are being used here though

    The concept of Modding Community doesn't go well together with Competitive Business
    My Project Page || My GitHub Profile ||

  • Posts: 96

    Thanks for the feedback, I updated the most of the variables from checking nil in other language's style into LUA style. As for functions, I might fix when I have time to study in-depth about the scope of private/local functions, their visibility and their accessibility in LUA before I attempt to make any change to it.

  • Posts: 184

    Treat everyday as if you are a student, not a master. The student learns, grows and sees beauty. The master becomes bitter, resentful, and stagnates.

  • Posts: 1,670

    Just wanted to highlight this is the deal breaker for the whole SetModel on cosmetics to work:

    SendToServerConsole( "dota_combine_models 0" )

    The concept of Modding Community doesn't go well together with Competitive Business
    My Project Page || My GitHub Profile ||

  • Posts: 96

    On side note on what Noya mentioned, that will disable model combiner on heroes allowing wearable to be attached, removed, etc. By default, most wearables have this enable by default, except very few some like Abaddon's weapon, etc. Make sure to send this command to both server and client consoles to allow replacement.

  • Posts: 45

    :gaben: 11/10

  • Posts: 203

    Dude this library is awesome, good job.

    Is it up to date with reborn ?

  • Posts: 8

    10/10 - Great Library.

    Feature Request: Attaching custom models as cosmetics.

  • Posts: 21

    Are arcanas not supported or something cause I tried using the cm arcana and it doesn't have any particles / animations but it has the cape.

  • very nice!!! thanks so much!