-
Notifications
You must be signed in to change notification settings - Fork 0
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.
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.
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
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.
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
andbootstrapAddon
from the frameworkscore
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.
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 👍
There are two ways to speed up this transpiling process.
{
// ....
"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
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.
- Getting started
- What is Typescript and why i choose Typescript
- Available modules
- Core
- Database
- Locale
- Model
- Net
- Slash
- UI