Other great resources: Official JS API docs, Scripting Forum
Labels
What are labels?
A label is a string that can be associated with an object, and later used to retrieve that object:
- A label can only be associated with one object at a time
- An object can have multiple labels at the same time
They are mostly used to provide named references for map-placed objects, such as structures and areas, so that scripts can retrieve them without needing to use hard-coded object or co-ordinate references.
You can inspect labels in the Javascript Debugger.
Which objects can be labelled?
You can label any of the Warzone Objects, with the exception of Data objects:
Notes:
- When a Game object gets destroyed its associated label is removed.
- Location objects are removed when they no longer have any labels associated with them.
- Apparently, groups can be labelled as well.
How do I create labels?
There are three ways to create labels:
- Use a map editor, like FlaME, to define and label objects (the labels are stored in labels.ini)
- Define them manually in the labels.ini file associated with a map – remember to specify the "label" property!
- Create a custom location object in a script and use addLabel() to label it
There are discussions taking place in the forums and also a wiki page that propose possible naming conventions for labels.
Are they private to my script?
No. And this is perhaps the most important thing to understand when using labels.
Labels are shared between all scripts running on the same machine, but are not syncrhonised with network peers.
This is particularly important on the game host where there are a large number of scripts running.
As such, it's recommended that any labels you create using the addLabel() function should be prefixed or suffixed with the value of 'me' to reduce the chances of other scripts overwriting them.
Are they persistent?
Labels are stored in save games, and will be restored when the save game is loaded.
Labels defined in a map (labels.ini) can be changed at runtime, by assigning those labels to some other object or removing them, and those changes will persist in save games, but the map will not be altered. So, if you start a new game, the original labels from the map will be reinstated.
Availability 3.1 B2+
Requires:
- Warzone 3.1 Beta 2 or above
- Warzone 3.2 or above recommended
The majority of label features were added or improved in Warzone 3.2
Contents
Jump to:
Scripting: Labels
Related Objects:
Create them:
- addLabel() – label an object
List them:
- getLabel() – get first label associated with a specific object
- enumLabels() – get a list of all labels
Retrieve their objects:
- getObject() – get object associated with a label
- label() – use this instead on WZ 3.1
Monitor them:
- eventArea<Label>() – triggered when a droid enters a labelled Area object
- resetArea() – reset or filter an area trigger
Remove them:
- removeLabel() – remove a label