Request for playing a certain Theme at the desired intensity

Namespace: psai.net
Assembly: psaiCoreDotNet (in psaiCoreDotNet.dll) Version: 1.0.0.0 (1.0.0.0)

Syntax

C#
public PsaiResult TriggerMusicTheme(
	int themeId,
	float intensity
)

Parameters

themeId
Type: System..::..Int32
The id of the Theme to play
intensity
Type: System..::..Single
The initial intensity value. The valid range is between 0.0f and 1.0f.

Return Value

Type: PsaiResult
termdescription
"PsaiResult.OK if successful
"PsaiResult.initialization_errorpsai has not been initialized correctly. See psai.log for more information.
"PsaiResult.unknown_themethe requested Theme does not exist in the current soundtrack
"PsaiResult.commandIgnoredMenuModeActivethe command was ignored, call MenuModeLeave() first.

Remarks

Please note that there is a hierarchy among the different types of Themes, which will e.g. prevent a Base Mood from interrupting a Theme of type Action Event. Likewise, a Theme of type Shock Event will interrupt any other Theme that may be currently playing. Please refer to the psai Manual included in the psai SDK for a description of all the Theme Types and their playback priorities. The general interruption behaviour is as follows: If a Theme of a lower priority is currently playing when a new Theme is triggered, the psai soundtrack will play the newly triggered Theme immediately and quickly fade out the previous Theme. This way it is possible to build up a stack of interrupted Themes: A Base Mood may be interrupted by an Action Event, which is then interrupted by a Shock Event. When the intensity of the Shock Event has dropped to zero, psai will return to the Action Event, starting with the intensity level that was up at the time of its interruption. Likewise, when the intensity of the Action Event has reached zero intensity, psai will continue with the Basic Mood. If another Theme of the same priority is playing when a Theme has been triggered, psai will switch to the next Theme as soon as the Segment currently playing has reached its end. This can only work if there is at least one Segment in the newly triggered Theme, that has been marked within the psai® Editor as a compatible follower to the Segment currently playing. Please refer to the psai® Editor documentation for more information about Segment compatibilites. If the newly triggered Theme is the very same Theme that is currently playing, psai will set the internal Intensity level to the Intensity-argument of the new trigger-call. Thus, triggering the same Theme over and over again will not result in an accumulation of the triggered intensity values. Please see the 'Intensity'-section of the psai Manual for more information about psai's Intensity concept. If a Theme of type Basic Mood is triggered while a Theme of higher priority is playing, psai will internally store the triggered Basic Mood as the one to switch to, when the Intensity level of all stacked Themes has dropped to zero. All other trigger-calls to Themes of lower priority are ignored completely. The Theme will be playing for a timespan as defined by the member "music duration" within the psai Editor. The intensity falloff rate will be automatically adjusted to reach zero accordingly. To manually override this setting, call the overloaded version of TriggerMusicTheme() with the additional musicDuration parameter. Troubleshooting: If the soundtrack does not react as expected, please check your 'psai.log' file in your '[current user]/Documents/psai' folder to see what happened, and check back with your composer to make sure that the Types of the affected Themes have been assigned correctly within the psai Editor authoring software.

See Also