Wiki - Build & Install

Overview

WarcraftXL is the framework that loads into the running game. The thing you build is WarcraftXL.dll: it boots inside the client, brings up the hook engine, and raises a set of events that modules react to. Modules live under scripts/ and compile into that same DLL, so building the framework builds your modules with it.

Before you start. The target is a 32-bit process, so everything builds Win32. You also need a 3.3.5a client that you legally own - WarcraftXL ships no game files.

Requirements

Windows with a Win32 C++17 toolchain - Visual Studio 2022 is recommended.
CMake 3.25 or newer.
PowerShell 5.1 or newer (it ships with Windows) if you use the helper script.
A legally-obtained 3.3.5a (build 12340) client to deploy into and test against.

Get the source

Clone the framework repository. Modules are separate repositories you drop into scripts/.

git clone https://github.com/WarcraftXL/wxl-core.git
cd wxl-core

To add a module, clone it under scripts/ - it is picked up on the next build:

git clone https://github.com/WarcraftXL/wxl-unit-outline.git scripts/wxl-unit-outline

Build

There are two ways to build: the helper script (recommended, it also deploys) or raw CMake.

Helper script

build.ps1 configures, builds Release, and copies the result into your client. On the first run, point it at your client folder once - the path is remembered afterwards.

# first run - tell it where the client is
.\build.ps1 -ClientPath "D:\Path\To\3.3.5a"

# from then on, just
.\build.ps1

The build output is WarcraftXL.dll (with the d3d9.dll proxy alongside it), deployed into the client folder.

Raw CMake

If you would rather drive CMake yourself:

cmake -B build
cmake --build build --config Release --target WarcraftXL

Vendored dependencies build with the project, so there is nothing else to fetch.

Build options

The helper script takes a few switches:

Switch	What it does
-ClientPath	Client folder to deploy into. Needed once, then cached.
-Clean	Wipe the build directory first for a from-scratch build.
-AutoPatch	Prepare the client's executable to load the framework. Idempotent, and it backs up the original first.
-BuildHost	Also build the companion asset host.

Install into the client

If you build with the helper script, the files are already in place. To set it up by hand, put WarcraftXL.dll and the d3d9.dll proxy next to Wow.exe, then run the one-time patch so the client loads the framework on launch:

.\build.ps1 -AutoPatch

Launch the game. On bootstrap the framework writes a startup log - check it to confirm the modules came up.

Touching a client binary is on you. Work on a copy, keep an untouched backup, and only point this at a client and server you are permitted to modify and connect to.

Your first module

A module is a class that subscribes to engine events in its constructor and reacts in the handlers. A file-scope instance registers itself when the DLL loads.

#include "events/EventScript.hpp"

class HelloModule final : public wxl::events::EventScript {
public:
    HelloModule() {
        on<&HelloModule::OnEndScene>(wxl::events::Event::OnEndScene);
    }

    void OnEndScene(const wxl::events::EndSceneArgs& a) {
        // runs every frame - draw an overlay, read the world, edit it...
    }
};

// self-registers at load
HelloModule g_helloModule;

Drop the file under scripts/your-module/, rebuild, and it is live. From the handler you reach the rest of the game through the typed wxl::game bindings - never a raw address.

The asset host

Some setups run a companion process, the asset host, that serves the client's files from outside the game. It is optional and off the critical path for most modules. Build it by adding -BuildHost to the helper script.

.\build.ps1 -BuildHost

Logs & troubleshooting

Nothing happens on launch. Confirm WarcraftXL.dll and the d3d9.dll proxy sit next to Wow.exe, and that the patch step ran.
Check the startup log. The framework writes one on bootstrap; it lists the modules that registered.
Build is the wrong architecture. The client is 32-bit - make sure you configured a Win32 toolchain, not x64.

Still stuck? Open an issue on the GitHub organization.