Music Organization

Overview

Music is organized as themes, moods, and patterns.

A theme is a larger collection of pieces of music of a certain type or a special melody. A theme consists of several moods (for example, ambient, middle, high) that are a certain expression of that theme.
A mood consists of several layers (for example, main, start, stinger) that can each hold one or more patterns. Usually moods within a theme have the same key and tempo to allow smooth cross-fading.
A pattern is a piece of music. Patterns used moods are usually loopable, while those used at special moment are often one-shots.

Themes

Themes are adaptive pieces of music that contain different levels of intensity. Each level of intensity has its own beginning, loop, and end, as well as random decorative one-shots. Every theme must have a unique name.

A theme contains all the parts of a piece of music that are used to make it adaptable to the gameplay. Adaptive music has different levels of intensity or feeling in one theme. Think of a theme as a piece of music that is made up of Moods with differing levels of intensity.

It is best practice for each theme to have a default mood, which is listed in the theme properties in the music database window. Moods are not dependent on the MusicLogic system. For instance, the MusicLogic system can be turned off, but will still be able to play moods by using triggers.

Playing a Theme

Attach a MusicThemeSelector entity to an area shape. In the MusicThemeSelector properties, enter a theme name. To make the music change its intensity based on the state of the game, Music Logic must be enabled. In order to enable Music Logic:
Place a Music:LogicTrigger node in a Flow Graph.
Connect a trigger to its Start Music Logic port. When the player enters the area shape, the theme will be set and the music will change based on the gameplay.

or...

Place a Music:ThemeSelector node in flowgraph and select a Theme/Mood.
Add a Music:LogicTrigger node.
Trigger the Play or Start inputs of these nodes.

Theme Properties

Parameter	Function
Default Mood	Defines the mood that gets used when the theme gets started without a mood being selected.
Default Mood Timeout
Mood Crossfade Time	Defines the time it takes to fade from one mood to another.
Bridges

Moods

Think of a mood as a level of intensity. Moods do not have to have unique names. As moods are used by music logic to transition between different intensities in one theme, it is necessary to have a similar collection of moods in each theme.

Moods are made up of a set of patterns. A mood must have a main layer, which is a looping piece of music. Typically patterns of the main layer have the same key and tempo of moods across the same theme to allow smooth cross fading.

Often, a mood can have start and end layers. Start and end are optional patterns, designed to be attached to the front or back of a looping piece to create graceful endings and beginnings.

There is also an incidental layer and rhythmic layer, which play a short pattern on top of a looping piece. This can add variety to the music. Finally, there is a stinger layer. Stingers are not synced to fade points and and can be triggered via FG using the node of the MusicStinger entity.

If the music logic gets used, the mood names must match the node names in the music logic preset.

Mood Properties

Parameter	Function
Priority
Fade Out Time	Determines the time needed to fade out the current mood, when the mood gets stopped.
Fade In Time	Determines the time needed to fade in the current mood, when the mood starts.
Play Single	This will force a mood to play once, instead of looping.
Start Layer Playcount	Defines how often the start layer can be played, if the mood gets played from the beginning multiple times (-1 = infinite)

Layers

Parameter	Function
Start Layer	If a start layer is present, the music system will choose to play it and seamlessly attach the main layer.
Main Layer	Defines the actual music piece that gets played. The main layer has 2 properties: Custom Index creates a playlist of the containing patterns. Their index numbers are entered, separated by a comma (and no space). Loop defines if the custom order gets looped or not.
End Layer	When ending a piece of music, the music system will play the end pattern when it has reached the end of the main pattern. Note: There is also a flag in the MusicEndTheme entity to jump from a fade point to the end pattern. This way, a theme can be ended quickly and gracefully.
Incidental Layer	These are patterns which will play at random sync points, in time with the main layer. They are typically used as embellishments to a consistent loop. The Incidental layer has a probability that determines how one of its patterns will play when a sync point is reached. There is also a probability setting for each pattern so that patterns can be weighed differently.
Stinger Layer	When stingers are triggered, they play irrespective of sync points, and not in time with the main layer.
Rhythmic Layer	Same behavior as the incidental layer.

Patterns

The smallest music building block is a pattern. It is an audio file. Every pattern must have a unique name. The music system must be able to differentiate between patterns.

A pattern can be used either as a one time piece of music or as a part of a more complex piece of music. The specific audio file is listed at the pattern level. The music system does not play sound events; it directly plays audio files.

Pattern Properties

Parameter	Function
Filename	Click the folder icon to open the sound browser; then, click the browse file to select an audio file.
Fade Points	Fadepoints are measured in samples. Each fade point is a sample value separated by a comma, with no space.
Pre-FadeIn	When a pattern begins to fade in, this is the number of samples before a fade point.
Volume	The music volume in decibel.
Probability	When there is more than one pattern in a layer, this value sets each pattern's likelihood of being played.
Custom Index	In the main layer properties a Custom Order can be set to create a playlist if multiple patterns are available. The Custom Index (integer) value is used to specify the correct pattern in the order.

Playing a Pattern

Trigger the MusicPlayPattern entity to play a pattern. In the MusicPlayPattern properties, enter a pattern name. When the entity is triggered, the pattern will play once.