Scripting:Targeting

Target syntax

This page shows all the possible forms of value you can specify for a target type parameter. If you have used NVScript most of the possible forms will be familiar to you. Wherever possible I've tried to replicate the syntax used by NVScript for editor convenience.

Sometimes it may not make much sense to use a given targeting form, even if the script does not explicitly prohibit it. In general the script documentation will indicate which values are likely to be appropriate if it matters.

[me]

Targets the object the script is attached to.

[source]

All actions taken by scripts happen in response to messages received by the object the script is attached to. This option allows the script to target the object that sent the message that is currently being handled by the script. Note that this should be used with caution

objectid

Targets the object or archetype with the specified ID number.

name

Targets the object or archetype with the specified name.

*archetype

Targets all direct concrete descendants of the specified archetype. So, for example, *Chest will target all concrete Chest objects in your level, but not any concrete Safe, VicHopeChest, LC_Chest, or other indirect descendants of the Chest archetype.

@archetype

Targets all direct or indirect concrete descendants of the specified archetype. For example, @Chest will target all concrete Chest objects in your level and any concrete Safe, VicHopeChest, or other indirect descendants of the Chest archetype.

<distance:archetype or >distance:archetype

Targets all descendants of the specified archetype that are less than (< version) or greater than (> version) the specified distance from the script's host object. Distances are given in Dromed units, and may be decimal values. For example, <5.3:Chest will target all direct and indirect concrete descendants of the Chest archetype that are less than 5.3 Dromed units from the script host object. By default, all direct or indirect concrete descendants are targeted, however you can include * before the archetype name to restrict the targeting to direct descendants only, eg: <5.3:*Chest will target only concrete Chest objects within 5.3 Dromed units, not including concrete Safe, VicHopeChest or other indirect concrete descendants of Chest. Note that the distance is calculated in three dimensions (ie: location on the X, Y, and Z axes is included in the calculation).

&linkdef

Targets objects linked to the script host object based on the specified link definition. The syntax for the link definition is given in the next section.

Link definition syntax

The link definition syntax is complicated enough to need its own section! In its most simple form, you provide the name of a link and all objects linked to the host object by links of that type are targeted. However, that only scratches the surface of the possibilities.

&linktype

Objects linked to the script host object via links of the specified link type will be targeted. For example, &ControlDevice will target ControlDevice linked objects. By default all linked objects will be targeted, but that behaviour can be changed using the options discussed below.

A number of additional 'sigils' can be placed between the & and the linktype to provide more advanced features. In general the order in which sigils are specified does not matter, as long as they appear between the & and the linktype they will be picked up and acted upon, but some only make sense when combined with others.

Supported sigils

?

Including ? as a sigil turns on random selection mode. If this is specified then the the targeted object or objects will be chosen at random from the objects linked to the script host object by the specified link type. By default only a single object will be chosen at random, however this can be changed using the [] and ! sigils

%

Including the % sigil will restrict the objects targeted to archetypes only. For example, &%ScriptParams will only target archetypes linked to the script host object with ScriptParams links.

#

Effectively the inverse of the previous sigil, including the # sigil will restrict the objects targeted to concrete objects only. For example, &#ScriptParams will only target concrete objects linked to the script host object with ScriptParams links. Note that if both % and # appear in the link definition, the last specified one takes priority.

[count]

You can control the number of objects targeted by prefixing the link type with the desired maximum count in square brackets [ ]. If the specified count is larger than the number of linked objects, the number of objects targeted will be the number of linked objects. For example &[4]ControlDevice will target at most the first four objects linked to the script host object by ControlDevice links. If only two objects are linked by ControlDevice links, only those two objects will be targeted. The behaviour of this sigil depends on whether random (or weighted random) mode is enabled or not:

• If random and weighted random mode are not enabled, the order of the objects selected is based on the link IDs from the host object to the linked objects. If there are more linked objects than the specified count, this will always select the same subset of the linked objects.
• If random mode (but not weighted random mode) is enabled, the list of linked objects is shuffled into a random order and at most count objects are selected from that list. Objects will not appear more than once provided that they are only linked to the host object once.
• If weighted random mode is enabled, this will always target count randomly selected linked objects, potentially selecting the same object multiple times. In general you should avoid using [] in weighted random mode unless the script documentation indicates that doing so is safe/sensible/not likely to open a class 4 gate to the Sleeper's Pyramid on the Dead Plateau.

!

Target all linked objects. This is the default when random mode is off and [ ] has not been specified, and if ! and [ ] appear in the linkdef, ! will take priority. When random mode (but not weighted random mode) is enabled, ! will return all the linked objects in a random order, guaranteeing that each object only appears once provided that they are only linked to the host object once.

Weighted random mode

If linkdef is set to Weighted (ie: &Weighted) a special 'weighted random mode' is enabled. This mode looks at the ScriptParams links from the host object to other objects, and uses the script data set for the ScriptParams links to determine which links (and hence, which objects) are more likely to be selected than others when choosing at random. So, a link with data of 2 will be chosen twice as often as one with data of 1. If the data is not set for a ScriptParams link, or the data is not a number, its weight defaults to 1. The %, #, and [] sigils may be be used with weighted random mode, but ! is ignored (as it makes no sense in this situation) and ? is enabled implicitly.