Audiograph

Audiograph

This article documents the audiograph, which will be available from 2.11 onwards. You can download it from here if you want to use it before 2.11 is released: https://forums.thedarkmod.com/index.php?/topic/20475-dragofers-scripting/

The audiograph is an Inventor's Guild device for playing back recordings stored on spindles. It offers the following features:

• Every audiograph can load and unload any spindle, a metal cylinder the player can carry in his inventory.
• Spindles are loaded by frobbing or using an audiograph while the player has a spindle selected in his inventory.
• To start or stop playing the recording, frob the audiograph or trigger it from i.e. a lever.
• Audiographs can target a spindle to automatically load it at map start. If the "start_on" spawnarg is set it will play the recording.
• AIs can be alerted if an audiograph plays certain recordings.
• The spindle's targets can be triggered at the end of a recording (non-looping sounds only).

Basic setup

There are 2 types of entities you need to place in your map, both in the entity folder "Static/Mechanical":

• atdm:audiograph - this is the sound player.
• atdm:audiograph_spindle - this can store one soundshader, set in the "snd_audiograph" spawnarg.

To start the map with a spindle already loaded into an audiograph, let the audiograph target a spindle. Set "start_on" if you want the audiograph to automatically start playing the sound, too.

For looping soundshaders you can set the "loop" spawnarg on the spindle to determine whether the audiograph will switch off after one cycle or continue playing indefinitely. Note that you also need the "looping" keyword in the soundshader definition.

Usage

There are 2 steps to using an audiograph:

• Loading a spindle: this is done by selecting a spindle in the inventory, then either frobbing the audiograph or pressing the "use" key while the audiograph is frob-highlighted.
• Activating the audiograph: when a spindle is loaded, the recording can be started or stopped by frobbing the audiograph. You can also trigger it from i.e. a button, lever or script.

A spindle is unloaded by frobbing the spindle that's attached to the audiograph.

Triggering targets at the end of a recording

The targets of the spindle will be triggered if an audiograph finishes playing it, if the spindle is not set to loop (spawnarg "loop" "0").

Alerting AIs

By default, playing a recording will alert nearby AIs up to around 300 units away if there's no closed door in the way. They may still hear it through a closed door if both the AI and the audiograph are very close to the door. This is completely independent of what the player actually hears and is controlled via the following spawnargs on each spindle:

• sprS_propagate (default "yell") - this is a sound propagation preset for how far and how loud this sound can be heard by AIs. You can find more presets in the "Create Entity" menu with the prefix "sprGS_", keeping in mind that the prefix should be left aside when setting a new spawnarg value. To stop AIs from reacting to the recording, set this spawnarg to "-".
• propagate_modifier (default -10) - this spawnarg adjusts the volume in dB of the sound as heard by AIs, which also affects the radius.

Scripting

There are no script events specific to the audiograph, but you can access script functions and variables that are inside the "audiograph" scriptobject. To begin, you need to create a special type of entity variable named after the "audiograph" scriptobject and assign the audiograph to it:

audiograph aud = $atdm_audiograph_1;

The following variables are available:

is_loaded //whether a spindle is loaded into this audiograph, 0 or 1
is_playing //whether the audiograph is playing the spindle, 0 or 1
spindle //the currently loaded spindle entity

The following script functions are suitable for use by external scripts:

load_spindle() //if the player has a spindle selected in his inventory, it will be loaded into the audiograph
toggle_audiograph() //if a spindle is loaded, the audiograph will either start or stop playing it
return_spindle() //the currently loaded spindle will be given to the player

Example script to cause an audiograph to start playing a sound if it's loaded with a spindle and isn't already playing it:

void start_audiograph()
{
	audiograph aud = $atdm_audiograph_1;

	if( aud.is_loaded && !aud.is_playing )
	{
		aud.toggle_audiograph();
	}
}