Quick Start Guide Get music playing in your project in 10 steps

This guide walks you through the minimum steps to go from import to adaptive music playback. For full details on every feature and setting, see the MusicTransitionDesignerGuide.

MTD requires Unity 2023.1+ and depends on Unity Addressables (com.unity.addressables).

Import the package

Import MusicTransitionDesigner into your project. It installs to Assets/MusicTransitionDesigner and creates default asset folders. The Startup Window will open automatically.

Create core data assets

In the Startup Window, click the button to generate the core data assets (MtdProjectSettings and MtdEditorData). These are required for MTD to function.

Configure Project Settings

Open Tools → Music Transition Designer → Settings and assign your BGM and Stinger Mixer Groups. You can also set default fade durations for system-wide playback (Stop, Pause, and Resume), configure debug behaviour, and assign default folders for assets here. This can be revisited at any time.

Import audio files and mark them as Addressable

Import your audio clips into the project (the default folder is 00_AudioFiles). Each clip you want to use with MTD must be marked as Addressable in the Inspector.

Set each audio clip's Load Type to Decompress On Load while authoring. This is required for the Music Track Editor to display a high-resolution waveform. You can change the Load Type back after you've finished setting up the Music Track.

Create Music Tracks

Open the Asset Manager via Tools → Music Transition Designer → Asset Manager.

Opening assets: Double-click an asset in the Asset Manager list to open it for editing in the tab above.

Assets that require validation: State Groups, Outcome Categories, State Outcomes, and Transition Rules must be validated before they become active. When you finish editing one of these, always press Validate and Enable first, then Save.

In the Music Tracks tab, create a Music Track for each audio clip. Double-click a track in the list to open it. For each track:

Assign the audio clip.
Set the BPM and time signature.
Set the Entry Point (where Bar 1 Beat 1 sits) and Exit Point (where the track should stop or loop).
Optionally add Track Markers, a Lead-In, or a Tail.

Do not duplicate Music Track assets via copy-paste in Unity's Project window. This causes GUID conflicts that will invalidate the asset and anything that references it. If this happens, open the duplicate and press Generate New GUIDs.

Create State Groups

In the State Groups tab, create groups that represent your game-state categories. For example:

A group called Location with states: Village, Forest, Dungeon.
A group called CombatStatus with states: NotInCombat, InCombat.

Double-click the State Group in the list to open it. When finished, press Validate and Enable first, then Save.

The same GUID duplication warning applies to State Groups. Do not copy-paste State Group assets.

Create a State Tree

In the State Trees tab, create a State Tree. Double-click it in the list to open it. This maps state combinations to music.

Add your State Groups to the State Hierarchy.
Press New Branch to create branches.
For each branch, select the state conditions that must be met (states within a column = OR; across columns = AND).
Create or assign a State Outcome for each branch. State Outcomes can be created directly from here.

Branches evaluate top to bottom — the first match wins. Watch for shadowing warnings if a higher branch makes a lower one unreachable.

Edit State Outcomes

In the State Outcomes tab, double-click each State Outcome in the list to open it and configure playback:

Assign a Music Track.
Set Play From, Play Until, and Loop behaviour.
Optionally override the track's default volume.

When finished, press Validate and Enable first, then Save.

The Play Until position must be later than the Play From and Loop To positions, or the asset will not validate.

Create Transition Rules

In the Transition Rules tab, create rules that define how music changes between State Outcomes. Double-click a rule in the list to open it. For each rule:

Set the Track A (outgoing) and Track B (incoming) types — these can be specific State Outcomes, Outcome Categories, Any, or None.
Choose a Sync Point (e.g. On Next Bar, Immediate, On Marker).
Configure fade settings for the outgoing and incoming tracks.

When finished, press Validate and Enable first, then Save.

Start with a single Any → Any rule as a fallback. You can add more specific rules later — they will automatically take priority. If no rule matches at all, MTD will immediately stop the current track and play the next one.

Create a SoundBank, set up the scene, and play

Create a SoundBank

In the SoundBanks tab, create a SoundBank and double-click it to open it. Add your State Tree to the Source State Trees list. This automatically includes all referenced State Outcomes, Music Tracks, and applicable Transition Rules.

Set up the scene

Add the MtdSceneInitialiser prefab to your scene. On the component:

Add your SoundBank to the Persistent Scene Banks list.
Set the Initial State Tree.
Set the Initial States (the starting state for each State Group).
Set Playback to Start to begin music automatically.

Trigger state changes

To change music during gameplay, set states using either:

Components — add an MtdOnTriggerEnter (or any other trigger) and an MtdStateControl action to a GameObject, then drag the action into the trigger's list.
Code — call MtdApi.SetState. See MtdApi.cs or MusicTransitionDesignerGuide.html for full details on parameters.

Press Play. Music should start, and changing states will trigger transitions according to your rules.

Test with the Preview Window

You don't need to enter Play Mode to test transitions. Open Tools → Music Transition Designer → Preview Window, load your SoundBanks, set the active tree and states, press Play, then change states and click Transition Now to audition transitions directly in the editor.

Common pitfalls

Audio not marked as Addressable — clips won't load at runtime. Check each clip's Inspector.
Waveform is low-resolution — set the clip's Load Type to Decompress On Load while authoring.
Duplicated assets — copy-pasting Music Tracks, State Groups, or State Trees in Unity's Project window causes GUID conflicts. Use Generate New GUIDs on the duplicate.
No music playing — ensure MtdSceneInitialiser is in the scene, at least one SoundBank is loaded, a State Tree is active, and its entries have valid State Outcomes.
Transitions not firing — check that a Transition Rule exists for the transition path, is enabled, and is included in a loaded SoundBank.
Validation errors / asset stays disabled — for State Groups, Outcome Categories, State Outcomes, and Transition Rules, press Validate and Enable before Save. The Asset Manager also flags issues in real time; fix the root cause (usually a missing reference or timeline ordering issue) and dependent assets will become valid again.