This page contains documentation about the Music System of CryENGINE and its subsystems.
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.
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 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.
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
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 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.
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.
|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.|
Allows for enabling and disabling the MusicLogic with the defines preset as well as querying for its status.
|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.|
Allows for playing the selected Theme and Mood as well as providing valuable status information.
|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)|
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.
|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|
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.
|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|
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)
|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|
MusicVolume can be faded in or out by using the Flow Graph. Properties include StartFade, StopFade, FadeTime, SourceValue, and TargetValue.
|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|
The node sends ML events to the music system.
|Event||The name of the ML event that should get send|
|Send||Sends the event|