Triggering events when looking at something: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
No edit summary
(Rewrite and extension)
Line 1: Line 1:
[[Category:Editing]]
''by Obsttortes; extended by Geep''
== Introduction ==
== 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, 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.  
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.
This article describes how to get entities to trigger events, if the player looks at them.


== The scriptobject ==
== The Scriptobject ==
 
The first thing you need is the scriptobject, which you can get [http://forums.thedarkmod.com/topic/14394-apples-and-peaches-obsttortes-mapping-and-scripting-thread/page__view__findpost__p__307416, here]. Put t in your script folder and include it by adding the line


The first thing you need is the latest version of the scriptobject, which is distributed within the TDM pk4 as
tdm_base01/script/trigger_look.script
Put this your script folder and include it by adding the line
   #include "script/trigger_look.script"
   #include "script/trigger_look.script"
in your tdm_custom_scripts.script file. If there is no such file, you have to create it.


In your tdm_custom_scripts.script file. If there is no such file, you have to create it.
== The Setup ==
 
== The setup ==


On the object you want to trigger an event, add the spawnarg "scriptobject" "trigger_look". That's it. If the player does look at it, it will trigger all it's targets.
On the object you want to trigger an event (let's call it a "shield" here), add the spawnarg
scriptobject     trigger_look
That's it. If the player does look at it, it will trigger all its targets.


== Additional Spawnargs ==
== Additional Spawnargs ==
Line 22: Line 24:
There are some additional spawnargs that can be used to control the behaviour of this object. They are all optional.
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)
* "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)
* "stim": the stim used to enable this object (default is PLAYER_STIM)
- "distance": how close the entity must be (default: 1024)
* "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)
* "tolerance": describes how exact the player (or another entity) must look (default: 0.1)
- "once": if set to one, the entity will trigger it's targets only once (default: 0)
* "once": if set to 1, the entity will trigger its targets only once (default: 0)
 
Interesting values of "tolerance" (which consider the x-y plane only) are
* 0 = direct look only
* 0.1 (default) = up to about 29 degrees from the direct-look axis (about 58 degrees total).
* 1 = up to 90 degrees from direct-look axis (180 degrees total)
* 2 = no directionality (360 degrees total)


== Remarks ==
== Remarks ==


There are two parts in the workflow of this object. The first part is the stim, that enables the object, the second one is the entity to react to. This must not be the same!
The algorithm differs depending on whether the viewer is:
* the player - is the shield seen, i.e., in the player's field of view?
* 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.)
 
== Looking at AI ==
 
This script should not be used as-is 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, merge trigger_look functions with the AI's script object. An example of such a merger script is given
[[http://forums.thedarkmod.com/applications/core/interface/file/attachment.php?id=14101 here]].
 
See also in the TMD distribution: tdm_base01/script/ai_trigger_look.script
 
Because of naming conflicts, instead of "tolerance" and "distance", you must specify these parameters (which have no defaults):
* tol_angle
* tol_distance
 
== How the Trigger_Look Script Works ==


While for the player the code checks, if he looks at it, for other entities it only checks wheter they are facing in the correct direction (in the x-y-plane).
There are two parts in the trigger_look workflow:
# the stim, that enables the object, set up in "init"
# the entity to react to.
These must not be the same!


The code does not check, if the entity can be really seen. So if the player for example looks at it trough a wall within the proper range, it will be activated, too. I plan to add this feature later on. In the meantime, you should adjust the distance spawnarg to get the desired effect.
The heart of the script is 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 [[https://youtu.be/5pnLZzrZTAo]].
 
Finally, the first vector is normalized to a unit vector, and the "angle" (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.
[[Category:Editing]]

Revision as of 00:54, 24 March 2020

by Obsttortes; 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 Scriptobject

The first thing you need is the latest version of the scriptobject, which is distributed within the TDM pk4 as

tdm_base01/script/trigger_look.script

Put this your script folder and include it by adding the line

 #include "script/trigger_look.script"

in your tdm_custom_scripts.script file. If there is no such file, you have to create it.

The Setup

On the object you want to trigger an event (let's call it a "shield" here), add the spawnarg

scriptobject     trigger_look

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)

Interesting values of "tolerance" (which consider the x-y plane only) are

  • 0 = direct look only
  • 0.1 (default) = up to about 29 degrees from the direct-look axis (about 58 degrees total).
  • 1 = up to 90 degrees from direct-look axis (180 degrees total)
  • 2 = no directionality (360 degrees total)

Remarks

The algorithm differs depending on whether the viewer is:

  • the player - is the shield seen, i.e., in the player's field of view?
  • 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.)

Looking at AI

This script should not be used as-is 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, merge trigger_look functions with the AI's script object. An example of such a merger script is given [here].

See also in the TMD distribution: tdm_base01/script/ai_trigger_look.script

Because of naming conflicts, instead of "tolerance" and "distance", you must specify these parameters (which have no defaults):

  • tol_angle
  • tol_distance

How the Trigger_Look Script Works

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.

These must not be the same!

The heart of the script is 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 [[1]].

Finally, the first vector is normalized to a unit vector, and the "angle" (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.