6. Music and sounds

Now that we've build an adventure game using text and images, we may want to make it much more immersive by adding music and sounds. As shown in tutorial 1, you can use whatever HTML tags you want, including audio and video. So one way to add music (or e.g. narrations) is to add an autoplaying audio file to the HTML file for your StoryScript entity (so far, we covered Locations and Items that have such a file). StoryScript will help to start the autoplay, and will prevent it from autoplaying again when the browser reloads. For example, we could start playing some music by adding this audio tag inside of the description tag in our Start.html file:

<audio controls="controls" autoplay="autoplay">
	<source src="resources/Forest.mp3" type="audio/mp3" />
	Your browser does not support the audio element.
</audio>

StoryScript has a better way to play music, which lets you configure what music to play for what locations in one place. You can also choose what music you want for the game's GameState (e.g. CharacterCreation and Play) and PlayState (e.g. Menu, Combat). To
use this feature, set a playList property on the setup object in your rules.ts. Note that you specify the name of the music file first, and then add when to play it (you can play the same piece of music for multiple game states and locations):

playList: {
	'Medieval.mp3': [GameState.Play],
	'Forest.mp3': [Start]
}

With this, you instruct StoryScript to play the 'Medieval' music while the GameState is Play, while at the Start location the 'Forest' music will play.

Wherever possible, StoryScript tries to allow you to run your own code to determine what to do so you have maximum freedom. In a playlist, you can also specify a custom function that takes the game object and returns the file name of the music that should be played. When you hover over the playList property, you should see the documentation I created to tell you what options you have. All StoryScript classes, properties and functions are documented in this way, hopefully making it much easier for you to figure out all the things you can do:

Apart from music, you can also play sounds. In the old King's Quest games, you'd hear a short sound play when you managed to crack a combination. It was very satisfying to hear this sound after hours of trying! You can play a sound at any time by using the playSound method on the game object's sounds object:

game.sounds.playSound('success.wav');

If you want to play a sound on every successful combination, you can do this using the success hook on the combinations object in your rules.ts file:

combinations: {
    success: (game: IGame) => {
        game.sounds.playSound('success.wav');
    }
}

You can play multiple sounds at once, but then you'll hear them all at once! You also have the option to wait for the sound to complete to do something else. You can pass in a callback function as a second parameter to the playSound function, which will run once the sound has completed.