Editor API
Return to top
SoundService
Edit

Scene / SoundService

SoundService Class ​

Sound Manager

Table of contents ​

Properties ​

onPlaySoundComplete: Action1<string number>
The task of completing the playback of sound (2D sound is represented by string for assetId, 3D sound is represented by playId for playback id)

Accessors ​

BGMVolumeScale(): number other
BGM volume
volumeScale(): number other
Volume of sound effects

Methods ​

get3DSoundById(playId: number): Promise<Sound> other
Get a 3DSound based on the playback ID
play3DSound(assetId: string, target: string GameObject Vector, loopCount?: number, volume?: number, params?: Object): number other
Play 3D sound effects on the target
playBGM(assetId: string, volume?: number): void other
Play background music
playSound(assetId: string, loopCount?: number, volume?: number): string other
Play sound according to asset ID
stop3DSound(playId: number): void other
Stop 3D sound
stopAll3DSound(): void other
Stop all 3D sound
stopAllSound(): void other
Stop all 2D sound except BGM
stopBGM(): void other
Stop background music
stopSound(assetId: string): void other
Stop sound according to asset ID

Properties ​

onPlaySoundComplete ​

▪ Static Readonly onPlaySoundComplete: Action1<string number>

The task of completing the playback of sound (2D sound is represented by string for assetId, 3D sound is represented by playId for playback id)

Usage example: create a script named SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, and an explosion sound effect will be played. After playing, a fire effect will be generate above the Player's head

ts
@Component
export default class SoundExample extends Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await Player.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        //Play explosive sound effects at the player's current coordinates
        const playId = SoundService.play3DSound(boomSoundAssetId, player.character.worldLocation);
        //Sound effect playback completed callback
        SoundService.onPlaySoundComplete.add((resId) => {
            if (resId == playId) {
                //Printing sound playback completed
                console.log("Play sound complete.")
            }
        });
    }
}
@Component
export default class SoundExample extends Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await Player.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        //Play explosive sound effects at the player's current coordinates
        const playId = SoundService.play3DSound(boomSoundAssetId, player.character.worldLocation);
        //Sound effect playback completed callback
        SoundService.onPlaySoundComplete.add((resId) => {
            if (resId == playId) {
                //Printing sound playback completed
                console.log("Play sound complete.")
            }
        });
    }
}

Accessors ​

BGMVolumeScale ​

• Static get BGMVolumeScale(): number other

• Static set BGMVolumeScale(value): void other

BGM volume

Precautions

Value range 0-1

Returns ​

number

BGM volume

Precautions

Value range 0-1

Parameters ​

valuenumber

volumeScale ​

• Static get volumeScale(): number other

• Static set volumeScale(value): void other

Volume of sound effects

Precautions

Value range 0-1

Returns ​

number

Volume of sound effects

Precautions

Value range 0-1

Parameters ​

valuenumber

Methods ​

get3DSoundById ​

• Static get3DSoundById(playId): Promise<Sound> other

Get a 3DSound based on the playback ID

Parameters ​

playId numberThe unique ID for playing, the sound effect asset ID, is equal to the assetId. The difference is that playId passes a number type, such as 4330; The assetId can be transferred to the string type "4330". Range: string length depends on the length of asset ID type: integer

Returns ​

Promise<Sound>Sound GameObject of the object

Usage example: create a script named SoundExample, place it in the object bar, open the script, modify the original content to the following content, save and run the game, create a box at the coordinates of point 0, and play a 3D sound effect at the position. press the F key, the sound effect will move to the coordinates of Player

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
            obj.worldLocation = new mw.Vector(0, 0, 0);
        })
        let playId = SoundService.play3DSound(bgmSoundAssetId, new mw.Vector(0, 0, 0), 0);
        InputUtil.onKeyDown(Keys.F, () => {
            SoundService.get3DSoundById(playId).then(obj => {
                obj.worldLocation = player.character.worldLocation;
            })
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
            obj.worldLocation = new mw.Vector(0, 0, 0);
        })
        let playId = SoundService.play3DSound(bgmSoundAssetId, new mw.Vector(0, 0, 0), 0);
        InputUtil.onKeyDown(Keys.F, () => {
            SoundService.get3DSoundById(playId).then(obj => {
                obj.worldLocation = player.character.worldLocation;
            })
        })
    }

}

play3DSound ​

• Static play3DSound(assetId, target, loopCount?, volume?, params?): number other

Play 3D sound effects on the target

Parameters ​

assetId stringThe unique ID of the play, the ID of the sound effect asset, is equal to the playId. The difference is that playId passes a number type, such as 4330; The assetId can be transferred to the string type "4330". Range: string length depends on the length of asset ID
target string GameObject VectorPlay target (GUID of GameObject GameObject world coordinates)
loopCount? numberLoop count, when=0, infinite playback default: 1 range: no limit type: integer
volume? numberVolume default: 1 range: no restriction type: integer
params? ObjectPlay parameters: {radius: internal radius (default 200), falloffDistance: attenuation distance, excluding internal radius (default 600)} default: undefined
params.falloffDistance? number-
params.radius? number-

Returns ​

numberPlay ID, a unique identifier for playing sound, can be used to stop the sound

Usage example: create a script named SoundExample, place it in the object bar, open the script, modify the original content to the following content, save and run the game, press the F key to create a square at the 0 point coordinate, and play a 3D sound effect at the position, and press the F key again to stop the sound effect

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
            obj.worldLocation = new mw.Vector(0, 0, 0);
        })
        let isPlay = false;
        let playId = 0;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stop3DSound(playId);
            } else {
                playId = SoundService.play3DSound(bgmSoundAssetId, new mw.Vector(0, 0, 0), 0);
            }
            isPlay = !isPlay;
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
            obj.worldLocation = new mw.Vector(0, 0, 0);
        })
        let isPlay = false;
        let playId = 0;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stop3DSound(playId);
            } else {
                playId = SoundService.play3DSound(bgmSoundAssetId, new mw.Vector(0, 0, 0), 0);
            }
            isPlay = !isPlay;
        })
    }

}

playBGM ​

• Static playBGM(assetId, volume?): void other

Play background music

Parameters ​

assetId stringThe unique ID of the play, the ID of the sound effect asset, is equal to the playId. The difference is that playId passes a number type, such as 4330; The assetId can be transferred to the string type "4330". Range: string length depends on the length of asset ID
volume? numberVolume default: 1 range: no restriction type: integer

Example usage: Create a script called SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, and a background music will be played

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        SoundService.playBGM(bgmSoundAssetId, 1);
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        SoundService.playBGM(bgmSoundAssetId, 1);
    }

}

playSound ​

• Static playSound(assetId, loopCount?, volume?): string other

Play sound according to asset ID

Parameters ​

assetId stringThe unique ID of the play, the ID of the sound effect asset, is equal to the playId. The difference is that playId passes a number type, such as 4330; The assetId can be transferred to the string type "4330". Range: string length depends on the length of asset ID
loopCount? numberLoop count, when=0, infinite playback default: 1 range: no limit type: integer
volume? numberVolume default: 1 range: no restriction type: integer

Returns ​

stringAsset ID

Precautions

Cannot be stacked

Usage example: create a script named SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, and press the F key to play an explosion sound effect

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        InputUtil.onKeyDown(Keys.F, () => {
            SoundService.playSound(boomSoundAssetId);
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        InputUtil.onKeyDown(Keys.F, () => {
            SoundService.playSound(boomSoundAssetId);
        })
    }

}

stop3DSound ​

• Static stop3DSound(playId): void other

Stop 3D sound

Parameters ​

playId numberThe unique ID for playing, the sound effect asset ID, is equal to the assetId. The difference is that playId passes a number type, such as 4330; The assetId can be transferred to the string type "4330". Range: string length depends on the length of asset ID type: integer

