SpellQuery

This documentation is a part of the TCI reference.

Spell data searches can now be done by using the "spell_query" option in simc. This does not do any simulation, but rather reads the expression given as a value for the option, and runs it against the spell (or talent) data for live or PTR (by specifying ptr=1 before the spell_query option). The result is a textual output of all spells (or talents) matching the given query expression. You can also append "@level" at the end of your spell query, which will execute the query using an actor level that was specified at level. In addition, from version 623-1 forward you can also specify the item level through the level option. Spell query will interpret any level higher than the global player maximum level of the simulator to indicate item level scaling for the spell.

To accomplish this, a new expression data type has been defined (TOK_SPELL_LIST), which contains a list of spell or talent identifiers. To this end, spell_query works on an expression level by first taking a full list of spell ids, and performing filtering on that list to limit it. Thus, all spell_query related operations are binary, and the left side operator must always be a TOK_SPELL_LIST operand. Binary operators may be chained normally, as the binary operator inherits both data source and the result type from the left side operator.

The expressions for spell query follow the normal simc expression input, however the spell query must be told where to get the initial list of identifiers. The following identifier data sources have been defined:

• spell - The master spell list, containing all spell data in simc
• talent - The master talent list, containing all talent data (NOTE: not spells)
• talent_spell - All spell ids used by the master talent list for talent ranks
• class_spell - All spells belonging to a class and "clickable", this includes pets
• race_spell - All racial spells
• mastery - All class masteries
• spec_spell - All specialization spells, passive or active
• glyph - All glyph spells
• set_bonus - All set bonus spells
• effect - All effects
• perk_spell - All perk spells (NOTE: WoD only)
• artifact - All artifact spells (Added in version 703-1, Removed in 8.0)
• azerite - All azerite power spells (Added in version 8.0)
• covenant_spell - All Covenant abilities (Added in version 9.0.1, release 1)
• soulbind_spell - All Soulbind abilities (Added in version 9.0.1, release 1)
• conduit_spell - All Soulbind conduit abilities (Added in version 9.0.1, release 1)
• runeforge_spell - All runeforge legendary spells (Added in version 9.0.2, release 1)

A data source can be filtered by giving it a data field name, by suffixing the data source name with a period and the filtering data field name. Currently the system does not support deeper "paths" than 2, i.e. "spell.name" is the deepest it will go. The expression is then given an operand, e.g. == !=, <, > and so on, after which a string, numeric type or another spell identifier list (if the operands &, | or - are used). The following data field names are currently supported, listing the name, data_source_types (spell covers all but "talent" data source), operand_type and a brief description:

• name, spell/talent, STRING
• id, spell/talent, NUMBER
• flags, spell/talent, NUMBER (not used for anything currently)
• speed, spell, NUMBER (projectile speed)
• school, spell, STRING (spell school name)
• class, spell/talent, STRING (class name)
• pet_class, talent, STRING (pet talent tree name)
• scaling, spell, NUMBER (spell scaling type, -1 for "generic scaling", 0 for no scaling, otherwise class number)
• extra_coeff, spell, NUMBER (spell-wide coefficient, usually used for spells scaling with both SP and AP)
• level, spell, NUMBER (spell learned level)
• max_level, spell, NUMBER (spell "maximum" level in a scaling sense)
• min_range, spell, NUMBER (minimum range in yards)
• max_range, spell, NUMBER (maximum range in yards)
• cooldown, spell, NUMBER (spell cooldown, in milliseconds)
• gcd, spell, NUMBER (spell gcd duration, in milliseconds)
• category_cooldown, spell, NUMBER (shared cooldown duration, in milliseconds, New in version 710-03)
• charges, spell, NUMBER (number of charges for the spell)
• charge_cooldown, spell, NUMBER (charge cooldown in milliseconds)
• category, spell, NUMBER (spell cooldown category)
• duration, spell, NUMBER (spell duration in milliseconds)
• rune, spell, STRING, (b = blood, f = frost, u = unholy, will match minimum rune requirement, Removed in version 701-1)
• power_gain, spell, NUMBER (amount of runic power gained, Removed in version 701-1)
• max_stack, spell, NUMBER (maximum stack of spell)
• proc_chance, spell, NUMBER (spell proc chance in percent (0..100))
• icd, spell, NUMBER (internal cooldown of a spell in milliseconds)
• initial_stack, spell, NUMBER (initial amount of stacks)
• cast_min, spell, NUMBER (minimum cast time in milliseconds)
• cast_max, spell, NUMBER (maximum cast time in milliseconds)
• cast_div, spell, NUMBER (scaling divisor for cast time, always 20)
• m_scaling, spell, NUMBER (unknown scaling multiplier)
• attribute, spell, NUMBER (spell attribute bit index, 0 indexed)
• flag, spell, NUMBER (spell family flag bit index, 0 indexed, Added in version 801-1)
• label, spell, NUMBER (spell label number, Added in version 905-1 )
• scaling_level, spell, NUMBER (level threshold for m_scaling)
• desc, spell, STRING (spell description)
• tooltip, spell, STRING (spell tooltip)
• stance_mask, spell, NUMBER (stance mask of the spell, Added in version 701-1)
• tab, talent, NUMBER (talent tab number, 0..2)
• dependence, talent, NUMBER (talent id this talent depends on)
• depend_rank, talent, NUMBER (talent rank of talent id this talent depends on)
• col, talent, NUMBER (talent column 0..3)
• row, talent, NUMBER (talent "tier" 0..6)
• power_id, spell/azerite, NUMBER (azerite armor trait id, Added in version 8.0)
• essence_id, spell, NUMBER (heart of azeroth essence id, Added in version 8.2)
• covenant, spell, STRING (covenant name in lowercase, Added in version 9.0.1 release 1)
• conduit_id, spell, NUMBER (conduit identifier, Added in version 9.0.1 release 1)

