Script objects: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
m (tweak spacing)
(→‎tdm_light_holder: From what I can see, only STIM_TRIGGER is actually processed by tdm_light_holder)
 
(6 intermediate revisions by 3 users not shown)
Line 3: Line 3:
A '''script object''' is an object that is written in the idTech4 scripting language, and an be attached to arbitrary entities. Each entity can have '''only one''' script object, but one script object can be attached to multiple entities.
A '''script object''' is an object that is written in the idTech4 scripting language, and an be attached to arbitrary entities. Each entity can have '''only one''' script object, but one script object can be attached to multiple entities.


To use a script object on an entity, give it the spawnarg '''script_object''' set to the name of the script object. For your convience, TDM already contains a few useful script objects, here is a list:
To use a script object on an entity, give it the spawnarg '''scriptobject''' set to the name of the script object. For your convience, TDM already contains a few useful script objects, here is a list:


== List of script objects ==
== List of script objects ==
Line 23: Line 23:


<pre>
<pre>
  "script_object" "tdm_suicide"
  "scriptobject" "tdm_suicide"
  "remove_delay"  "100"              // remove this entity 100 seconds after spawning it
  "remove_delay"  "100"              // remove this entity 100 seconds after spawning it
</pre>
</pre>
Line 29: Line 29:
Note: In TDM v1.03 the delay '''must be''' >= 1, or the script will wait 360 seconds. In TDM v1.04, the time can also be between 0 and 1 second, for instance 0.5 seconds.
Note: In TDM v1.03 the delay '''must be''' >= 1, or the script will wait 360 seconds. In TDM v1.04, the time can also be between 0 and 1 second, for instance 0.5 seconds.


Note #3: From TDM v1.04 onwards, any entity with this script object will activate its targets right before it removes itself. This can be used to trigger things ater a certain time from map start has passed, and is used f.i. by the new "atdm:vanishing_platform" entity.
Note #3: From TDM v1.04 onwards, any entity with this script object will activate its targets right before it removes itself. This can be used to trigger things after a certain time from map start has passed, and is used f.i. by the new "atdm:vanishing_platform" entity.




Line 35: Line 35:


<pre>
<pre>
  "script_object" "tdm_light_holder"
  "scriptobject" "tdm_light_holder"
  "extinguished"  "1"                // the light starts off, but can be lit by the player
  "extinguished"  "1"                // the light starts off, but can be lit by the player
</pre>
</pre>
Line 41: Line 41:
This is typical attached to either lights (an electrical lamp f.i.) or light holders (a candle holder with attached candle + flame, or a torch with attached flame). This script object has handy methods to toggle all lights that this holder has, regardless how many (multiple flames?) or where (flame on holder or flame on candle on holder?).
This is typical attached to either lights (an electrical lamp f.i.) or light holders (a candle holder with attached candle + flame, or a torch with attached flame). This script object has handy methods to toggle all lights that this holder has, regardless how many (multiple flames?) or where (flame on holder or flame on candle on holder?).


This script object also makes the entity react to stims (f.i. fire, water and gas), and/or triggers like when you link a button/lever/trigger to this entity.
This script object also makes the entity react to triggers like when you link a button/lever/trigger to this entity.


(See also the light_ext and light_moving_ext scriptobjects, used by extinguishable light sources to respond to fire/water/gas stims.)


=== tdm_gui_message ===
=== tdm_gui_message ===


This script object is attached to an atdm:target_message entity, and the entity shows a message to the player, based on cvars and spawnargs. You can use this script object for the "popup" messages that appear on the upper left corner (f.i. to give the player hints) or for screeen overlays like in a movie, where it says f.i. "Random Town, past midnight". Where the message appears and how it looks is entirely customizable by using a different gui.
This script object is attached to an '''atdm:gui_message''' entity, and the entity shows a message to the player, based on cvars and spawnargs. You can use this script object for the "popup" messages that appear on the upper left corner (f.i. to give the player hints) or for screeen overlays like in a movie, where it says f.i. "Random Town, past midnight". Where the message appears and how it looks is entirely customizable by using a different gui.
 
See [[Popup messages]] for more information.


==== CVARs ====
==== CVARs ====


* '''tdm_show_trainer_messages''' - if true, the messages are shown, if false, suppressed
* '''tdm_show_trainer_messages''' - if true, trainer messages are shown, if false, suppressed