Usage example: create a script named SoundExample, place it in the object bar, open the script, modify the original content to the following content, save and run the game, press the F key to create a square at the 0 point coordinate, and play a 3D sound effect at the position, and press the F key again to stop the sound effect

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
            obj.worldLocation = new mw.Vector(0, 0, 0);
        })
        let isPlay = false;
        let playId = 0;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stop3DSound(playId);
            } else {
                playId = SoundService.play3DSound(bgmSoundAssetId, new mw.Vector(0, 0, 0), 0);
            }
            isPlay = !isPlay;
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
            obj.worldLocation = new mw.Vector(0, 0, 0);
        })
        let isPlay = false;
        let playId = 0;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stop3DSound(playId);
            } else {
                playId = SoundService.play3DSound(bgmSoundAssetId, new mw.Vector(0, 0, 0), 0);
            }
            isPlay = !isPlay;
        })
    }

}

stopAll3DSound ​

• Static stopAll3DSound(): void other

Stop all 3D sound

Example usage: Create a script called SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, it will generate 10 blocks, each block will play a 3D sound effect, and after 10 seconds, all 3D sound effects will automatically stop

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        for (let i = 0;
i < 10;
i++) {
            mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
                obj.worldLocation = new mw.Vector(i * 300, 0, 0);
                SoundService.play3DSound(bgmSoundAssetId, obj, 0);
            })
        }
        setTimeout(() => {
            SoundService.stopAll3DSound();
        }, 10000);
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        const cubeId = "197386";
        for (let i = 0;
i < 10;
i++) {
            mw.GameObject.asyncSpawn({ guid: cubeId }).then(obj => {
                obj.worldLocation = new mw.Vector(i * 300, 0, 0);
                SoundService.play3DSound(bgmSoundAssetId, obj, 0);
            })
        }
        setTimeout(() => {
            SoundService.stopAll3DSound();
        }, 10000);
    }

}

stopAllSound ​

• Static stopAllSound(): void other

Stop all 2D sound except BGM

Example usage: Create a script called SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, press the F key to play two 2D sound effects, press the F key again to stop all sound effects

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        const boomSoundAssetId2 = "20479";
        let isPlay = false;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stopAllSound();
                isPlay = false;
            } else {
                SoundService.playSound(boomSoundAssetId, 0);
                SoundService.playSound(boomSoundAssetId2, 0);
                isPlay = true;
            }
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        const boomSoundAssetId2 = "20479";
        let isPlay = false;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stopAllSound();
                isPlay = false;
            } else {
                SoundService.playSound(boomSoundAssetId, 0);
                SoundService.playSound(boomSoundAssetId2, 0);
                isPlay = true;
            }
        })
    }

}

stopBGM ​

• Static stopBGM(): void other

Stop background music

Example usage: Create a script called SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, press the F key to play a background music, press the F key again to stop the background music

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        let isPlay = false;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stopBGM();
            } else {
                SoundService.playBGM(bgmSoundAssetId, 1);
            }
            isPlay = !isPlay;
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const bgmSoundAssetId = "12721";
        let isPlay = false;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stopBGM();
            } else {
                SoundService.playBGM(bgmSoundAssetId, 1);
            }
            isPlay = !isPlay;
        })
    }

}

stopSound ​

• Static stopSound(assetId): void other

Stop sound according to asset ID

Parameters ​

assetId stringThe unique ID of the play, the ID of the sound effect asset, is equal to the playId. The difference is that playId passes a number type, such as 4330; The assetId can be transferred to the string type "4330". Range: string length depends on the length of asset ID

Usage example: create a script named SoundExample, place it in the object bar, open the script, modify the original content to the following, save and run the game, press the F key to play an explosive sound effect, and press the F key again to stop playing

ts
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        let isPlay = false;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stopSound(boomSoundAssetId);
                isPlay = false;
            } else {
                SoundService.playSound(boomSoundAssetId, 0);
                isPlay = true;
            }
        })
    }

}
@Component
export default class SoundExample extends mw.Script {

    protected onStart(): void {
        if (!SystemUtil.isClient()) return;
        this.test();
    }

    private async test(): Promise<void> {
        const player = await mw.asyncGetLocalPlayer();
        const boomSoundAssetId = "13896";
        let isPlay = false;
        InputUtil.onKeyDown(Keys.F, () => {
            if (isPlay) {
                SoundService.stopSound(boomSoundAssetId);
                isPlay = false;
            } else {
                SoundService.playSound(boomSoundAssetId, 0);
                isPlay = true;
            }
        })
    }

}