SimulationCraft: a C++ WoW combat simulator whose GUI is called largely unmaintained while the tree still builds four of them

The file calls the GUI largely unmaintained, the tree ships four solutions for it

Two executables are shipped: simc uses a command line interface, while SimulationCraft is the graphical front end. The same paragraph that names them says the graphical user interface is largely unmaintained and that it is highly recommended to use the command line instead. The Armory download and analysis path is part of that interface.

The repository layout tells a different story about how much work the GUI still receives. There is a qt/ directory, a gui/ directory, a simcqt.rc resource file, both simulationcraft.pri and simulationcraft.pro build files, a logos/ directory, and a WinReleaseScripts/ directory. On the Windows side there are four separate solutions: simc_vs2017.sln, simc_vs2019.sln, simc_vs2022.sln and simc_vs2026.sln.

Four solution files for one project is a maintenance surface of its own, since each Visual Studio generation needs its own copy kept in step. The gap between what the file says about the interface and what the tree maintains for it is the first thing to resolve before choosing a front end.

No Linux package, but a Dockerfile, a flake and an osx snapshot script

The file sends you to the downloads page for a package for your particular platform, then immediately withdraws that promise for one of them: there is no Linux release, since it is so ridiculously easy to build it yourself on that platform. What it describes in detail is Windows, which offers both a formal install and an archive that can be extracted onto your desktop. macOS is not mentioned in that section at all.

The root of the repository tells a fuller story. There is a Dockerfile and a .dockerignore, a flake.nix with a flake.lock, and a build_snapshot_osx.sh script whose name implies an operating system package that the file never describes. There is also a .travis.yml sitting next to a .github/ directory, so continuous integration configuration spans two generations of tooling.

So the file documents Windows binaries, declares Linux unnecessary, and leaves macOS to a shell script. The repository itself has no GitHub releases, which also sits oddly beside the instruction to check the release notes, since releases are expected to be frequent.

Every wiki link climbs two directories above the repository root

The help section points readers at a starters guide, at the wiki pages, and at a common issues page. Each of those is a relative link written as ../../wiki/StartersGuide, ../../wiki/ and ../../wiki/CommonIssues, and the same ../../ pattern is used for the issue links. A path that begins with two levels up does not stay inside the repository, so the documentation leans on links that only resolve from the site rather than from the checkout.

Two other links point at anchors inside the same file, at the Community section, from text that appears several sections earlier. Those work, and they are the only internal links in the file.

There is also a short notice about naming, and it is unambiguous: SimulationCraft is different from SimCraft, and anyone looking for full-motion simulators for SimRacing and FlightSim should visit SimCraft instead. Given how often the two names get confused in search results, that notice is the reason to prefer the full name or the short form SimC when looking for documentation.

The Docker build bakes in an API key and tunes for generic hardware

The Dockerfile builds simc with clang, thin link time optimization and profile guided optimization enabled:

make -C /app/SimulationCraft/engine release CXX=clang++ -j ${THREADS} LTO_THIN=1 LLVM_PGO_GENERATE=1 OPTS+="-Os -mtune=generic" SC_DEFAULT_APIKEY=${APIKEY}

Two things in that one line matter. The API key is a build argument that gets compiled into the binary as SC_DEFAULT_APIKEY, which is how the tool authenticates against the Blizzard API for Armory imports. And the optimization flags say -Os -mtune=generic, so an image built this way is deliberately not tuned for the CPU that built it. That is the right call for an image meant to be shared, and the wrong call if the goal is the fastest possible local simulation.

Profile guided data is collected by running the CI profile for a hundred iterations, merging the raw profiles, and rebuilding:

LLVM_PROFILE_FILE="code-%p.profraw" ./engine/simc ${PGO_PROFILE} single_actor_batch=1 iterations=100

So the image is not just a compile wrapper. It runs the freshly built binary once to train its own optimizer.

The example passes a build argument the header never lists

The Dockerfile header names the build arguments it expects: THREADS with a default of 1 and a note to supply a value for -j, and APIKEY with an empty default, used for authentication with the Blizzard API. The example directly underneath passes something else:

