Music System

Overview

This page contains documentation about the Music System of CryENGINE and its subsystems.

Music System

Generally spoken the Music System as a whole consists of three parts:

The Music System plays back music.
The Music Logic automatically changes the music, depending on certain game inputs.
The Music Editor located in The DataBase View tab of the Editor specifies which music to play.

Music System

The Music System loads the theme description and can play a theme, switch to moods, or play individual patterns by name. It's a bit like a CD player where you press start and select the track. It cannot differentiate based on the semantic meaning of moods or themes. The code for the Music System is located in the CrySoundSystem project.

Music Logic

Music Logic is a game-dependent module that can have several inputs to change its internal state. Those Music Signals are manually placed within game code with a single line of code. The signals drive points of input which are processed by the Music Logic code. and passed on to the MusicLogicGraph. By traversing along the MusicLogicGraph, the Music System receives commands to change themes or moods. The Music Logic needs to be activated by one of the triggers described below. When activated, the Music System should not be used by any other code or scripted events. The MusicLogicControl FlowGraph node can change input values and activate or deactivate the Music Logic.

Music Editor

To enable music in a level, the music database must be opened from the DataBase View while a level is open. As soon as the level is saved with the database attached, it will require the music database as a dependency. Thus, you will always have a specified list of music to choose from in a specific level. Press the icon to unload a music library file and saving the level will disassociate the music database from the level. A level can not associate more than one library file.

In the screenshot above, SDK_Music in the drop-down menu refers to the Game\Music\SDK_Music.xml file.
There are three ways to play music in CryENGINE:

Use the MusicPlayPattern script or LUA script to play a pattern by calling a single pattern by its unique name.
Set a theme and change the active moods with the Flow Graph editor, LUA, or area shapes script.
Set a theme and then turn on Music Logic. This will select and change to the mood that fits best.

The theme or mood entities can be connected to an area shape or directly triggered through Flow Graphs. Whenever the player is in the area shape, the attached music theme will play interactively.

Music Logic is an automatic system, determining the intensity of a game situation through different inputs, such as player fire, injury, or explosions. Depending on the intensity value, themes may play differently. Music Logic is triggered either by Flow Graph as described below or by script (MusicLogic.StartLogic()).

Music Entities

Music Entities are small LUA scripts that provide special functionality for music. There are currently six entities for music. For more information on Music Entities, please see the Sound Entities (deprecated) reference document.

Controlling Music with the Flow Graph

All already existing music FG nodes have been moved to the new "Music" option under "Add Node" so that all music related nodes are grouped there and the remaining dialog and general sound nodes under "Sound". We have added a bunch of new Music Nodes to make controlling music through FG even more powerful. The music entities listed above can all be triggered in the Flow Graph. Music Logic can be enabled and modified there as well. A robust, adaptive musical score can be created, particularly when used in combination with game tokens as triggers. Additionally to the already increased overall usability the biggest improvement is the availability of drop-down lists to choose from loaded Themes/Moods and MusicSystem behavioral options without the need of the designer to manually copy and paste stuff.

Music:LogicControl Node

The MusicLogicControl node is used to turn Music Logic on or off. It can also be used to add values to the Logic to bump or force the Music Logic into a different state. For just enabling/disabling the ML use the Music:LogicTrigger node instead.

Port	Description
Enable and Disable	Standard ports to turn the node on or off.
Preset	Select a preset for the music logic
Start MusicLogic	When this port is triggered, the logic is on.
Stop MusicLogic	When this port is triggered, the logic is off.
Set all values	Sending a numeric value to this port sets the value of all the intensities (AI, Game, and Player Intensity) to the specified value.
Add all values	Sending a numeric value to this port adds the specified value to all the intensities (AI, Game, and Player Intensity). Values can be sent to the individual intensity measures by using the same method as Set all values and Add all values.
Set Allow-Change	When Allow-Change is high enough, it can override the time delay associated with the current mood, forcing it to switch moods at the next fade point. This port accepts a numeric value.
Add Allow-Change	When Allow-Change is high enough, it can override the time delay associated with the current mood, forcing it to switch moods at the next fade point. It is similar to Set Allow-Change, but the input value is added to the current value.
Set Multiplier	By default, this value is one. Changing this number to less than one will create a less responsive system, which is also less likely to jump to higher levels of intensity. Giving it a value greater than one will make MusicLogic respond more quickly, and will also make it more likely to jump to higher levels of intensity.
Set AI Multiplier	By default, this value is one. This behaves similar to Set Multiplier, but affects only the AI intensity, which is a measure of how many AI enemies are there, as also how close they are to the player.

