Starting from SimulationCraft

Started From The Simmin’ — Now We’re Here

The SimulationCraft Importer is a new feature in Hekili v2.5. It will try its hardest to take a complete SimulationCraft Action Priority List (APL) and turn it into a fully-functional display with attached action lists.

When I started developing the Hekili addon during Mists of Pandaria, the addon supported one class (Shamans) and two specializations (Enhancement, Elemental). The core design goal was to make the addon give suggestions as consistent with SimulationCraft as possible, so that when a player wonders why their performance trails behind the beloved SimulationCraft stacked rankings, they can see live, in-game what they’re doing differently from SimulationCraft.

From There to Here

So how do we get from a SimulationCraft APL to a shiny in-game display? Until recently, the process involved a lot of manual labor, converting each APL by hand into the four key elements used by the addon:

Actions, which are grouped into
Lists, that are connected by
Hooks, attached to one or more
Displays.

After translating from SimC to Hekili, I would go to the additional step of hardcoding each display as class defaults, distinguishing them from other lists by highlighting their names in blue.

For Hekili v2.5, the SimulationCraft Importer has undergone a lot of redevelopment. Now, if you want to import an APL into the addon, you can open the Hekili UI (/hekili) and go to the importer tab to get started.

An Example Case

For demonstration purposes, we’ll import the SimulationCraft APL for Beast Mastery Hunters. We can get this from opening the sample APL from the SimulationCraft program, or grab the latest development APL from the SimulationCraft repository on Google Code.

We can start by selecting the entire APL and copying it to the clipboard. The essential lines are all the lines that start with actions… Everything else is ignored. Still, to save time, let’s copy everything from the first line (hunter=”Hunter_BM_T17M”) to the last line (summon_pet=cat). We’ll paste it into the box labeled SimulationCraft APL.

As you can see, I’ve pasted the entire APL from SimulationCraft into the SimulationCraft APL box inside the addon. There’s a shiny red button labeled Import Action Lists at the bottom, but let’s look at the other options first!

There are several other settings we should consider before we hit Import Action Lists. The first setting, Import to Display, allows us to tell the addon whether we want to create or update a display when we import the APL. In some cases, we might just want to update some existing action lists and leave the displays alone. However, in our case, we do want to create a display, since we don’t have any displays for Beast Mastery yet, so we’ll leave this setting checked.

With Import to Display checked, the Display Settings group is visible. The Destination Display dropdown lets us decide whether we want to create a brand new display or use an existing display, overwriting it with the new settings. In our case, we want to create a new display, and we’ll name it Beast Mastery: Primary, since that’s what we’ll be using it for once we’re done setting it up. Enter the name you choose in the New Display Name field — if you enter an existing display name while the Destination Display is set to Create New Display, the addon will refuse to import until you correct the error.

In the Action List Settings section, we get similar options. We can choose to Overwrite Existing action lists, if any action lists with the same name happen to exist. Additionally, we can set an Action List Prefix, which will help determine the final name given to each automatically generated action list.

In this example, we’ll set the Action List Prefix to BM (for Beast Mastery). If we inspect the APL, we’ll find that there are two action lists used by SimulationCraft in this particular case. Some of the entries begin with actions.precombat and the rest start simply with actions. These are both special action lists, as precombat actions are meant to be used before entering combat, while actions is the default action list which is processed after combat begins.

The importer will use the prefix provided, as well as the action list’s name from the APL to create a new name within the Hekili addon.

actions.precombat will become BM: Precombat.
actions will become BM: Default.

After configuring everything as described above, we can press the Import Action Lists button and see the result.

In the left column, we can see Beast Mastery: Primary listed under Displays, and the new action lists we expected have appeared under Action Lists. These new items appear with their names in white because they are not defaults built into the addon itself — defaults appear in blue.

Oh, and yes, just to confirm, the new display is there:

My Hunter alt’s dreams of a Beast Mastery display have come true. The overlaid text and translucent mover will disappear when we close the Hekili UI.

But Wait, What Are These Warnings?

Ah, you saw that. Good, you’re paying close attention. After clicking the Import Action Lists button, a new box appeared on the SimulationCraft Importer tab. These Warnings are not so ominous. The addon is just letting us know if it ran into any issues when building your action lists and display. In this case, here’s the feedback…

WARNING: The import for ‘Default’ required modifications:
Line 11: Converted ‘focus’ to ‘focus.current’ (1x).
Line 20: Converted ‘focus’ to ‘focus.current’ (1x).
Line 23: Converted ‘focus’ to ‘focus.current’ (1x).
Line 28: Converted ‘focus’ to ‘focus.current’ (1x).
Line 28: Converted unconditional ‘X.react’ to ‘X.up’ (1x).
Line 29: Converted ‘focus’ to ‘focus.current’ (1x).

WARNING: The import for ‘Precombat’ required modifications:
Line 3: Unsupported action ‘summon_pet’.
Line 5: Unsupported action ‘exotic_munitions’ with modifiers ‘ammo_type=poisoned’ and conditions ‘active_enemies< 3’.
Line 6: Unsupported action ‘exotic_munitions’ with modifiers ‘ammo_type=incendiary’ and conditions ‘active_enemies>=3’.

The first section, regarding the Default action list that became BM: Default, shows several syntax changes that the addon made for us automatically. The reason for these adjustments is that the addon’s engine and the SimulationCraft engine are written in different programming languages (the addon in Lua, SimulationCraft in C++). While SimulationCraft can refer to your current focus as simply focus and your maximum focus as focus.max, the addon checks your current focus using the identifier focus.current.

