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, which are small metal cylinders the player can pick up and store in his inventory. It offers the following features:

• Every audiograph can load, unload and play any spindle.
• 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.

Sounds

The following spawnargs are available for setting sounds, on the spindle and audiograph respectively:

• snd_audiograph (spindle): the main sound you want the recording to play.
• snd_noise (spindle): an additional layer of background noise to be played together with the recording. It can be disabled by setting to "silence" or "nosound".
• snd_switch_on (audiograph): sound made when starting a recording. The recording will start after this sound finishes.
• snd_switch_off (audiograph): sound made when a recording ends.
• snd_load (audiograph): sound made when loading a spindle onto the audiograph.
• snd_unload (audiograph): sound made when unloading a spindle from the audiograph. Note that this will play simultaneously with "snd_acquire" on the spindle.

Triggering targets at the end of a recording

By default the targets of the spindle will be triggered if an audiograph finishes playing it, as long as the spindle is not set to loop (spawnarg "loop" "0"). The following spawnargs for the spindle offer more control over this behaviour:

• trigger_max: Maximum number of times this spindle is allowed to trigger its targets after the recording finishes playing.
• trigger_from: Only trigger the spindle's targets if the spindle is played from the audiograph specified in this spawnarg. More audiographs can be specified in additional spawnargs i.e. trigger_from2.

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:

float is_loaded //whether a spindle is loaded into this audiograph, 0 or 1
float is_playing //whether the audiograph is playing the spindle, 0 or 1
entity spindle //the currently loaded spindle entity
Furthermore, the number of times a spindle has triggered its targets is stored as a "trigger_num" spawnarg on the spindle itself.

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

load_spindle( entity e ) //attempts to load the specified entity into the audiograph. Will do nothing if the entity is not in the inventory category "Recordings" or the audiograph is already loaded.
return_spindle( float return_to_inv ) //the currently loaded spindle will be unloaded and either given to the player or reappear where it was picked up, depending on the value of return_to_inv.

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 )
	{
		sys.trigger(aud);
	}
}