API
Return to top
SoundService
编辑

场景 / SoundService

SoundService Class
​

音效管理器

Table of contents ​

Properties
​

onPlaySoundComplete: Action1<string number>
播放声音完成的委托(2D声音是string代表assetId, 3D声音是playId代表播放id)

Accessors
​

BGMVolumeScale(): number client
BGM音量
volumeScale(): number client
音效的音量

Methods
​

get3DSoundById(playId: number): Promise<Sound> client
根据播放 id 获取一个 3DSound
play3DSound(assetId: string, target: string GameObject Vector, loopCount?: number, volume?: number, params?: Object): number other
在目标播放3D音效
playBGM(assetId: string, volume?: number): void other
播放背景音乐
playSound(assetId: string, loopCount?: number, volume?: number): string other
根据资源Id播放声音
stop3DSound(playId: number): void other
停止3D声音
stopAll3DSound(): void other
停止一切3D声音
stopAllSound(): void other
停止除BGM以外的一切2D声音
stopBGM(): void other
停止背景音乐
stopSound(assetId: string): void other
根据资源Id停止声音

Properties ​

onPlaySoundComplete
​

▪ Static Readonly onPlaySoundComplete: Action1<string number>

播放声音完成的委托(2D声音是string代表assetId, 3D声音是playId代表播放id)

使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，会播放一个爆炸音效，播放完成后玩家头顶会生成一个火焰特效
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";
        //在玩家当前坐标处播放爆炸音效
        const playId = SoundService.play3DSound(boomSoundAssetId, player.character.worldLocation);
        //音效播放完成回调
        SoundService.onPlaySoundComplete.add((resId) => {
            if (resId == playId) {
                //打印声音播放完成
                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";
        //在玩家当前坐标处播放爆炸音效
        const playId = SoundService.play3DSound(boomSoundAssetId, player.character.worldLocation);
        //音效播放完成回调
        SoundService.onPlaySoundComplete.add((resId) => {
            if (resId == playId) {
                //打印声音播放完成
                console.log("Play sound complete.")
            }
        });
    }
}

Accessors ​

BGMVolumeScale
​

• Static get BGMVolumeScale(): number client

• Static set BGMVolumeScale(value): void client

BGM音量

Precautions

取值范围0-1

Returns ​

number

BGM音量

Precautions

取值范围0-1

Parameters ​

valuenumber

volumeScale
​

• Static get volumeScale(): number client

• Static set volumeScale(value): void client

音效的音量

Precautions

取值范围0-1

Returns ​

number

音效的音量

Precautions

取值范围0-1

Parameters ​

valuenumber

Methods ​

get3DSoundById
​

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

根据播放 id 获取一个 3DSound

Parameters ​

playId number播放的唯一标识，音效资源 ID，等同于 assetId。区别是 playId 传递的是 number 类型，如：4330；assetId 传字符串类型 "4330" 即可。 range: 字符串长度依据资源 ID 长度而定 type:整数

Returns ​

Promise<Sound>Sound 对象的 gameObject
使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，会在0点坐标处创建一个方块，并在该位置播放一个3D音效，按下F键该音效会移动到玩家坐标处
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

在目标播放3D音效

Parameters ​

assetId string播放的唯一标识，音效资源 ID，等同于 playId。区别是 playId 传递的是 number 类型，如：4330；assetId 传字符串类型 "4330" 即可。 range: 字符串长度依据资源 ID 长度而定
target string GameObject Vector播放目标 (GameObject的GUID GameObject 世界坐标)
loopCount? number循环次数，当=0时，为无限播放 default: 1 range:不做限制 type:整数
volume? number音量 default: 1 range:不做限制 type:整数
params? Object播放参数: { radius: 内部半径(default 200), falloffDistance: 衰减距离,不包含内部半径(default 600) } default: undefined
params.falloffDistance? number-
params.radius? number-

Returns ​

number播放ID，播放声音的唯一标识，可用于停止声音
使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，按下F键会在0点坐标处创建一个方块，并在该位置播放一个3D音效，再次按下F键会停止该音效
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

播放背景音乐

Parameters ​

assetId string播放的唯一标识，音效资源 ID，等同于 playId。区别是 playId 传递的是 number 类型，如：4330；assetId 传字符串类型 "4330" 即可。 range: 字符串长度依据资源 ID 长度而定
volume? number音量 default: 1 range:不做限制 type:整数
使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，会播放一个背景音乐
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

根据资源Id播放声音

Parameters ​

assetId string播放的唯一标识，音效资源 ID，等同于 playId。区别是 playId 传递的是 number 类型，如：4330；assetId 传字符串类型 "4330" 即可。 range: 字符串长度依据资源 ID 长度而定
loopCount? number循环次数，当=0时，为无限播放 default: 1 range:不做限制 type:整数
volume? number音量 default: 1 range:不做限制 type:整数

Returns ​

string资源id

Precautions

不可叠加

使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，按下F键会播放一个爆炸音效
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

停止3D声音

Parameters ​

playId number播放的唯一标识，音效资源 ID，等同于 assetId。区别是 playId 传递的是 number 类型，如：4330；assetId 传字符串类型 "4330" 即可。 range: 字符串长度依据资源 ID 长度而定 type:整数
使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，按下F键会在0点坐标处创建一个方块，并在该位置播放一个3D音效，再次按下F键会停止该音效
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

停止一切3D声音

使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，会生成10个方块，每个方块播放一个3D音效，10秒后会自动停止所有3D音效
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

停止除BGM以外的一切2D声音

使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，按下F键会播放两个2D音效，再次按下F键会停止所有音效
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

停止背景音乐

使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，按下F键会播放一个背景音乐,再次按下F键会停止背景音乐
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

根据资源Id停止声音

Parameters ​

assetId string播放的唯一标识，音效资源 ID，等同于 playId。区别是 playId 传递的是 number 类型，如：4330；assetId 传字符串类型 "4330" 即可。 range: 字符串长度依据资源 ID 长度而定
使用示例:创建一个名为SoundExample的脚本，放置在对象栏中，打开脚本，将原本内容修改为如下内容，保存并运行游戏，按下F键会播放一个爆炸音效，再次按下F键会停止播放
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;
            }
        })
    }

}