aggixx edited this page Sep 29, 2015 · 3 revisions
Clone this wiki locally

This documentation is a part of the TCI reference.

Is there an error? Something missing? Funky grammar? Do not hesitate to leave a comment.

Declaring items


Equipment pieces are declared through the following syntax: <slot>=<item_name>[,<option1=value1>,<option2=value2>,...] The item name is used by replacing any white spaces with underscores. Note that some names have built-in support: for example, the Shadowmourne proc is hardcoded into Simulationcraft and you don't need to specify it. For example:

 # The following line is valid but it only adds a dummy helmet with no stats.

 # This will import a earthen helmet (id=60325), an epic plate helm, with a 359 ilevel.
 # Its stats are 2784 armor, 512 stamina, 281 strength, 228 haste and 168 critical strike.
 # It has a a destructive shadowspirit, along with a 20 crit + 20 str gem, and a 30 str gemming bonus (the bonus is only mentioned when active).
 # Finally, it has a 60 strength + 35 mastery enchant.

 # We can also provide the item's ID, this will force the application to query the stats from the armory. We only have to specify how we customized it: gems, enchant, reforging.

Slots keywords

Acceptable slots are:

  • meta_gem
  • head
  • neck
  • shoulder, shoulders
  • back
  • shirt
  • chest
  • waist
  • wrist, wrists
  • hand, hands
  • finger1, ring1, finger2, ring2
  • trinket1, trinket2
  • main_hand, off_hand
  • ranged
  • tabard


Importing stats through ID

  • id (default: 0) can be used to specify the item's id and force the application to query the stats, the quality and armory type from the items importation sources (see the Item Data Importation section). The returned parameters will replace those you may have specified.
 # Let's import our helm's stats
  • source (default: "") can be used to override the item_db_source global setting for this item (see the Item Data Importation section). It uses the same syntax.
 # Let's import our helm's stats from mmo-champion, or local if mmo-champion doesn't work.

