Page Comparison

Introduction

In the old Warzone scripting (WZscript) system, two files were required:

• .slo – the main wz script
• .vlo – variable definitions

In Javascript, these are merged in to a single file:

• .js – variable definitions and your main script

Tip: You can also split your script in to several smaller scripts, and pull them in to a main script using include(). This can make working with large scripts much easier.

It is common for a script to deal with new or existing game components such as research topics, structures, unit bodies, propulsions, weapons etc. All these components are defined in appropriate text files like body.txt / body.ini, etc. In the old wzscript system, you had to define anything you wanted to use in the .vlo before you could use it in the .slo. In the new Javascript system, most Constants are pre-defined, and anything else (like a structure or component ID, etc) can simply be specified as a quoted string.

Note: If you are using the same value a lot, it's better to define a variable or constant and then use that throughout your script – see "Variables and Constants" section later.

Comments

There are two types of comments in Javascript:

// single line comment
var foo = "fish"; // can be put at end of lines
 
/* multi
line
comment */
 
var bar = /* can be put inside code */ "mammal";

Variables and Constants

Defining variables (read-write values) and constants (read-only values) is easy in Javascript:

var <name> = <value>; // a variable
 
const <name> = <value>; // a constant

The <value> can be any data type you want – Javascript data types are discussed later.

Variable names are written in camelCase and constant names are written in UPPER_CASE, just for convention so it's easier to know if something can be changed or if it's read-only without having to find the declaration.

Your variable and constant names should be unique. For example, don't define a variable called "foo" and then define a constant called "foo" - there can only be one thing called "foo" (...within a given Scope).

Here's an example of defining a variable (with a string value) and a constant (with an array of strings as its value):

var myPythonBody = "Body11ABT";
 
const MY_RESEARCH = [
	"R-Vehicle-Body11",
	"R-Vehicle-Prop-Tracks",
	"R-Vehicle-Prop-Hover"
];

You'll notice that you no longer need to define the data type like you did in .vlo and .slo files.

Some additional great information from Mozilla Developer Network: Values, Variables and Literals

Event/trigger concept

Like WZscript, the Javascript API is event-driven. However, there are some important differences between the way in which WZScript events work and the way Javascript events work.

WZScript events required you to define what would trigger the event, whereas most Javascript events have pre-defined triggers. So, let's start by looking at the way in which events are triggered (more detailed examples are shown later)...

To make things clearer, let's take a look at some example code...

Wait and Every equivalents

The queue() function is like the WZScript 'wait <time>' trigger:

// define our event handler, let's call it "foo"...
function foo() {
  // some code
}
 
// now let's queue that function to be run after 200ms...
queue("foo", 200);

The setTimer() is like the WZscript 'every, <time>' trigger:

// define our event handler, let's call it "bar"...
function bar() {
  // some code
}
 
// now let's set a timer to run bar() every 300ms...
setTimer("bar", 300);

So, in both cases, you create a function and then you use either queue() or setTimer() to call that function after a certain amount of time. You can specify some extra data to pass in to your function, for more information on that click the links to see full documentation for queue() and setTimer().

Callback equivalents

Javascript's callback system is much simpler than WZScript – all you need to do is create a function with a specific name.

Almost all Javascript callbacks have parameters – click on the links in the table below to get full details and examples...

