Triggering events when looking at something

by Obsttortes; updated and extended by Geep

Introduction

Triggering events in games is a nice feature that can be used to drive the story forwards or to create tension. There are already several possibilities for how events can be triggered in DarkRadiant. The most common ones are the player entering a specific area, taking an object, or fulfilling an objective.

This article describes how to get entities to trigger events, if the player looks at them.

The Setup

Deploying the trigger_look Scriptobject for non-AI Entities

The following includes configuration for both AI and non-AI entities. This section is primarily for non-AI entities. See further down for more about looking at AI entities.

On the object you want to trigger an event (let's call it here a "seen-object" or as a more specific example, a "shield"), add the spawnarg

scriptobject     trigger_look    # non-AI entities
scriptobject     ai_trigger_look # AI entities

You must also do the following:

• create a folder called 'script' in your FM directory
• within that script folder, create a file called tdm_custom_scripts.script
• add the following to the file:

#include "script/trigger_look.script"    # for non-AI entities
#include "script/ai_trigger_look.script" # for AI entities

That's it. If the player does look at it, it will trigger all its targets.

Additional Spawnargs

There are some additional spawnargs that can be used to control the behaviour of this object. They are all optional.

• "entityname": The entity to react to (default is player1, thus meaning the player)
• "stim": the stim used to enable this object (default is PLAYER_STIM)
• "distance": how close the entity must be, i.e., maximum distance (default: 1024)
• "tolerance": describes how exact the player (or another entity) must look (default: 0.1)
• "once": if set to 1, the entity will trigger its targets only once (default: 0)

Remarks

If you fill in "entityname", be sure it is not the same value as "name" of the seen-object.

Interesting values of "tolerance" (speaking in terms of the x-y plane only) are

• 0 = direct look only, like a rifle bore
• 0.1 (default) = up to about 26 degrees from the direct-look axis (about 52 degrees total)
• 1 = up to 90 degrees from direct-look axis (180 degrees total)
• 2 = no directionality (360 degrees total)

In practice, values very close to zero or greater than 1 are unlikely to be useful. To calculate a tolerance value for a particular angle theta (which is half the total viewing angle):

tolerance = 1 - cos(theta)

The algorithm differs depending on who the triggering viewer is:

• The Player - is the shield seen, i.e., in the player's field of view (assuming the given tolerance)?
• Another Entity - only checks whether it is facing in the correct direction (in the x-y-plane).

No check is made if the shield can be really seen. So if the player, for example, looks at it through a wall within the proper range, it will be activated, too. (Possibly this can be improved in the future. In the meantime, you should adjust the distance spawnarg to get the desired effect.)

Deploying the ai_trigger_look Scriptobject for Looking at AI Entities

trigger_look should not be used to look at an AI, because the AI will have a scriptobject already. If you override it with trigger_look, then the AI behavior fails. Instead, use the ai_trigger_look script object which merges trigger_look functions with the AI's script object. This can be set up in the same manner as trigger_look, just substitute 'ai_trigger_look' for 'trigger_look' in the setup steps above. The ai_trigger_look script can be found in tdm_base01/script/ai_trigger_look.script.

Because of naming conflicts, you must specify these parameters as spawnargs on the AI entity (which have no defaults):

• tol_angle (akin to 'tolerance' in trigger_look)
• tol_distance (akin to 'distance' in trigger_look)

How the Trigger_Look Scriptobject Works

The scriptobject is distributed within the TDM pk4 as

tdm_base01/script/trigger_look.script

(Any FM that used trigger_look before it was part of the standard distribution will have a copy in the FM's script folder as well as the line

 #include "script/trigger_look.script"

in its script/tdm_custom_scripts.script file.)

When you open the script with a text editor, you will see that there are two parts in the trigger_look workflow:

1. the stim, that enables the object, set up in "init"
2. the entity to react to.

The heart of the script is the second part, the "processStim" function. It identifies the "inflictor", e.g. player1, and the object to be seen, e.g., a "shield", and by subtraction of their origins finds the vector from inflictor to seen-object. For a player-inflictor, the vector is adjusted in z to be "from the eyes" instead of from the origin "at the feet".

If the length of that vector exceeds the "distance" parameter, nothing will be triggered.

Otherwise, the unit vector in the direction of the inflictor's view is retrieved. A function call gives this in terms of Euler angles. This is then converted to a direct unit vector, representing the "forward" view (and ignoring the "right" and "up" vectors). For a fuller explanation of the mathematics, see the video Trigger_look Explained.

Finally, the first vector is normalized to a unit vector, and the "angle" variable (which is actually the cosine of the angle) between those 2 unit vectors is calculated. This is compared to "eps" (short for epsilon) which is 1 minus "tolerance", for triggering.

See Also

Obsttortes Forum Thread about this.