Basic properties

  • quality can be used to specify the item's quality. All values are accepted but, for random enchants, it has to be one of "rare", "epic" or "uncommon" i order to figure out the stats values.
  • ilevel is the item level. It is especially important for random enchants, in order to figure out the stats values.
  • type is the armor type, it should be one of "cloth", "leather", "mail", "plate". It is used to check whether the character is eligible for the armor specialization bonus (+5% strength for a warrior only wearing plate for example).
  • lfr, when set to 1, flags the item as a looking for raid item difficulty. It is used in conjunction with special effects to determine the power of the special effect on that item, typically on trinkets.
  • heroic, when set to 1, flags the item as heroic. It is used in conjunction with addon when the application has to decide between the heroic or normal proc.
  • warforged, when set to 1, flags the item as an elite item, e.g., thunderforged or warforged items. It is used in conjunction with special effects to determine the power of the special effect on that item, typically on trinkets.
  • mythic, when set to 1, flags the item as a mythic item. It is used in conjunction with special effects to determine the power of the special effect on that item, typically on trinkets.
  • upgrade, when set to 1 or 2, applies a level of upgrade on the piece of gear (value times 4 for epic/legendary, value times 8 for rare). Simc offers two different ways to upgrade items:
    1. If an id option is given, stats are not given, and the item can be found from the local item database (source option is empty, or contains local, and the item is found), the simulator will use a precise upgrade formula.
    2. If no id option is provided, or the item stats are given through the stats option, or the item is not found in the local database, or the local database is not used, the simulator uses an approximate formula for item upgrades, which may result in stats that are a couple of points off. This method requires that quality, and ilevel parameters are set on the item, either through the id option based item data parsing, or by the specific options. > Also note that you may use the upgrade option to upgrade an item more than two times. In this case, the simulator has a global ilevel cap of 1000.


  • stats is the sequence describing the stats. The syntax is : <value1><stat1>[_<value2><stat2>_...]. For example: "500sta_250str". Note that manually specified stats will override any stats queried through the id option.
  • weapon is used to specify the weapons' damage ranges. It is a sequence of options. Syntax is: weapon=<type>[_<option1>=<value1>...]. Type can be one of: dagger, fist, beast, beast2h, sword, sword2h, mace, mace2h, axe, axe2h, staff, polearm, bow, gun, crossbow, thrown. Additional types for wands are: arcane, bleed, chaos, fire, frost, frostfire, holy, nature, physical, shadow, spellstorm, shadowfrost, shadowflame, drain. Options are:
    1. speed (mandatory) is the weapon's speed, in seconds.
    2. min and max are the damages range. When not set, they will be inferred from dps and speed (constant damages weapon) or, in last resort, from dmg or damage.
    3. dps is the weapon's dps. It is not used when min and max are set.
    4. dmg (or damage) is the weapon's constant damages. It is not used when min and max, or dps, are set.
 # Here is a 4.0s and 500dps weapon definition with min and max.

 # Same axe but it will do constant damages of 2000 points.

 # Alernative syntax for the constant damages weapon


  • gems is the sequence of bonuses brought by the gems and gemming bonuses. The syntax is [<metaprefix>_<metasuffix>][_<value1><stat1>...]. For example: "destructive_shadowspirit_40str" for a destructive shadowspirit diamong (meta) and a 40 strength gem. Use this chain to include the gemming bonus when it is activated.
 # Here is the definition for a earthen helmet.
 # Meta socket: destructive shadowspirit diamond
 # Yellow socket: 20crit + 20str orange gem
 # Gemming bonus: 30str


  • enchant can be either a stats sequence (using the same pattern than stats or gems) or one of the recognized keywords, such as "landslide", "lightweave_embroidery", "power_torrent", etc.
 # We can use keywords

 # Or specify a custom 500 strength enchant


  • use allows you to specify on-use effects. The syntax is: <value1><param1>[_<value2><param2>...]. The parameters can be:
    • Any school abbreviation, for damages effects. For example: "451physical".
    • Any stat abbreviation, for stats gains. For example: "1500str".
    • cd or cooldown for a cooldown. For example: "45cd" for a 45s cooldown.
    • dur or duration for a duration. For example: "15dur" for a 15s duration.
    • stack or stacks for a maximum stack for a buff
    • aoe to specify the number of enemies to hit, -1 for all enemies
    • driver to specify the on-use spell for the item. If a spell is given, the system attempts to automatically detect what kind of buff (or damage spell) to make.
    • tick can be used to specify the period of the ticks for the effect
    • reverse can be used to specify whether the triggered buff counts from stack to 0
 # Unsolvable riddle: 1605 str on-use effect every 2mins, 20s duration.

 # A custom trinket ticking 100 Agility every second, lasting for 10 seconds
  • equip allows you to specify procs. The syntax is: <trigger>_<value1><param1>[_<value2><param2>...]. The parameters are the same as with use and also:
    • procby is used to define what types of abilities proc the effect. Each different type is given after procby using a forward slash and a specifier. Allowed specifiers are
      • aoespell, Area of effect harmful spells
      • aoeheal, Area of effect healing spells
      • spell, Harmful spells and harmful periodic effects
      • directspell, Harmful spells
      • heal, Healing spells and healing periodic effects
      • directheal, Healing spells
      • attack, Melee and ranged autoattacks and special abilities
      • wattack, Melee and ranged autoattacks
      • sattack, Melee and ranged special abilities
      • melee, Melee special abilities
      • wmelee, Melee autoattacks
      • ranged, Ranged special abilities
      • wranged, Ranged autoattacks
    • procon is used to define what types of results proc the effect. Each different type is given after procon using a forward slash and a specifier. Allowed specifiers are
      • impact, any positive result (hit, glance, crit)
      • hit, any positive result (hit, glance, crit, implies a non-zero amount)
      • crit, any critical strike result (implies a non-zero amount)
      • glance, any glancing result (implies a non-zero amount)
      • dodge, any dodge result
      • parry, any parry result
      • miss, any miss result
      • cast, casting finishes
      • multistrike, any multistrike result (implies a non-zero amount)
      • ms_hit, any multistrike hit result (implies a non-zero amount)
      • ms_crit, any multistrike critical strike result (implies a non-zero amount)
    • % can be used to specify a proc chance as a percentage. For example: "25%" for a 25% proc chance.
    • ppm can be used to specify a proc chance per minute. For example: "2ppm" for a proc chance leading to 2 procs per minute.
    • rppm can be used to specify a real procs per minute value. For example: "2rppm" for a proc chance leading to 2 real procs per minute.
      • A suffix of spellhaste, attackhaste, or crit can be appended to rppm, causing the value to be scaled with the corresponding stat
    • driver can be used to specify the spell that is used to "proc" the effect. If given, the system attempts to automatically detect what kind of effect to make.
    • trigger can be used to specify the spell that is triggered by the proc. If given, the system attempts to automatically detect what kind of effect to make.
    • refresh can be used to allow the refreshing of the procced buff. This is the default behavior.
    • norefresh can be used to disallow the refreshing of the procced buff. This is the default behavior for buffs that gain/lose stacks by ticking.
 # "Darkmoon card: hurricane": 5k nature damage, about 10% chance to proc on every attack

 # Custom trinket that procs on attack crits
  • addon is a shortcut for adding proc effects with a built-in support. For example, addon=pyrorocket is equivalent to specifying use=1165Fire_45cd. For a list of supported procs, you can look at the sc_unique_gear.cpp file.
 # Gloves with pyro-rockets (id=54998) on it.
  • initial_cd allows the user to specify the minimum amount of time that must elapse before any procs the item provides occur. The proc effect must have a cooldown, and the initial cooldown is limited to a maximum of the normal duration of the item's cooldown. This allows the user to emulate equipping an item at certain time prior to the beginning of combat.
 # This emulates equipping the trinket (which has an 11s ICD) at 7.5s prior to the pull.