==== Spawnargs ====
==== Spawnargs ====
Line 58: Line 61:
* '''lines''' - Number of lines the text has
* '''lines''' - Number of lines the text has
* '''text''' - The text to be shown on the message.
* '''text''' - The text to be shown on the message.
* '''gui''' - Name of the GUI file, defaults to ''guis/message.gui''
* '''gui''' - Name of the GUI file, defaults to ''guis/tdm_message.gui''
* '''wait''', '''delay''' - These two are inherited from '''atdm:target_callobjectfunction''' and set the "wait" between triggers and the initial "delay" before the messsage show.
* '''wait''', '''delay''' - These two are inherited from '''atdm:target_callobjectfunction''' and set the "wait" between triggers and the initial "delay" before the messsage show.
* '''fade_out_time''' - Defaults to 1, in seconds. This time is waited for the GUI to fade out, then the message is forcefully removed. If you use a different gui with "gui", then set this spawnarg to match the fadeout time of your gui.
* '''fade_out_time''' - Defaults to 1, in seconds. This time is waited for the GUI to fade out, then the message is forcefully removed. If you use a different gui with "gui", then set this spawnarg to match the fadeout time of your gui.
Line 72: Line 75:
=== tdm_voice ===
=== tdm_voice ===


A script object for atdm:voice, which can play voices (or any other sounds) so they appear to come from the player. Can be used for voice overs and speaker-from-off effects. Both effects use the volume in two different CVARs, so their volume can be controlled separately.  
A script object for atdm:voice, which can play voices (or any other sounds) so they appear to come from the player. Can be used for voiceovers and narrator effects. These effects use separate volumes defined by two different CVARs.  


How to use:
How to use:


# Place an '''atdm:voice''' entity in your map (location does not matter, and you need only one)
# Place an '''atdm:voice''' entity (in '''Sound''' folder) in your map (location does not matter, and you need only one)
# Place multiple '''atdm:voice_trigger''' entities in your map
# Place multiple '''atdm:voice_trigger''' entities (in '''Targets''' folder) in your map
# link your '''atdm:voice_trigger''' entities to '''your atdm:voice''' entity ({{key|CTRL}}+{{key|K}} in [[DarkRadiant]])
# Link your '''atdm:voice_trigger''' entities to your '''atdm:voice''' entity ({{key|CTRL}}+{{key|K}} in [[DarkRadiant]])


Give the following spawnargs to the '''atdm:voice_trigger''' entities:
Give the following spawnargs to the '''atdm:voice_trigger''' entities:
Line 85: Line 88:
"snd_say"    "sound_you_want_to_play"                      // generic, male or female
"snd_say"    "sound_you_want_to_play"                      // generic, male or female
"as_player"  "1"                                            // if the player should say things
"as_player"  "1"                                            // if the player should say things
"as_player"  "0"                                            // if the speaker (from off) should say things
"as_player"  "0"                                            // if the narrator should say things
</pre>
</pre>


The difference between "as_player" "0" and "1" is the volume as set in the menu.
When "as_player" is set to "1", the sound volume is controlled by the "Player Voice Volume" slider in the TDM Audio menu.


When "as_player" is set to "0", the sound volume is controlled by the "Narrator Volume" slider in the TDM Audio menu.
==== CVARS ====
==== CVARS ====


* tdm_voice_player_volume
* tdm_voice_player_volume // Player Voice Volume
* tdm_voice_from_off_volume
* tdm_voice_from_off_volume // Narrator Volume
* Menu settings


