Overview of sound systems

There are two types of sounds available in the audio system: sound effects and music. Sound effects are short bursts of quick sounds that signal the player of the game making progress. A few examples of sound effects are gun noises, bullets firing, a character jumping, physics contact events and many others. Music is longer in length and usually played in a loop. A few examples of music are background music, cut scenes, successfully completing a milestone in the game and many others.

All audio assets are imported into the editor in the format of audioClip assets.

Music Playing

1. Create an empty node on the Node Tree
2. Select the empty node and click Add Component -> Components -> AudioSource at the bottom of the Properties to add the AudioSource component.

3. Drag the audio resources in Assets to the Clip of the AudioSource component, as follows:

   

4. Next, set the other parameter of the AudioSource component as needed, for the details please refer to the Audiosource Component documentation.

If you only need to play the audio automatically after the game is loaded, check the PlayOnAwake of the AudioSource component. If you want more flexibility in controlling AudioSource playback, you can get the AudioSource Component in the custom script and then call the appropriate API. As shown below:

// AudioController.ts
@ccclass("AudioController")
export class AudioController extends Component { 
    @property(AudioSource)
    public audioSource: AudioSource = null!;
    play () {
        this.audioSource.play();
    }
    pause () {
        this.audioSource.pause();
    }
}

Next, add the corresponding custom component to the editor’s Properties. Selecting the corresponding node and add the custom component by clicking Add Component-> Custom script -> User Script at the bottom of the Properties. Then drag and drop the node with the AudioSource component onto Audio Source in the custom component. As shown below:

Effect Playing

Compared to long music playback, audio effects playback has the following characteristics:

• Short playback time
• A large number of simultaneous playback

For such playback requirements, the AudioSource component provides the playOneShot interface to play audio effects. The specific code implementation is as follows:

// AudioController.ts
@ccclass("AudioController")
export class AudioController extends Component {     
    @property(AudioClip)
    public clip: AudioClip = null!;   
    @property(AudioSource)
    public audioSource: AudioSource = null!;
    playOneShot () {
        this.audioSource.playOneShot(this.clip, 1);
    }
}

Note: playOneShot is a one-time play operation, there is no way to pause or stop the audio after it is played, and no way to register the ended event callback.

Web Platform Playback Restrictions

Audio playback on the Web platform currently requires compliance with the latest Audio Play Police, and even if the AudioSource component is set to playOnAwake it will not start until the first user input is received. An example is as follows:

// AudioController.ts
@ccclass("AudioController")
export class AudioController extends Component {      
    @property(AudioSource)
    public audioSource: AudioSource = null!;
    start () {
        let btnNode = find('BUTTON_NODE_NAME');
        btnNode!.on(Node.EventType.TOUCH_START, this.playAudio, this);
    }
    playAudio () {
        this.audioSource.play();
    }
}

Related Links

Audio Asset AudioSource Component