This article contains information specific to writing livescripts targeting the C++ backend, but the guidelines laid out in Language Differences are useful even if you are currently targeting Lua, since C++ is the more restrictive backend, and by following them you leave the door open to use C++ in the future in case you would ever need to.
Note: As TSWoW develops, some caveats listed in this section might disappear.
LiveScripts transpiled to C++ have much more restrictions than when using the Lua backend, since C++ is a much more different from JavaScript, and a more restrictive language. Generally, any LiveScript that works with C++ should also work for Lua, but the inverse is not true at all.
LiveScripts do their best to abstract away the manual memory management in C++ by using smart pointers and stack objects where possible. However, there are a few concerns you will have to consider.
The types we receive from event callbacks are special pointer types. These should never be stored anywhere in a live script, store their GUIDs instead (using .GetGUID). These types are owned by the server core, and there is no way to know if the memory they point at remain valid after the event has finished executing.
If two objects in TSWoW refer to each others and form a cycle, they will not be automatically cleaned up if all other references to them are lost, since C++ does not have a (built-in) garbage collector. If we use circular data types, we need to make sure that those cycles are broken when the data should be removed.
Since livescripts written in TypeScript can be transpiled to C++, they have a few caveats, but also a few improvements over normal TypeScript and JavaScript.
These are special variable names that you cannot use.
| Type | Reason |
|---|---|
| template | Refers to templates in C++ |
Callback functions are used either to register events to the TSEvents, or as callbacks to map/array higher order functions (filter, reduce, forEach etc.).
Asynchronoius callback functions cannot read or modify scoped/non-global variables, such as event handlers, timers or delayed events. Trying to do this should raise a compiler error.
Synchronous callbacks, such as arrays map/filter/reduce/forEach, can access their enclosing scope, but still not across asynchronous boundaries.
let globalVar: uint32 = 0;
export function Main(events: TSEvents) {
let localVar: uint32 = 0;
events.Player.OnSay(()=>{ // <-- asynchronous callback
localVar = 10; // does not work
if(localVar > 10) {} // does not work
globalVar = 10; // works
if(globalVar > 10) {} // works
let cbVar: uint32 = 0;
[].forEach(()=>{ // <-- synchronous callback
cbVar = 10; // works
if(cbVar > 10) {} // works
globalVar = 10; // works
if(globalVar > 10) {} // works
})
}
}
Arrays are created by specifying their type and then assigning normally:
const arr = [1,2,3]; // <-- works, but numbers assumed to be floats
const arr : TSArray<uint32> = []; // <-- works
const arr2 : TSArray<uint32> = [1,2,3]; // <-- works
Looping with for…in or for…of is currently disabled, but you can still loop by index:
const arr : TSArray<uint32> = [1,2,3]
for(let value of arr) { } // <-- does not work (for .. of unsupported)
for(let value in arr) { } // <-- does not work (for .. in unsupported)
for(let i=0;i<arr.length;++i) { } // <-- works
arr.forEach((value,index)=>{}) // <-- works
A few callback functions have different arguments compared to normal TypeScript, which might show up incorrectly in the autocompletion examples. This section shows correct parameters of each such function.
const arr: TSArray<uint32> = [1,2,3];
arr.forEach((value,index)=>{});
arr.filter((value,index)=>true);
// it is recommended, but not required, to specify the output type for reduce
arr.reduce<uint32>((prev,value,index)=>prev+value,0);
// map **must** specify the output type explicity (<uint32> in this case)
arr.map<uint32>((x,i,arr)=>x+1)
Maps, or dictionaries, are collections that uniquely connects one value type to another. In TSWoW, we have decided to call these dictionaries to avoid confusing them with Maps in World of Warcraft.
Dictionaries are created with the special function CreateDictionary:
const myDictionary = { // <-- does not work (No call to CreateDictionary)
1: "value"
}
const myDictionary : = CreateDictionary<uint64,string>({ // <-- works!
1: "value1",
8: "value8"
});
Maps can currently only be iterated using callback functions:
const myDict : TSDictionary<uint64,string> = CreateDictionary<uint64,string>({
1: "value1",
2: "value2"
});
for(const key in myDict){} // <-- does not work
myDict.reduce((prev,key,value)=>p+key,0); // <-- works
myDict.filter((key,value)=>true); // <-- works
myDict.forEach((key,value)=>{}); // <-- works
Classes work mostly as usual. If a class does not extend anything else, they should extend TSClass:
class InnerClass extends TSClass {
innerValue: int;
constructor(innerValue: int) {
super();
this.innerValue = innerValue;
}
}
class TestClass extends TSClass {
a: int = 25;
inner: InnerClass;
constructor(innerValue: int) {
super();
this.inner = new InnerClass(innerValue);
}
}
function Main(events: TSEventHandlers) {
const cls = new TestClass(100);
// We can print a class using its stringify method
console.log(cls.stringify());
}
LiveScripts can also be written in C++ directly, it is however considered a more advanced feature of TSWoW, and a few special functions (GetObject, AddTimer) have slightly different syntax when written in C++. ORM classes are not supported in C++ at all.
If building scripts for the Lua backend, raw C++ script files are ignored completely and will not be loaded into the server. If you want to use both raw C++ and transpile some code to Lua, you have to use separate modules.
First, we create a header raw-file.h
void cpp_function();
Then, a corresponding cpp raw-file.cpp
#include <iostream>
void cpp_function()
{
std::cout << "Hello world from C++!" << "\n";
}
Then, we’ll need a type declaration file raw-file.d.ts
export declare function cpp_function(): void;
Finally, we can call this function from our main function (or any other TypeScript module).
import { cpp_function } from "./raw-file"
export function Main(events: TSEventHandlers) {
// will print the hello world message when script is reloaded
cpp_function();
}
Note: The main file of a project must always be a TypeScript file
Create a typescript file ts-file.ts
export function ts_function() {
console.log("Hello world from TypeScript!");
}
Then, from any c++ file as created above, simply do the following:
#include "ts-file.h"
// (if the file was in a subdirectory, the include should instead be #include "subdir/ts-file.h")
void some_function()
{
ts_function();
}
You can create a special CMakeLists.txt placed in your root livescripts directory to link external libraries. You do not need to set up the entire project in this file, it will be included after TSWoW has created a target named after your module (module named module-a has a target module-a ready when the file is loaded). Simply add any libraries or external headers to this file.
Note: Do not place external library files into the livescripts directory, since TSWoW will think it should compile them as part of the script itself.
Note: Remember that livescripts are completely unloaded from memory any time you rebuild them, but it’s your responsibility to handle heap allocations
Livescript TypeScript uses different conventions depending on what type it is, and may require including special headers. For example, user types are (currently) always wrapped in std::shared_ptr while TS* types are always sent as is. The string type is called TSString in C++.
To figure out how to accept an argument of a specific type, try writing a TypeScript function and look at the C++ the transpiler produces at livescripts/build/cpp/livescripts.