The second section shows us that there were some abilities that SimulationCraft supports that are not (yet) supported by the addon. The missing abilities in this case were summon_pet and exotic_munitions. When the addon finds an ability that is not supported, it is skipped and left out of the resulting action lists. That means the addon currently will not tell us when to summon our missing pet, or change our Exotic Munitions if we’re using that level 100 talent. (Yet.)

Last, it’s worth noting that some abilities get special handling when imported from a SimulationCraft APL. In the case of Hunters, the rapid_fire, stampede, dire_beast, and bestial_wrath abilities are treated as cooldowns and can be toggled on and off using the Show Cooldowns setting in the Toggles section. Similarly, interrupt abilities are generally linked to the Show Interrupts setting (and are only recommended when your target is actually casting an interruptible ability).

Ok, So What Else?

First, I’ll leave it as an exercise for the reader to compare the action lists in-game with what we pasted from SimulationCraft. You can inspect and modify each action list in the Hekili UI by clicking the + next to its name under Action Lists. Explore a bit… If you break something, you can re-import everything and start over without much trouble. If you find that something was imported incorrectly, please contact me and let me know — I expect that the new system will have some kinks to work out.

Second, it’s worth taking a look at our new display’s configuration. Let’s click Beast Mastery: Primary under Displays.

Ok, that’s a lot of stuff. Good news! The default values should work well for a primary display. Let’s see what kind of adjustments we might want to make.

Here, you can see that the display is Enabled, its name is set to Beast Mastery: Primary (and you can change it if you want), and it will work with both our primary and secondary Talent Groups as long as we’re in our Beast Mastery Specialization.

So what are these Mode Overrides? These settings allow you to force the display to act as though there are certain number of targets based on the addon’s Current Mode (see the Toggles section of the Hekili UI). If set to zero, any of these settings are ignored. The default settings, shown above, indicate that if our Current Mode is set to Auto, then this display make its recommendations using the actual number of enemies that were detected — there’s no artificial Auto: Minimum or Auto: Maximum.

However, if our Current Mode is set to Single Target, then this display will act as though there is only 1 target available, as the Single: Maximum is set to 1. If the Current Mode is set to AOE, then the display will act as though there are at least 3 targets detected, even if there are fewer, because the AOE: Minimum is set to 3.

Ok, So What If I Want an AOE Display?

Good news! You know what separates an AOE display from a Primary display? An AOE display always acts as though there are always multiple targets to attack. Hm, if only there were a feature that would fool a display into thinking there were always 3 or more enemies… That’s right — the Mode Overrides are the key.

Let’s make a copy of our Beast Mastery: Primary display and call it Beast Mastery: AOE. We can do this by clicking the + next to Beast Mastery: Primary, and choosing the Import/Export subgroup.

The Import/Export subgroup lets us copy our displays, import displays from fellow players, or export our displays to share with others. The import and export features are currently limited by the fact that if players don’t have the action lists of the same name, the displays will not be able to hook the missing lists.

All we have to do is enter Beast Mastery: AOE in the Copy To box and press Enter.

Our Beast Mastery: AOE display appears as next in the Displays list.

The new display was added to the list of Displays. As you can see in the image above, I’ve already made the changes to the Mode Overrides so that this display will always act as though there are at least 3 targets. The Auto: Minimum, Single: Minimum, and AOE: Minimum are all set to 3. The maximum settings have all been set to zero, which means those settings are ignored.

Further Customization

Like the default displays that you may already be familiar with, these new displays we’ve made can be customized in terms of size, position, direction, number of abilities to show, fonts, captions, and so on. Most of these settings can be found in the UI and Style subgroup under each display.

After moving our new displays to where I want them, I can change the aesthetic from something like this…

You can see that I’ve placed the Beast Mastery: AOE display on top, with the Beast Mastery: Primary display on bottom. There are a couple of issues for me, in that the display is too wide, getting hidden behind the auras on my target, and the first icons of each display overlap a bit.

…to something like this:

Now, each display is only four icons long. The primary icons are set to the same size as the rest, and now both displays line up nicely without overlap. But what is that red 3 on the AOE display?

What did I change? For both displays, I went to their UI and Style sections and set Icons Shown to 4. I also changed the Primary Icon Size to 40, matching the Queued Icon Size. On the Beast Mastery: AOE display, I also changed the Primary Caption to Show # of Targets. The number of targets appears in the bottom right corner of the display’s primary icon.

Why is the target count shown in red? The addon displays the number of targets in red when it has not actually detected that many enemies. The Beast Mastery: Primary display, remember, is forced to act as though there are 3 or more targets at all times. If I attack a few of the training dummies, the number changes and turns white — the addon will tell you it actually sees 5 enemies.

Now that I’ve attacked five enemies, the red 3 changes to a white 5 on the AOE display.

Wrapping Up

That covers the new SimulationCraft importer, which is in the current beta (r200) version of the addon available on Curse. Give it a try, but remember, the APL you use must be supported by the addon. Shamans (Enhancement, Elemental), Monks (all specializations), Paladins (Retribution, Protection), and Hunters (all specializations) can use this feature. No other classes are presently supported by the addon.

Did this work for you? Have questions or feedback! Please let me know. Comment here or respond back @Hekili808 on Twitter. Mahalo!