For numeric data fields, the following numeric operators between a spell list and a numeric right-side operand are available: ==, !=, >, <, >=, <=. All string data fields can be filtered by a string right-side operand and the following operators:

• == : case insensitive string equality
• != : case insensitive string inequality
• ~ : case insensitive substring in data field
• !~ : case insensitive substring not in data field

IMPORTANT NOTE Due to how simc does command line parsing, all string based filtering needs to be input with whitespaces converted to underscores and without any special characters. The spell filtering will automatically "canonicalize" any strings it compares your textual input against, and all comparisons are done case insensitive. This means that for example "Shadow Word: Pain" becomes "Shadow_Word_Pain" when given as a right-side string operand to filter with IMPORTANT NOTE

Furthermore, for identifier list operands on the right side of the expression, the following operators are available:

• & : intersection (identifiers in both left and right side)
• | : union (identifiers from both left and right side, removing duplicates)
• • : subtraction (right side identifiers removed from left side list of identifiers)

Examples:

a) All activatable class spells of shaman

$ simc spell_query=class_spell.class=shaman

b) All cataclysm activatable spells

$ simc spell_query="class_spell.level>80"

c) All activatable class spells of shaman and priest

$ simc spell_query="class_spell.class=shaman|class_spell.class=priest"

c) All mastery spells

$ simc spell_query=mastery

d) All class (and pet) spells costing resources

$ simc spell_query="class_spell.cost>0"

e) All spells that contain "shadow damage" in their description or tooltip

$ simc spell_query="spell.descshadow_damage|spell.tooltipshadow_damage"

f) All death knight spells that use at minimum a blood and an unholy rune

$ simc spell_query="spell.class=death_knight&spell.rune=bu"

g) All spells using the constant scaling

$ simc spell_query=spell.scaling=-1

h) All spells that are fire or frost based (including derivations)

$ simc spell_query="spell.school=fire|spell.school=frost"

Note that depending on your shell interpreter, you may need to escape some special characters used in the spell queries.

..........................................................................................

A new data source called "effect" allows for filtering effects based on data field, currently all data fields accept a numeric operand to compare against. Additionally, spells can now be filtered by using "effect" as a field name, followed by one of the actual data field names:

• id - Effect id
• flags - Effect flags (not used for anything)
• spell_id - Spell the effect belongs to
• index - Effect index on the spell (effect indexes in data are 0..2)
• type - Effect type (see data_enums.hh for effect_type_t)
• sub_type - Effect (aura) sub type (see data_enums.hh for effect_subtype_t)
• m_coefficient - Effect average scaling multiplier (class-based scaling)
• m_delta - Effect delta scaling multiplier (class-based scaling)
• m_bonus - Effect bonus scaling multiplier (class-based scaling)
• coefficient - Effect coefficient
• amplitude - Effect amplitude (base tick time)
• radius - Effect minimum radius
• max_radius - Effect maximum radius
• base_value - Effect base value
• misc_value - Effect miscellaneous value
• misc_value2 - Effect secondary miscellaneous value
• trigger_spell - A spell (identifier) that is triggered by this effect
• m_chain - Effect chain multiplier
• p_combo_points - Effect combo point based multiplier (usage unknown at the moment)
• p_level - Effect level based multiplier
• damage_range - Effect damage range modifier (usage unknown at the moment)
• chain_target - Number of targets the effect chains to
• target_1 - First targeting type identifier (Added in version 703-1)
• target_2 - Second targeting type identifier (Added in version 703-1)

An example:

a) All shaman talents that additively increase the critical strike bonus of spells

$ ./simc spell_query="talent_spell.class=shaman&talent_spell.effect.sub_type=108&talent_spell.effect.misc_value=15"

..........................................................................................

When using the spell_query_xml_output_file option, the output will be stored into the chosen file and formated as XML.