Script objects

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

• Writing script objects