docker build --build-arg THREADS=2 --build-arg NONETWORKING=1 -t simulationcraft .

NONETWORKING is not in the list of available build arguments. Going the other way, the file declares ARG PGO_PROFILE="CI.simc" and uses it to drive the instrumentation run, but PGO_PROFILE is not in that header list either. The documented inventory and the actual arguments disagree in both directions.

The run command shows what the image expects on the command line, and it is a simulation input rather than a shell:

docker run simulationcraft spell_query=spell.name=frost_shock

The header also says that to reduce the footprint, all SimulationCraft files are removed except ./simc and ./profiles/*, while the build steps in the same file work from ./engine/simc.

Why an event driven simulator rather than another closed form calculator

The design premise is stated as a correction to other tools. Increasing class synergy and the prevalence of proc-based combat modifiers have eroded the accuracy of traditional calculators that rely on closed-form approximations to model very complex mechanics. The stated goal is to close that accuracy gap while maintaining a performance level high enough to calculate relative stat weights for gear selection.

That second half of the sentence is the constraint that shapes everything else. A simulator can be exact and useless if it takes too long to run, and relative stat weights are what a gear decision actually consumes, so throughput is part of the correctness argument rather than an afterthought. It also explains the profile guided optimization step in the container build and the thread count build argument.

Scope follows the same line: a multi-player event driven simulator written in C++, modelling character damage per second across raiding and dungeon scenarios, with raid or party creation of arbitrary size and detailed charts and reports for both individual and raid performance.

Character data arrives from the Armory and needs a Blizzard API key

There are two ways in, and they differ in how a character reaches the tool. The graphical interface lets players download and analyze characters from the Armory. Run from the command line instead, player profiles are specified through parameter files, so the data comes from the local filesystem.

Either way the Armory route talks to the Blizzard API, which is what the APIKEY build argument and the SC_DEFAULT_APIKEY compiler define exist for. The repository also carries casc_extract/ and dbc_extract3/, directories whose names point at extracting game data, alongside SpellDataDump/ and a profiles/ directory that supplies the inputs the command line path expects.

The file treats a failed import as a support case rather than a user error: if you are unable to download your character, open an issue. It also asks for an issue when an analysis looks wrong and when a directive you need is missing, and it makes the point that opening an issue is by far the most effective way to get a swift resolution, compared with email, forum posts or chat messages.

Eight vendored licences, one unexplained, and no GitHub release

The project is GPL-3.0, with COPYING at the root. Alongside it sit LICENSE.BOOST, LICENSE.BSD, LICENSE.BSD2, LICENSE.LGPL, LICENSE.MIT and LICENSE.UNLICENSE, and the file attributes those to eight external libraries: RapidJSON and RapidXML under MIT, MSInttypes r29 under BSD 3-Clause, the Qt Toolkit under the GNU Lesser General Public License version 3, UTF-8 CPP under the Boost Software License, {fmt} and cpp-semver under MIT, and utf8.h under the Unlicense.

One file in that set has no library attached to it in the list. LICENSE.BSD2 sits at the root, and nothing in the external library section names a component licensed under it, so the mapping between the licence files and the code they cover is incomplete in the documentation.

Mixing LGPL and GPL in one binary is the kind of arrangement that deserves a deliberate decision rather than an inherited one, and the file settles nothing about how Qt is linked. Separately, the repository has no GitHub releases even though the file says releases occur quite frequently and tells you to check the release notes.

Editorial conclusion

Judgement: SimulationCraft is worth the setup cost for anyone who models gear decisions rather than reads them, because that is the closed form accuracy gap the project exists to close. Go in through simc and the parameter file route, not the graphical interface, which the file itself calls largely unmaintained. Expect to build it yourself on Linux and macOS, since only Windows packages are offered. Before trusting a character import, know that the Armory path needs a Blizzard API key, that the Docker image compiles one in at build time and optimizes for generic hardware, and that the wiki links in the file point outside the repository.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases