Getting started

To write an addon in LUA you just simply need a text editor and save the file along with some other files into the addon folder of your World of Warcraft client. Writing in Typescript is a bit more complex on the setup side but it's worth the short extra time.

IDE and environment

To transpile your written Typescript code in LUA you need the Node.js runtime. Download your favorite (LTS or current) and install it on your system.

Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine

When done you need to have some kind of text editor or IDE. I personally prefer Visual Studio Code because it has exellent Typescript support including autocompletion (And hell yes, we want autocompletion for the full WoW API).

After having Node.js and a favorite IDE installed, setup an empty Typescript project, lets continue by looking at dependency management.

Dependency management

QhunCoreTS is a framework that is embeded in your addon. So where do I find this framework? The answer ist simple. You need to add dependencies to your addon.

To install dependencies in a Node.js environment you have to use the console View -> Terminal (VSCode) and type the following commands:

$ npm init -y    # this will create a package.json file for you
$ npm install --save-dev @wartoshika/wow-qhun-core-ts     # this will install the framework, wow api declarations and the transpiler

You may noticed that a directory called node_modules has been created. This is the place where Node.js stores installed dependencies and add them to your package.json file.

The next step is to add two more files in order to tell Typescript how your project should be interpreted (tsconfig.json) and a file to tell qhun-transpiler how to transpiler your addon. Lets call it qhun-transpiler.json.

Your project file structure should look like the following:

yourAddon/
    - node_modules/
    - package-lock.json
    - package.json
    - qhun-transpiler.json
    - tsconfig.json

Configure environment

You now need to alter the file contents to reflect this code block:

tsconfig.json

{
    "compilerOptions": {
        "module": "commonjs",
        "noImplicitAny": true,
        "removeComments": true,
        "preserveConstEnums": true,
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,
        "outDir": "dist",
        "moduleResolution": "node",
        "target": "esnext",
        "sourceMap": true,
        "typeRoots": [
            "node_modules/@types",
            "node_modules/@wartoshika"
        ]
    },
    "include": [
        "./src/**/*.ts"
    ]
}

To get a deeper understanding of what the tsconfig.json file does, visit the Typescript handbook pages.

qhun-transpiler.json

{
    "name": "YOUR ADDON NAME HERE",
    "version": "YOUR VERSION HERE",
    "author": "YOUR NAME HERE",
    "licence": "YOUR LICENSE HERE",
    "description": "YOUR DESCRIPTION HERE",
    "stripOutDir": "src",
    "target": "wow",
    "tsconfig": "./tsconfig.json",
    "config": {
        "staticReflection": 7,
        "visibleName": "YOUR INGAME VISIBLE ADDON NAME HERE",
        "interface": 80000
    }
}

After changing the placeholder text and saving the file, you should be able to start building the actual addon. If you want to get a deeper understanding of the qhun-transpiler.json file, read the documentation.

Hello world addon

Ready to rumble, lets talk about code.

You should start by creating a source folder called src and create a file eg. MyAwesomeAddon.ts. The .ts extension shows your IDE that this is a Typescript file so syntax highlighting and autocompletion will start working.

import { QhunAddon, bootstrapAddon } from "@wartoshika/wow-qhun-core-ts/src/core";

@QhunAddon()
class MyCoolAddon {

    constructor() {

        print("Hello World of Warcraft", "This is my Typescript addon!");
    }
}

bootstrapAddon(MyCoolAddon);

Step by step explanation:

• The first import statement imports QhunAddon and bootstrapAddon from the frameworks core module. Since no class is available in your file context you must import nessesary classes and functions from other files.
• @QhunAddon is the entrypoint of your Addon.
• Declaring a class named MyCoolAddon with a constructor function
• Print your hello world string onto the default console in your WoW client
• Finally the function call to bootstrapAddon outside of your class context will bootstrap your declared addon class by handling over your class name.

You may noticed the usage of the print function. Every LUA and WoW function is available in the Typescript context!

Your project structure should now reflect the current following:

yourAddon/
    - node_modules/
    - src/
      - MyAwesomeAddon.ts
    - package-lock.json
    - package.json
    - qhun-transpiler.json
    - tsconfig.json

If this is the case, you are ready to transpile the Typescript source code into LUA.

Transpiling to LUA and run with the WoW client

Last but not least you need to transpile this code into a WoW understandable language. The transpiler software supports WoW per design, no worry about issues with unsupported functions. If you used a function of the Typescript universe - that is not supported by the transpiler - you will be notified at transpiling time.

To transpile your addon you need to run the following statement from your console:

$ ./node_modules/.bin/qhun-transpiler -p ./qhun-transpiler.json

There should now be the following output on your console:

Added @wartoshika/wow-qhun-core-ts as external module.
Successfully transpiled X files.

If you dont received that output, go to the troubleshooting page and look for help.

Congratulations on transpiling your first file into WoW compatible LUA!

You may find the generated files in the dist folder that has been created. There you can find your transpiled MyAwesomeAddon.lua, the .toc file according to your addon and the embedded framework. Copy this files into your WoW addon folder and start the game!

Watch for the generated output on the default console and be happy 👍

Tip: Speed up the transpiling and testing process

There are two ways to speed up this transpiling process.

1. Create an alias for the transpiling command in the package.json file.

{
// ....
  "scripts": {
    // add this line of code
    "start": "./node_modules/.bin/qhun-transpiler -p ./qhun-transpiler.json",
  },
// ....
}

You can now start the transpiling process by typing the following command:

$ npm start

2. Create a symbolic link from the dist folder to your addon folder.

On Windows (You need to open the terminal as administrator):

$ mklink /D "C:/path/to/wow/addon/MyAwesomeAddon" "C:/path/to/your/addon/source/dist"

The content of your dist folder will now be visible in addon/MyAwesomeAddon and can be read by the WoW client.