'''Unsupported''' options (taken out because the team doesn't want to add them):
'''Unsupported''' options (taken out because the team doesn't want to add them):
Line 99: Line 104:
* CVAR: tdm_player_is_female
* CVAR: tdm_player_is_female
* Spawnarg: "snd_say_female" "female_sound_you_want_to_play" // overrides snd_say if the player is female
* Spawnarg: "snd_say_female" "female_sound_you_want_to_play" // overrides snd_say if the player is female
* Menu settings (the sliders were taken out of the audio menu)


== See also ==
== See also ==

Latest revision as of 17:04, 9 September 2019

Introduction

A script object is an object that is written in the idTech4 scripting language, and an be attached to arbitrary entities. Each entity can have only one script object, but one script object can be attached to multiple entities.

To use a script object on an entity, give it the spawnarg scriptobject set to the name of the script object. For your convience, TDM already contains a few useful script objects, here is a list:

List of script objects

tdm_alarm

A script object that sounds an alarm sound that can be heard by AI as suspicious sound, as well as a player audible sound.

Functions:

   void    start_alarm();
   void    stop_alarm();

See atdm:alarm_sound on how to use it.


tdm_suicide

 "scriptobject" "tdm_suicide"
 "remove_delay"  "100"              // remove this entity 100 seconds after spawning it

Note: In TDM v1.03 the delay must be >= 1, or the script will wait 360 seconds. In TDM v1.04, the time can also be between 0 and 1 second, for instance 0.5 seconds.

Note #3: From TDM v1.04 onwards, any entity with this script object will activate its targets right before it removes itself. This can be used to trigger things after a certain time from map start has passed, and is used f.i. by the new "atdm:vanishing_platform" entity.


tdm_light_holder

 "scriptobject" "tdm_light_holder"
 "extinguished"  "1"                // the light starts off, but can be lit by the player

This is typical attached to either lights (an electrical lamp f.i.) or light holders (a candle holder with attached candle + flame, or a torch with attached flame). This script object has handy methods to toggle all lights that this holder has, regardless how many (multiple flames?) or where (flame on holder or flame on candle on holder?).

This script object also makes the entity react to triggers like when you link a button/lever/trigger to this entity.

(See also the light_ext and light_moving_ext scriptobjects, used by extinguishable light sources to respond to fire/water/gas stims.)

tdm_gui_message

This script object is attached to an atdm:gui_message entity, and the entity shows a message to the player, based on cvars and spawnargs. You can use this script object for the "popup" messages that appear on the upper left corner (f.i. to give the player hints) or for screeen overlays like in a movie, where it says f.i. "Random Town, past midnight". Where the message appears and how it looks is entirely customizable by using a different gui.

See Popup messages for more information.

CVARs

  • tdm_show_trainer_messages - if true, trainer messages are shown, if false, suppressed

Spawnargs

  • show- The time in seconds the message is shown, will be longer by approx. one second to fade the message out. If set to 0, shows the message for 6 seconds plus 1s fade out.
  • lines - Number of lines the text has
  • text - The text to be shown on the message.
  • gui - Name of the GUI file, defaults to guis/tdm_message.gui
  • wait, delay - These two are inherited from atdm:target_callobjectfunction and set the "wait" between triggers and the initial "delay" before the messsage show.
  • fade_out_time - Defaults to 1, in seconds. This time is waited for the GUI to fade out, then the message is forcefully removed. If you use a different gui with "gui", then set this spawnarg to match the fadeout time of your gui.
  • auto_trigger - Boolean, if true, the msg is triggered "delay" seconds after map load automatically.
  • force - Boolean, if true, the msg is always shown, regardless of the menu setting (e.g. the CVAR).

Notes

  1. Currently messages just overlay each other on the screen. So if a later messages is displayed while an old message is still there, they fade over from the old one to the new one.
  2. If the player then steps back into the first trigger, the old message is not displayed again, because it is still waiting around.


tdm_voice

A script object for atdm:voice, which can play voices (or any other sounds) so they appear to come from the player. Can be used for voiceovers and narrator effects. These effects use separate volumes defined by two different CVARs.

How to use:

  1. Place an atdm:voice entity (in Sound folder) in your map (location does not matter, and you need only one)
  2. Place multiple atdm:voice_trigger entities (in Targets folder) in your map
  3. Link your atdm:voice_trigger entities to your atdm:voice entity (CTRL+K in DarkRadiant)

Give the following spawnargs to the atdm:voice_trigger entities:

"snd_say"    "sound_you_want_to_play"                       // generic, male or female
"as_player"  "1"                                            // if the player should say things
"as_player"  "0"                                            // if the narrator should say things

When "as_player" is set to "1", the sound volume is controlled by the "Player Voice Volume" slider in the TDM Audio menu.

When "as_player" is set to "0", the sound volume is controlled by the "Narrator Volume" slider in the TDM Audio menu.

CVARS

  • tdm_voice_player_volume // Player Voice Volume
  • tdm_voice_from_off_volume // Narrator Volume
  • Menu settings

Unsupported options (taken out because the team doesn't want to add them):

  • CVAR: tdm_player_is_female
  • Spawnarg: "snd_say_female" "female_sound_you_want_to_play" // overrides snd_say if the player is female

See also