WZScript callback	Javascript equivalent	Notes
CALL_GAMEINIT	eventGameInit()	The game has started.
CALL_DROIDDESIGNED	eventDesignCreated()	The player created a new droid design.
CALL_DROIDBUILT	eventDroidBuilt()	A new droid was built by a factory or created by a script.
CALL_NEWDROID
CALL_POWERGEN_BUILT	eventStructureBuilt()	A structure was built.
CALL_RESEX_BUILT
CALL_RESEARCH_BUILT
CALL_FACTORY_BUILT
CALL_MISSION_START	Not applicable	Javascript API doesn't currently have a concept of missions starting or ending.
CALL_MISSION_END
CALL_VIDEO_QUIT	eventVideoDone()	A video has finished playing.
CALL_LAUNCH_TRANSPORTER	eventLaunchTransporter()	The transporter "Launch" button was pressed.
CALL_START_NEXT_LEVEL	eventStartLevel()	A new level has started. (slightly different to WZscript meaning)
CALL_TRANSPORTER_REINFORCE	eventReinforcementsArrived()	A transport carrying reinforcements has arrived on the map.
CALL_MISSION_TIME	eventMissionTimeout()	The mission timer has reached 0.
CALL_ELECTRONIC_TAKEOVER	eventObjectTransfer()	An object is captured by Nexus link or transferred between allies.
CALL_UNITTAKEOVER
CALL_RESEARCHCOMPLETED	eventResearched()	A new technology has been researched.
CALL_STRUCT_ATTACKED	eventAttacked() eventAttackedUnthrottled()	Something was attacked.
CALL_DROID_ATTACKED
CALL_ATTACKED
CALL_TRANSPORTER_OFFMAP	eventTransporterExit()	A transport leaves the map.
CALL_TRANSPORTER_LANDED	eventTransporterLanded()	A transport lands.
CALL_BUILDLIST	Not yet implemented	The build list was opened.
CALL_BUILDGRID	Not yet implemented	A droid was ordered to build something.
CALL_RESEARCHLIST	Not yet implemented	The research list was opened.
CALL_MANURUN	Not yet implemented	New templates are available to manufacture.
CALL_MANULIST	Not yet implemented	The manufacture list was opened.
CALL_BUTTON_PRESSED	Not yet implemented	A button in the UI was pressed.
CALL_DESIGN_QUIT	Not yet implemented	The droid designer was closed.
CALL_OBJ_DESTROYED	eventDestroyed()	Something was destroyed.
CALL_DROID_DESTROYED
CALL_STRUCT_DESTROYED
CALL_FEATURE_DESTROYED
CALL_OBJ_SEEN	eventObjectSeen()	Sensors detected a new object.
CALL_DROID_SEEN
CALL_STRUCT_SEEN
CALL_NO_REINFORCEMENTS_LEFT	eventTransporterDone()	The player has transported all their remaining units from one map to another.
CALL_DESIGN_WEAPON	Not yet implemented	A weapon turret was selected in the droid designer.
CALL_DESIGN_SYSTEM	Not yet implemented	A systems turret was selected in the droid designer.
CALL_DESIGN_COMMAND	Not yet implemented	A command turret was selected in the droid designer.
CALL_DESIGN_BODY	Not yet implemented	A body was selected in the droid designer.
CALL_DESIGN_PROPULSION	Not yet implemented	A propulsion was selected in the droid designer.
CALL_ALL_ONSCREEN_DROIDS_SELECTED	eventSelectionChange()	The user selected one or more droids/structures.
CALL_PLAYERLEFT	eventPlayerLeft()	A player left the fame.
CALL_ALLIANCEOFFER	Not yet implemented	An alliance has been offered.

Expression equivalents

Javascript doesn't have expression triggers – instead, just put the expression in your function...

var readyToAttack = false;
 
function attackIfPossible() {
	if (readyToAttack) launchMyAttack();
}
 
setTimer("attackIfPossible", 5000);
 
function launchMyAttack() {
	// some code to make your stuff attack
 
	// and avoid attacking again until we have build some more droids
	readyToAttack = false;
}
 
function eventDroidBuilt() {
	readyToAttack = (enumDroid(me, DROID_WEAPON).length > 10);
	if (!readyToAttack) {
		// build another weapon droid!
	}
}

Ok, that's a really terrible way to decide when to attack, but it's just for illustration purposes.

The equivalent to the expression trigger is the attackIfPossible() function. We call it every 5 seconds (5000ms) using setTimer(). Each time it runs, it checks to see if we're ready to attack and, if we are, an attack will be launched.

But do you ever really need to do this? We could ditch attackIfPossible() function and it's timer, and just change the code inside eventDroidBuilt() so that it will launchMyAttack() if we've got more than 10 weapon droids. This would do just the same, with much less code:

function launchMyAttack() {
	// some code to make your stuff attack
}
 
function eventDroidBuilt() {
	if (enumDroid(me, DROID_WEAPON).length > 10) {
		launchMyAttack();
	} else {
		// build another weapon droid!
	}
}

There, much cleaner!

Init equivalent

Super simple – just use eventGameInit() 

Inactive equivalent

In Javascript API there isn't really a concept of an inactive event. If you don't want to use an event, don't create a function for it heh.

If you want to use an event, but only under certain conditions, well, that's a more noble cause! Here's how to do it:

// create the event function, but with a different name
function doStuff(victim, attacker) {
	// code
}
 
// let's activate it
eventAttacked = doStuff; // we're now listening to eventAttacked!
 
// and let's de-activate it:
delete eventAttacked;

Even more events...

The Javascript API has a load of other events not already discussed above. For a complete list and related documentation, see: Events & Timers.

Also, see Environment Sequences for some info on the order in which certain things happen.

Data types

Ok, before going any further I think we should take a look at the Javascript data types. The ones you'll use most are:

• Boolean
• String
• Number
• Object
• Array – I highly recommend you learn about the Iteration Methods of array objects – they will save you a lot of time and make your code cleaner and more reliable.