Random stats

  • suffix (default: "") can be used to specify a set of random stats. The exact stats will be inferred from the specified suffix, the item level and its quality. Acceptable values can be found in "" or "" for PTR simulations, search for "rand_suffix_data". The suffix is the numeric identifier for the random suffix found in the data structure.
 # Earthen Helmet of the Landslide

Set bonuses

Set bonuses have to be manually added, even if you have enough set pieces equipped. This is done with keywords such as tier11_2pc_caster. The generic syntax is tier<number>_[2pc/4pc]_[melee/caster/tank/heal]. The correct bonus is chosen according to your class and the suffix you used.

Note that enabling the 4pc bonus does not automatically enable the 2pc bonus, so you may want to toggle both of them. Reciprocally, you can activate those bonuses while your gear actually does not satisfy the requirements.

 # Enable the tier 11 bonuses for a balance druid.

(Since Simulationcraft 6.0.2) From Tier 17 onwards, you must use the new set_bonus option to override set bonuses, and omit the role. You can also specify earlier set bonuses with the set_bonus option, by simply appending set_bonus= to the "old option style".

 # Enable the tier17 bonuses

Item Data Importation

When automatically importing items data (see the importing stats through ID section), the application will sequentially query multiple sources until one of them successfully returns the stats. (For more information on how item import interacts with caching, see Cache Control.)

  • item_db_source (scope: global; default: "wowhead,mmoc,bcpapi,ptrhead,local") is a sequence of sources, separated by ":", "/" or "|". Simulationcraft will try to retrieve items from each source in turn. Acceptable values are:
    1. "wowhead" is Wowhead
    2. "bcpapi" is
    3. "ptrhead" is Wowhead - ptr
    4. "local" is Simulationcraft's local, offline database. It is built directly from the game's files and contains most ilevel 277-400 items.
 # Use the local items database as the default source, with Wowhead as a backup.

Additional commands

#Used to scale all gear on character to ilevel 600 when simulating

Appendix: stats abbreviations

Stats abbreviations are (non-exhaustive list):

  • Resources: health, mana, energy, rage, runic, focus
  • Primary: str, agi, sta, int, spi
  • Secondary: mastery, crit, haste, vers, mult, sp, ap, mp5
  • Defensive: armor, bonus_armor
  • Weapon damages: wdps, wspeed, wohdmg, wohspeed