music_track
music_track is a point entity available in 
Black Mesa. This entity allows you to play music and control it dynamically, without the need to create lots of scripts. The best example of using this entity is the beginning of chapter Surface Tension. When player triggering the trigger - the first music track starts, which is looped (it loops itself, without help from other entities), when the soldiers leaves the ambush - the next track starts, which is also looped. When the fight with the helicopter ends, the last, final track starts, which is not looped. Before this system implementation, music was launching via ambient_generic, which just playing the full version of the music from beginning to end, which made certain parts of the music inappropriate for situations, or even ended when the helicopter didn't even arrive.
All code for original music tracks from Black Mesa placed in game_sounds_music.txt and game_sounds_xen_music.txt, both placed in scripts folder.
Soundscript
This is example of sound script to make your music properly working with this entity. The comments explain what each line does.
"MusicTrackName" //Sound name.
{
"channel" "CHAN_STATIC" //Channels are used to categorize sounds in a way that NPCs, and game logic in general, can understand. In case of music_track, use only CHAN_STATIC.
"volume" "1.0" //A number between 0 and 1, where 1 is the sound's original volume.
"pitch" "100" //Any number between 0 and 255, where 100 is the sound's original pitch and 255 is very high.
"soundlevel" "SNDLVL_NONE" //The sound's attenuation; how fast it drops away. In case of music_track, use only SNDLVL_NONE.
"bpm" "31.7756" //BPM is Beats Per Minute. This value is specific to your music.
"signature" "1" //[Code] your-name-here said the next about it this: "Signature is the time signature: how many Beats Per Measure (BMP). If you know that your song is 100 BPM and that there are 4 beats per measure,
//then you know that each measure covers a 4 beats / 100 bpm slice of time. This is how we can figure out when to fade in the next track".
"fadetime" "2" //How many seconds to fade out the current track over. For example, a value of 5 means "fade this track out over 5 seconds".
"wave" "#music/MyCoolMusiс.wav" //Filename and path to it. Usually all music is placed in music folder.
}
Looping
To make your music endless looping, you'll need to add in your .wav file "loop point". Check out this guide.
Keyvalues
Targetname:
- Name
(targetname)<string> - The targetname that other entities refer to this entity by.
- Sound Name
(track_script_sound)<sound> - Name of the GameSound entry for the music to play.
Important:This doesn't work if you specify sound with path (music\bms - st1-part2.wav for example), instead, sound name from the code of the file must be used (music.st.1-part2 in case of the example). It can't use .wav file paths directly because it need the metadata fields (bpm, signature, fade time) above for the system to work properly.
- Next Track
(next_track_entity)<targetname> - Name of the next music_track entity to play when
Nextinput is called.
Important:You cannot use any track in next music_track, your music must go sequentially in soundscript file. Otherwise it will not work. Quote from [Code] your-name-here about this: "music_track entities function as a playlist that moves in a single direction (managed by BlackMesaMusicTrackManager). Calling Next on a music_track entity will fade out the currently active music track and queue the next oneto play when the next measure starts".
Inputs
Play<void>- Starts the music track.
Note:It cannot be refired while music is playing. Quote from [Code] your-name-here about this: "Doubtful. We ran into a significant number of bugs trying to get this system working. You can only move forward in the playlist (from what I remember)".
Stop<void>- Stops the music track.
Warning:This input only in FGD and doesn't exists in the game.
Fade<void>- Fades the music track out over the given number of seconds in sound script.
Important:Will not work without bpm, signature and fadetime.
Next<void>- Plays the next track when the BPM lines up.
Base:
AddContext<string>- Adds to the entity's list of response contexts. See Context.
AddOutput<string>- Assigns a new keyvalue/output on this entity. For keyvalues, some rely on extra necessary code to be ran and won't work if its simply just changed through this input. There is a strict format that must be followed:
// Format of changing KeyValues: "AddOutput [key] [value]"
//// Raw text:
"OnUser1" "!self,AddOutput,targetname new_name"
// Format of adding an Output: "AddOutput {targetname}:{inputname}:{parameter}:{delay}:{max times to fire, -1 means infinite}"
//// Raw text:
"OnUser1" "!self,AddOutput,OnUser1:SetParent:!activator:0.0:-1"
// Arguments can be left blank, but the empty blank should still be contained.
//// Raw text:
"OnUser1" "!self,AddOutput,OnUser1:ClearParent::0.0:-1"
|
ClearContext- Removes all contexts from this entity's list.
ClearParent- Removes this entity from the the movement hierarchy, leaving it free to move independently.
FireUser1toFireUser4- Fires the respective
OnUseroutputs; see User Inputs and Outputs.
Kill- Removes this entity and any entities parented to it from the world.
KillHierarchy- Functions the same as
Kill, although this entity and any entities parented to it are killed on the same frame, being marginally faster thanKillinput.
RemoveContext<string>- Remove a context from this entity's list. The name should match the key of an existing context.
SetParent<string>- Move with this entity. See Entity Hierarchy (parenting).
SetParentAttachment<string>- Change this entity to attach to a specific attachment point on its parent. The entity will teleport so that the position of its root bone matches that of the attachment. Entities must be parented before being sent this input.
SetParentAttachmentMaintainOffset<string>- As above, but without teleporting. The entity retains its position relative to the attachment at the time of the input being received.
DispatchResponse<string> !FGD- Dispatches a response to the entity. See Response and Concept.
DispatchEffect<string> (removed since
) !FGD- Dispatches a special effect from the entity's origin; See also List of Client Effects. Replaced by the particle system since .
RunScriptFile<script> (in all games since
) (also in 
)- Execute a VScript file from disk, without file extension. The script contents are merged with the script scope of the receiving entity.
RunScriptCode<string> (in all games since) (also in )- Execute a string of VScript source code in the scope of the entity receiving the input. String quotation may be needed when fired via console.
Bug:In Hammer, using string arguments will corrupt the VMF file's structure, making the file unviewable for the next Hammer session.Fix:Remove the string argument manually with a text editor.Note: Backtick characters ` are replaced with quotation marks at runtime, allowing quotation marks to be used when normally not possible.
CallScriptFunction<string> (in all games since) (also in ) !FGD- Calls a VScript function defined in the scope of the receiving entity.
TerminateScriptScope(only in) !FGD- Destroys the script scope of the receving entity.
SetLocalOrigin<coordinates> (in all games since
) !FGD- Send this entity to a spot in the map. If the entity is parented to something, it will be offset from the parent by this amount.
Outputs
Base:
OnUser1toOnUser4- These outputs each fire in response to the firing of the like-numbered
FireUser1toFireUser4Input; see User Inputs and Outputs.