Click any of those links to see vast amounts of documentation about them on the awesome Mozilla Developer Network (one of the great advantages of switching to Javascript is that there's reams of great information available on the internet!).

There are others like Date and RegExp, but I doubt you'll have need for those.

Note that there's some things missing from the Javascript environment used by Warzone (at the time of writing this), such as iterators. For a list of what's currently available in the JS environment, check out Script Environment.

Warzone data types

The JS API has a bunch of well defined object types as follows (click links for more info):

Custom objects

Making your own objects in Javascript is really trivial:

var foo = {
   bar: "fish",
   baz: function() { return this.bar; }
}
 
console(foo.baz()); // "fish"

There's a bunch of advanced stuff you can do, such as adding getter/setter properties, hidden properties, read-only properties, etc., but that's beyond the scope of this article!

Expressions, Operators, Assignment

Everything you need to know is here: Expressions & Operators

Also, you need to understand what Falsey & Truthy are. 

If and Switch statements

If statements don't require much explanation...

if (a == b) {
  // do stuff
} else if (a == c) {
  // do stuff
} else {
  // do stuff
}

And switch statements are also pretty easy to use:

eventAttacked(victim, attacker) {
	switch (victim.type) {
		case DROID: console("Droid attacked!"); break;
		case STRUCTURE: console("Structure attacked"); break;
		case FEATURE: console("Feature attacked"); break;
		default: console("No idea what was attacked!!");
	}
}

Before using switch statements, do some background reading.

Looping: While, Do, For, etc...

There's loads of ways to loop in Javascript!

• do ... while
• for
• for ... in
• while

There's actually a few more, but those listed above are the most widely used.

Like I said earlier, I highly recommend you learn about the Iteration Methods of Array objects!!

Casts 

See: Data type conversion

Custom & Script functions

Or, as they're known in Javascript: Functions 

Note: You can't use the 'const' keyword inside functions (not in the current JS API anyway). Also, the 'let' keyword is not currently supported.

Javascript (as in the language) provides a vast array of it's own functions, usually as methods of objects though. You can see a list of some of the ones I use most here: Native JS Features.

And the JS API (as in the stuff Warzone adds to the environment) provides an insane number of awesome Functions that let you do just about anything!

Local variables

See: Scopes & Closures and Code sandboxing.

Macros

There's no concept of "macros" in Javascript – just use constants, variables or functions as applicable.

Script function externals

In the JS API, script function externals are called "globals". Here's a comparison between WZScript and Javascript globals...

WZscript external	Javascript global	Notes
mapWidth	mapWidth	The width of the map, in tiles.
mapHeight	mapHeight	The height of the map, in tiles.
gameInitialised	Not applciable	If you want to recreate this, use the following code: Code Block theme RDark language javascript linenumbers true function eventGameInit() { this.gameInitialised = true; }
selectedPlayer	selectedPlayer	The current id of the human player on the local machine.
gameTime	gameTime	The elapsed time since the game started, in milliseconds.
multiPlayerGameType	isMultiplayer	Is this an online multiplayer game?
multiPlayerMaxPlayers	maxPlayers	The number of player positions on the current map.
multiPlayerBaseType	baseType	The base type setting for the current game.
multiPlayerAlliancesType	alliancesType	The alliance mode for the current game.
scrollX	Not yet implemented	The x1 co-ordinate of the scroll region set by setScrollParams().
scrollY	Not yet implemented	The y1 co-ordinate of the scroll region set by setScrollParams().
scrollWidth	Not yet implemented	The width of the scroll region set by setScrollParams().
scrollHeight	Not yet implemented	The height of the scroll region set by setScrollParams().
cursorType	Not yet implemented	The current mouse pointer mode.
intMode	Not yet implemented	The current game mode (eg. design, intelligence, etc)
targetedObjectType	Not yet implemented	The type of object currently under the mouse pointer.
boolextraVictoryFlag	Not applicable	You can trigger gameOverMessage() from your script. Use your own variables if you want to keep track of game state.
boolextraFailFlag
GameLevel	difficulty	See Difficulty Levels for more information. Note, in JS API this property is read-only.

In Javascript, there are also several new globals:

• version – the Warzone version the script is running under
• mapName – the name of the map used for the current game
• powerType – the power type for the current game (derrick power per second before upgrades)
• scavengers – is the Scavenger Faction enabled?
• scavengerPlayer – the ID of the scavenger faction, or -1 if they are disabled
• me – the player ID that your script is running as
• scriptName – name of the script that is running (useful for include() files)
• groupSizes[] – an array defining size if each of your Groups
• playerData[] – an array of Player objects describing each player in the game (except scavengers)
• derrickPositions[] – an array of pre-placed derricks on the map
• startPositions[] – an array of player starting positions on the map

Big list of everything

For a big list of everything in the JS API, see Quick Reference 

Error Handling

See: Error Handling

Questions?

As you port from WZscript, you'll likely have questions - drop a comment below and i'll do my best to answer them!