Music:LogicTrigger Node

Allows for enabling and disabling the MusicLogic with the defines preset as well as querying for its status.

Port	Description
Preset	Select a preset for the music logic
Start	When this port is triggered, the logic is on.
Stop	When this port is triggered, the logic is off.
Check	Checks if the ML is currently on or off and triggers the respective output.
Started	Outputs when the ML gets enabled from this node or a check is performed and the ML is on.
Stopped	Outputs when the ML gets disabled from this node or a check is performed and the ML is off.

Music:ThemeSelector Node

Allows for playing the selected Theme and Mood as well as providing valuable status information.

Port	Description
Play	Starts the selected Theme/Mood
ThemeAndMood	Defines the Theme and Mood
DelayInSeconds	Defines a delay it takes to start the Theme/Mood after the Play input was triggered
KeepPreviousMood	Defines if the mood from the previous theme should be kept. This overrides the mood of the current selection and only changes the theme.
Started	Outputs when the Theme/Mood starts
LoopCount	Outputs the current number of how often the mood looped (only works as long as the mood doesn’t change)
Progress	Outputs the current progress (0 to 1) (only works as long as the mood doesn’t change)
Time	Outputs the elapsed time in seconds (only works as long as the mood doesn’t change)
TimeRemaining	Outputs the remaining time in seconds (only works as long as the mood doesn’t change)

Music:MoodSelector Node

Allows for manipulation of the currently played Mood within a Theme. Theme and Mood are selectable via a drop-down list. Allows for easy switching up and down the available Moods and providing valuable status information.

PlayStart defines if the moods Start Layer should be used if available.

If PlaySynced is true, the new mood continues at the same progress as the previous one. If false the new mood starts from its beginning.

Port	Description
SetMood	Sets the defined mood
GetMood	Checks what mood is currently playing
Mood	Define the mood that should get set
PlayStart	Defines if the start layer of the new mood should get played if available
PlaySynced	Defines if the new mood should play at the same time of the current mood (1) or if it should start from the beginning (0)
CurrentMood	Outputs the current playing mood after the GetMood input was triggered

Music:EndTheme Node

Allows for stopping of he currently playing Theme through StopMode options provided via a drop-down list.

If EndEverything is true, also Patterns will get stopped. If false, only Themes and Moods will end.

Port	Description
Stop	Ends the current playing Theme (and/or Pattern)
StopMode	Defines how the music should end (Fadeout, Play End Layer,PlayEndLayerAtFadePoint, Stop At Once)
ForceEndLimit	The time before the end of a pattern (when StopMode is PlayEndlayer) or the time before the next fadepoint (when StopMode is PlayEndLayerAtFadePoint) where a layer switch is not allowed anymore.
EndEverything	0 = end only Themes, 1 = end Themes and Patterns

Music:PlayPattern Node

Allows for manually playing a single music pattern. Patterns are provided via a drop-down list. Provides valuable status information.

StopPrevious defines if the previous theme/mood or pattern will get stopped or not.

PlayOnTop should be used if a pattern should play at the same time as a theme/mood (e.g. a stinger)

Port	Description
Play	Plays the defined pattern
Stop	Stops the pattern at once (use EndTheme node if it should fade out)
Pattern	Defines what pattern should be played
StopPrevious	Defines if previous playing patterns should be stopped or not (affects all patterns and themes and uses a fade out)
PlaySynced	Defines is the pattern should start immediately (0) or wait for the next syncpoint of the current mood (1)
PlayOnTop	Indicates if the pattern behaves like a stinger and plays on top of the current mood without occupying a track slot
Started	Outputs when the pattern is started
Done	Outputs when the pattern has ended (either finished or aborted)
Finished	Outputs when the pattern played to the end
Aborted	Outputs when the pattern was stopped before reaching the end (either through the Stop input or an EndTheme node)
Progress	Outputs the current progress (0 to 1)
Time	Outputs the elapsed time in seconds
TimeRemaning	Outputs the remaining time in seconds

Music:Volume Node

MusicVolume can be faded in or out by using the Flow Graph. Properties include StartFade, StopFade, FadeTime, SourceValue, and TargetValue.

Port	Description
StartFade	Starts the volume fade
StopFade	Stops the volume fade
FadeTime	Defines the fade time in seconds (0 for instant change)
SourceValue	Defines the start value from 0 to 1 (-1 is current volume)
TargetValue	Defines the end value from 0 to 1
Done	Outputs when the fade is done (finished or aborted)
Finished	Outputs when the fade is finished
Aborted	Outputs when the fade is aborted
Value	Outputs the current value of the volume during a fade