Automation
Is there an error? Something missing? Funky grammar? Do not hesitate to leave a comment.
As of Simulationcraft 6.0.1 release 1, there is an Automation tab under the Import section that helps automate creation of comparison sims. For example, this tool would help you quickly generate a simulation to compare various talent, glyph, gear, or rotation configurations. This simulation is essentially a raid sim containing one actor for each configuration specified, so you will automatically get charts ranking the actors for DPS, HPS, DTPS, and TMI.
This wiki entry explains how to use the tool and what each of the settings does.
The interface is shown in the screenshot below.
The left column starts with a Comparison Type drop-down box that allows you to choose the type of comparison you want to run. It also contains a set of drop-down boxes to choose class, spec, race, and level, which will be used for all actors. It then has five text fields to define default talents, glyphs, gear, and rotation. Depending on the comparison type chosen, some of these boxes may be disabled.
There is a help text section at the top of the screen above the center and right columns that provides basic instructions on how to use the tool. These instructions will change based on the chosen comparison type.
The center column contains the Configurations text box, which allows you to specify different configurations, and the Footer text box. The Configurations text box will save whatever text you put in it per comparison type, so you can change comparison types without losing your entry for the other comparison types. More detail on the input syntax can be found below in the sections for each comparison type, or at the end in the Appendix: Syntax section. The Footer text box is used to add options to the end of the generated profile.
The right column contains shorthand abbreviations that may be used in Rotation Comparisons; see that section for more details.
When you first view the Automation tab, it will be filled in with some basic defaults, and the Comparison Type drop-down box will be set to "None," which is non-functional. You can change the defaults in the left column in this state, but to do anything useful you'll have to choose a comparison type from the drop-down box in the upper left. Refer to the appropriate section below for specific information on each comparison type.
The Default Talents text box will accept talent inputs in the usual simc format - both talents=0123123 and 0123123 will work seamlessly, as the code checks to make sure that the resulting character profile starts with talents=. Similarly, the Default Glyphs text box will accept a string of glyph names with or without the glyphs= precursor.
The Default Gear and Rotation text boxes accept usual simc gear and action specifications, but do not do any sanity checks. So for example, any of the following are acceptable inputs in the Default Gear box:
#specifying gear line by line
head=fake_helm,id=11111
neck=fake_amulet,id=22222
shoulder=fake_shoulders,id=33333
#specifying gear all on one line
head=fake_helm,id=11111 neck=fake_amulet,id=22222 shoulder=fake_shoulders,id=33333
#specifying a gear set stored in a text file
gear_filename.simc
The Default Rotation box works much the same way. However, the Default Rotation box may be left empty or used to define additional options that apply to every player. The sim will automatically use the default APL that corresponds to your spec if it sees that no action list has been defined. The final box in the left column is only used for the Rotation configuration type, so it is disabled and labeled "Unused" by default. This box will be described in more detail in the Rotation Comparisons section.
Finally, the Footer text box allows you to add custom commands to the generated profile. This is placed at the end of the profile, after all actors have been defined, so this is an appropriate place to define special boss configurations or global simc options (like optimal_raid=0).
Note that when the automation script generates a simulation, it's basically just bolting together your defaults and adding some lines based on what you enter in the center column. As such, you can use almost any tricks you want in these text boxes that work in a standard simc file. In other words, you have the entire Textual Configuration Interface syntax at your disposal.
For example, you could enter 1231231 name=Bob in the Default Talents box, and it would happily work - but all of your actors would be named Bob. For more detail on this, see Appendix: Syntax.
When you select the "Talents" comparison type, the "Default Talents" text box becomes disabled and the center column becomes the "Talent Configurations" text box. In this box, you can specify a list of talent strings, for example:
0000000
1111111
2222222
3333333
1231231
3213213
When you hit the "Import!" button, the script will generate a new actor for each line of text, setting the talents of that actor appropriately. Each actor will use the default glyphs, gear, and rotation specified in the left column, but the first will have talents=0000000, the second will have talents=1111111, and so on. Each actor will be named appropriately as well (ex: T_0000000, T_1111111, etc.).
Since the script is just pasting together bits of text, you can use standard SimC TCI tricks here to specify additional options. For example, with the input
1111111 name=Alice
2222222 name=Bob glyphs=focused_shield
3333333 name=Carl glyphs+=/focused_shield
the automation script will create 3 actors.
- The first will have
talents=1111111and be named Alice. - The second will have
talents=22222222and be named Bob, and will have only the focused_shield glyph rather than whatever you've specified in the Default glyphs box. - The third will have
talents=3333333and be named Carl, and will have the glyph of focused shield active in addition to any glyphs specified in the Default Glyphs box.
If you look at the Simulate tab after pressing "Import!", you'll see that the script is smart enough to append the extra options to the end of the character profile. It does this so that they take precedence over anything you've specified in the defaults. It also checks to see whether you've supplied the talents= portion or not, and adjusts the output as appropriate, so the following is a legitimate input:
1111111 name=Alice
talents=2222222 name=Bob
Note, however, that the very first thing specified for each configuration has to be the talents. name=Alice 11111111 will not work (and will probably generate an error, or at least undesired results!).
The tool expects each new configuration to be a new line - in other words, separated by a single carriage return, with no blank lines in-between. If you leave a blank line (two carriage returns), it will assume that you want a blank line to separate configurations instead, and act accordingly. This is explained in more detail in Appendix: Syntax.
The Glyph comparison type is very similar to the talent one. The Default Glyphs text box will be disabled, and a list of glyph configurations can be specified in the Configurations text box:
alabaster_shield
focused_shield
final_wrath
alabaster_shield/focused_shield/final_wrath
Since glyph names can be rather long, the automation tool will assign a simple numerical name to each configuration by default (ex: G_001, G_002, etc.). Of course, this can be overridden by specifying options:
alabaster_shield name=Albert
focused_shield name=Foucault
final_wrath name=Finn
alabaster_shield/focused_shield/final_wrath name=Alfalfa
As with talents, the glyph configuration needs to be the first thing on each line (so name=Albert glyphs=alabaster_shield will not work). Also as with talents, the tool expects each configuration to be one long string followed by a new line character (carriage return). Do not use blank lines unless you've already read Appendix: Syntax and know what you're doing.
The gear comparison type is a little different, insofar as the input is expected to be a series of items separated by carriage returns. As a result, the Configurations text box will expect you to use a blank line to separate different configurations. In other words, this is how you would specify three gear sets, each containing only head, chest, and legs:
head=fake_helm,id=11111
chest=fake_chest,id=22222
legs=fake_legs,id=33333
head=another_fake_helm,id=11112
chest=another_fake_chest,id=22223
legs=another_fake_legs,id=33334
head=a_third_fake_helm,id=11113
chest=a_third_fake_chest,id=22224
legs=a_third_fake_legs,id=33335
You can specify additional options in two ways - either after any individual item (separated by a space), or on its own new line. The example input below shows both:
#change this configuration's talents and glyphs with space-separated syntax
head=fake_helm,id=11111
chest=fake_chest,id=22222 talents=1233213 glyphs=alabaster_shield
legs=fake_legs,id=33333
#again, but split into multiple lines for no good reason
head=another_fake_helm,id=11112
chest=another_fake_chest,id=22223 talents=1231231
legs=another_fake_legs,id=33334 glyphs=alabaster_shield
#this time, change talents and glyphs on new lines
head=a_third_fake_helm,id=11113
chest=a_third_fake_chest,id=22224
legs=a_third_fake_legs,id=33335
talents=1111112
glyphs=alabaster_shield/focused_shield
Note that since gear is specified after everything else, the tool doesn't bother to move any additional options to the end. So for example, the second configuration above would end up looking like this on the Simulate tab:
#again, but split into multiple lines for no good reason
head=another_fake_helm,id=11112
chest=another_fake_chest,id=22223
talents=1231231
legs=another_fake_legs,id=33334
glyphs=alabaster_shield
Rotation comparisons are more flexible with regards to input because there are two main modes of using the Rotation comparison setting: Longhand and Shorthand.
In longhand mode, you specify each action list in full, just the way you would in a profile, with each action on a new line separated by a carriage return. Thus, the tool expects you to use two carriage returns (a blank line) to separate configurations, as shown in the example below:
actions+=/crusader_strike
actions+=/judgment
actions+=/avengers_shield
actions+=/judgment
actions+=/crusader_strike
actions+=/avengers_shield
actions+=/avengers_shield
actions+=/crusader_strike
actions+=/judgment
As with Gear comparisons, extra options can be specified on any line (space-separated) or on a new line (probably easiest):
name=Alice
actions+=/crusader_strike
actions+=/judgment
actions+=/avengers_shield
actions+=/judgment
actions+=/crusader_strike name=Bob
actions+=/avengers_shield
actions+=/avengers_shield
actions+=/crusader_strike
actions+=/judgment
name=Eve
And also as with Gear comparisons, we don't bother moving space-separated options to the end of the profile. The second configuration will look like this on the Simulate tab:
actions+=/judgment
actions+=/crusader_strike
name=Bob
actions+=/avengers_shield
See the Actions Header and Footer section for information about specifying actions or settings that apply to all configurations.
In shorthand mode, you supply a set of abbreviations (or "shorthands") that specify the rotations you want to test. For example, the three configurations defined in the Longhand section could be specified as follows:
CS>J>AS name=Alice
J>CS>AS name=Bob
AS>CS>J name=Eve
As you can see, this mode uses a ">" to separate actions and a single carriage return to separate actors. It also allows additional simulation options to be specified inline (space-separated). The sim will automatically attempt to invoke shorthand mode if it doesn't find "actions+=" or "actions=" in the configuration.
Shorthand mode also supports full use of conditionals, using the usual syntax with "+" standing for ",if=". So for example,
SotR+DP
might convert to
shield_of_the_righteous,if=buff.divine_purpose.react
The shorthand abbreviations are defined in the third column's Rotation Abbreviations edit box, which becomes enabled when switching the comparison type to Rotation. Ability, Option, and Operator shorthands are defined similarly, as described below. The Options Shorthands section fully describes the syntax for options and the Operator Shorthands section fully describes operator syntax.
Shorthands for abilities, buffs, talents, and glyphs must be defined in the first section of the sidebar under the ":::Abilities, Buffs, Talents, Glyphs:::" section. They use the very simple syntax
Shorthand=longhand_ability_name, separated by carriage returns, as such:
CS=crusader_strike
J=judgment
AS=avengers_shield
GC=grand_crusader
For most specs, the Rotation Abbreviations text box should load with a default set of shorthand abbreviations. If it doesn't, feel free to submit a ticket containing suggested shorthands so that we can add them for your spec.
The text box is editable for a reason - if you don't like a particular abbreviation (maybe you want to use
Cinstead ofCSforcrusader_strike), you can change it! You can also add your own entirely new shorthands by adding them to the list.
Ability shorthands can also be used to represent a combination of an ability and fixed options. For example, if you define
ASGC=avengers_shield,if=buff.grand_crusader.react
it will replace every instance of
ASGCwithavengers_shield,if=buff.grand_crusader.reactjust as you told it to. However, doing so will prevent you from using the built-in options syntax described in the next section, because specifying additional options using the '+' syntax will cause an error. For example,
ASGC+E
would translate to
avengers_shield,if=avengers_shield,if=buff.grand_crusader.react,if=target.health.pct<=20
which will cause an error when SimC tries to build the action list.
Shorthands for options can be specified under the ":::Options:::" heading. By default, choosing a spec will load a set of default option shorthands (ex:
E=target.health.pct<=20). For example, if we define an optionGC=buff.grand_crusader.react, we could specify the shorthand
AS+GC
which translates to
avengers_shield,if=buff.grand_crusader.react
These options can be combined with logical operations just like their longhands can. For example, given the definitions
DP=buff.divine_purpose.react
E=target.health.pct<=20
NF=target.debuff.flying.down
We could specify a shorthand like
CS+DP&(NF|!E)
which translates to:
/crusader_strike,if=buff.divine_purpose.react&(target.debuff.flying.down|!target.health.pct<=20)
The operators
+-*/<=are all supported as well. Note that>is not supported, since that's the delimiter to signify a new action. You can also define your own option shorthands just like you can define ability shorthands.
Options are special, in that they support two additional pieces of syntax:
- The "#" character indicates a required numeric argument. For example, the definition
HP#=holy_power>=#allows you to specify an option to only use an ability if you have greater than or equal to some numeric argument. An example of usage would beSotR+HP4, which the tool would automatically translate to/shield_of_the_righteous,if=holy_power>=4. Note that if specified this way, the numeric argument is not optional - e.g. you would need a separate definitionHP=holy_powerif you wanted just that portion. - The text "$ability" stands for the ability being modified by the conditional. For example, the definition of
BR=buff.$ability.remainscould be used as follows:
SS+BR>2
translates to
/sacred_shield,if=buff.sacred_shield.remains>2
Note that both of these conditionals can be used in a single definition, as in the
AC#=action.$ability.charges>=#.
Operators are special options that require an additional ability, buff, talent, or glyph (the "operand") to operate upon. The syntax for defining operators is the same as the syntax for defining options, including the "#" and "$ability$ replacements. However, operators add another piece of substitution syntax:
- The text "$operand" stands for the shorthand of the operand.
The basic syntax for using an operator/operand pair in a shorthand is "
B.C", whereBis the operand (the ability, buff, glyph, or talent being operated upon) andCis the operator.
To illustrate how this works, consider a case where you want to cast a spell only if a particular buff is active. For example, maybe we want to create a shorthand for
/avengers_shield,if=buff.grand_crusader.react
We've already seen how we can do this with just an ability declaration, or as an ability+option combination. However, we can also do this in operator form. Given the ability definitions
AS=avengers_shield
GC=grand_crusader
and the operator definition
BA=buff.$operand.react, we can construct the shorthand
AS+GC.BA
which translates to the desired
avengers_shield,if=buff.grand_crusader.react.
Just like other options, an option containing an operator can be combined with other operators via logical operations. So for example,
AS+GC.BA&E
translates to
/avengers_shield,if=buff.grand_crusader.react&target.health.pct<=20
While everything the operator system lets you do can already be accomplished by defining special options, the operator system gives you a lot more flexibility. For example, the definition "
BR#=buff.$operand.remains>#" lets you implement buff checks for anything defined in your Abilities section without having to write a separate option for each one (like our ASGC example).
Note: The Rotation Abbreviations text box is saved when exiting the program, so that your custom abbreviations will still be there when you start it again. However, note that it is not saved independently for each spec. Thus, when you switch the Class or Spec drop-down boxes, the tool will load the set of defaults for the new spec, and will "forget" any custom definitions you may have added. If there are definitions you use frequently, it is advisable to keep them in a text file somewhere for easy copy/pasting.
When choosing the Rotation comparison type, the "Default Rotation" text box is renamed to "Actions Header" and the "Unused" box is renamed "Actions Footer" and becomes enabled. This is because it is very common to want certain actions that apply to all rotations (like /auto_attack) without having to explicitly define shorthands. The Actions Header and Actions Footer boxes provide support for this. As you might guess, the text in the Actions Header box is placed in the profile immediately before the text generated from the Rotations Configuration input, and the text in the Actions Footer box is placed immediately after the text generated from the Rotations Configuration input.
So for example, if I just want to run a comparison of several different holy power generator priorities, I might define the following Actions Header:
actions.precombat=flask,type=greater_draenic_stamina_flask
actions.precombat+=/food,type=talador_surf_and_turf
actions.precombat+=/seal_of_insight
actions.precombat+=/sacred_shield
# Snapshot raid buffed stats before combat begins and pre-potting is done.
actions.precombat+=/snapshot_stats
actions=/auto_attack
actions+=/eternal_flame,if=buff.eternal_flame.remains<2&buff.bastion_of_glory.react>2&(holy_power>=3|buff.divine_purpose.react|buff.bastion_of_power.react)
actions+=/eternal_flame,if=buff.bastion_of_power.react&buff.bastion_of_glory.react>=5
actions+=/shield_of_the_righteous,if=holy_power>=5|buff.divine_purpose.react|incoming_damage_1500ms>=health.max*0.3
which would take care of precombat actions (applying a seal, flask, food, and pre-casting Sacred Shield if it's available) as well as enabling auto-attack and defining holy power consumers.
If I also want to add a line to the end of every profile that attempts to refresh Sacred Shield, I could put the following text in the Action Footer:
actions+=/sacred_shield
If I enter
CS>Jin the Rotation Configurations text box, the total APL generated will then be:
actions.precombat=flask,type=greater_draenic_stamina_flask
actions.precombat+=/food,type=talador_surf_and_turf
actions.precombat+=/seal_of_insight
actions.precombat+=/sacred_shield
# Snapshot raid buffed stats before combat begins and pre-potting is done.
actions.precombat+=/snapshot_stats
actions=/auto_attack
actions+=/eternal_flame,if=buff.eternal_flame.remains<2&buff.bastion_of_glory.react>2&(holy_power>=3|buff.divine_purpose.react|buff.bastion_of_power.react)
actions+=/eternal_flame,if=buff.bastion_of_power.react&buff.bastion_of_glory.react>=5
actions+=/shield_of_the_righteous,if=holy_power>=5|buff.divine_purpose.react|incoming_damage_1500ms>=health.max*0.3
actions+=/crusader_strike
actions+=/judgment
actions+=/sacred_shield
The Configurations text box is actually a little more flexible than described in each section. To be able to support both modes, it has to support separating configurations by both a single carriage return (for talents, glyphs, and shorthand rotations) or two carriage returns (for gear and longhand rotations). In fact, it actually supports both of these for all configuration types.
It first attempts to split the input to the text box based on two carriage returns ("\n\n" in coding speak). It then checks to see if that gives it more than one configuration to work with. If so, it uses those results to attempt to generate the profiles. In this case, it will ignore any comments (lines starting with "#") and treat the first non-comment line of each configuration as the first line of input.
If splitting on "\n\n" yields only one configuration, it tries to split the input once again, this time based on a single carriage return ("\n"). In this case, you really shouldn't be using comments (though technically, single-word comments like "#this" won't break anything).
As such, you could use either method in each mode, so long as you only used one or the other. For example, this is a perfectly reasonable input for a talent comparison:
#remember, this mode ignores comments
0000000 name=untalented
#flagrant
#comment
#spam
1111111 name=One
2222222
#peek-a-boo
name=Two
3333333
name=Three
However, it's also unnecessarily verbose, which is why I've suggested using single carriage returns for the talent, glyph, and shorthand inputs. Likewise, you could certainly define a Gear comparison like this:
head=fake_helm,id=11111 chest=fake_chest,id=22222 name=Alice
head=fake_helm_2,id=11112 chest=fake_chest_2,id=22223 name=Bob
head=fake_helm_3,id=11113 chest=fake_chest_3,id=22224 name=Eve
or a Rotation comparison like this:
actions+=/crusader_strike/judgment/avengers_shield name=Alice
actions+=/judgment/avengers_shield/crusader_strike name=Bob
actions+=/avengers_shield/crusader_strike/judgment name=Eve
But that might get difficult to read if you were specifying an entire gear set or rotation and additional options.
The key point here is that either input mode will work, but don't mix them. The following talent comparison input will fail in a spectacular fashion when you try to simulate:
#WARNING: NEVER DO THIS
0000000 name=Alice
1111111 name=Bob
2222222 name=Carlos
3333333 name=Don
1231234 name=Eve
The sim will take this to mean you have three actors. It'll skip the comment in the first actor and properly figure out that you want "talents=0000000". But at the end of the profile it will then add
name=Alice
1111111
name=Bob
which isn't what you want, and the "1111111" line will trigger an error when you hit Simulate.