API
Return to top
Sound
编辑

场景 / Sound

Sound Class
​

音效

使用示例:创建一个名为"SoundExample"的脚本，放置在对象栏中，打开脚本，输入以下代码保存，运行游戏，你可以听到音效的声音。代码如下：
ts
@Component
export default class SoundExample extends Script {

    private readonly sound = {
        assetID: "14929",
        object: null as mw.Sound,
    };

    protected onStart(): void {
        this.createSound();
    }

    @mw.RemoteFunction(mw.Client)
    public async createSound(): `Promise`<`void`\> {
        const success = await AssetUtil.asyncDownloadAsset(this.sound.assetID);
            if (success) {
                // 下载完毕创建音效
                this.sound.object = await GameObject.asyncSpawn<mw.Sound>(this.sound.assetID);

                // 设置音效transform
                const transform = new Transform(new Vector(0, 0, 0), new Rotation(0, 0, 0), new Vector(1, 1, 1));
                this.sound.object.worldTransform = transform;

                // 设置音效为空间音效
                this.sound.object.isUISound = false;
                this.sound.object.isSpatialization = true;
                // 设置UI音效形状为球形
                this.sound.object.attenuationShape = AttenuationShape.Sphere;
                // 设置音效范围100
                this.sound.object.attenuationShapeExtents = new Vector(100,0,0);
                // 设置音效衰减距离为200
                this.sound.object.falloffDistance = 200;
                // 设置音效音量
                this.sound.object.volume = 1;
                // 开启音效循环
                this.sound.object.isLoop = true;
                // 播放音效
                this.sound.object.play();
            }
    }
}
@Component
export default class SoundExample extends Script {

    private readonly sound = {
        assetID: "14929",
        object: null as mw.Sound,
    };

    protected onStart(): void {
        this.createSound();
    }

    @mw.RemoteFunction(mw.Client)
    public async createSound(): `Promise`<`void`\> {
        const success = await AssetUtil.asyncDownloadAsset(this.sound.assetID);
            if (success) {
                // 下载完毕创建音效
                this.sound.object = await GameObject.asyncSpawn<mw.Sound>(this.sound.assetID);

                // 设置音效transform
                const transform = new Transform(new Vector(0, 0, 0), new Rotation(0, 0, 0), new Vector(1, 1, 1));
                this.sound.object.worldTransform = transform;

                // 设置音效为空间音效
                this.sound.object.isUISound = false;
                this.sound.object.isSpatialization = true;
                // 设置UI音效形状为球形
                this.sound.object.attenuationShape = AttenuationShape.Sphere;
                // 设置音效范围100
                this.sound.object.attenuationShapeExtents = new Vector(100,0,0);
                // 设置音效衰减距离为200
                this.sound.object.falloffDistance = 200;
                // 设置音效音量
                this.sound.object.volume = 1;
                // 开启音效循环
                this.sound.object.isLoop = true;
                // 播放音效
                this.sound.object.play();
            }
    }
}

Hierarchy ​

Table of contents ​

Properties
​

onFinish: MulticastDelegate<() => void>
声音结束事件
onPause: MulticastDelegate<() => void>
声音暂停事件
onPlay: MulticastDelegate<() => void>
声音开始事件
click

Properties
​

onBeforeDestroyDelegate: MulticastDelegate<() => void>
物体销毁前事件回调
onCustomPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
监听自定义属性同步事件
onDestroyDelegate: MulticastDelegate<() => void>
物体销毁后事件回调
onPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>>
监听系统属性同步事件

Accessors
​

attenuationDistanceModel(): AttenuationDistanceModel client
获取音效的衰减方式
attenuationShape(): AttenuationShape client
获取音效的形状
attenuationShapeExtents(): Vector client
获取音效形状范围
falloffDistance(): number client
获取衰减距离
isLoop(): boolean client
获取是否循环播放
isSpatialization(): boolean client
获取音效空间化
isUISound(): boolean client
获取是否是UI音效
playState(): SoundPlayState client
获取音效播放状态
timeLength(): number client
获取音效时长
timePosition(): number client
获取当前已播放时长
volume(): number client
获取音量比例
click

Accessors
​

assetId(): string
获取当前物体使用资源的GUID
gameObjectId(): string
获取物体的唯一标识（唯一标识一个对象的字符串）。
isDestroyed(): boolean
当前物体是否被销毁
isReady(): boolean
当前物体状态
localTransform(): Transform
当前物体本地变换
name(): string
返回当前物体名称
netStatus(): NetStatus
获取当前物体同步状态
parent(): GameObject
获取当前父物体
tag(): string
获取当前物体的标签
worldTransform(): Transform
当前物体世界变换

Methods
​

pause(bPause?: boolean): void
暂停播放音效
play(startTime?: number, onSuccess?: () => void): void
播放音效
setSoundAsset(assetGUID: string): void client
通过 GUID 设置音效
stop(): void
停止播放音效
click

Methods
​

addComponent<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>, bInReplicates?: boolean): T: extends Script<T>
添加一个脚本组件
asyncGetChildByName(name: string): Promise<GameObject>
异步根据名称查找子物体
asyncReady(): Promise<GameObject>
物体准备好后返回
clone(gameObjectInfo?: GameObjectInfo): GameObject
复制对象
destroy(): void
删除对象
getBoundingBox(nonColliding?: boolean, includeFromChild?: boolean, outer?: Vector): Vector
获取物体包围盒大小
getBounds(onlyCollidingComponents: boolean, originOuter: Vector, boxExtentOuter: Vector, includeFromChild?: boolean): void
获取物体边界
getChildByGameObjectId(gameObjectId: string): GameObject
根据 gameObjectId 查找子物体
getChildByName(name: string): GameObject
根据名称查找子物体
getChildByPath(path: string): GameObject
根据路径查找子物体
getChildren(): GameObject[]
获取子物体
getChildrenBoundingBoxCenter(outer?: Vector): Vector
获取所有子对象包围盒中心点(不包含父对象,父对象不可用返回[0,0,0])
getChildrenByName(name: string): GameObject[]
通过名字查找所有的子物体
getComponent<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>
获取指定类型的组件
getComponentPropertys<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>): Map<string, IPropertyOptions>
获取脚本组件属性
getComponents<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>[]
获取指定类型的所有组件
getCustomProperties(): string[]
获取所有自定义属性
getCustomProperty<T: extends CustomPropertyType>(propertyName: string): T: extends CustomPropertyType
获取自定义属性
getCustomPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
给定对象属性修改时触发的事件代理
getPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
给定对象属性修改时触发的事件代理
getVisibility(): boolean
获取物体是否被显示
moveBy(velocity: Vector, isLocal?: boolean): void other
按给定的速度矢量随时间平滑地移动对象
moveTo(targetPosition: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前位置平滑移动至目标位置
rotateBy(rotation: Quaternion Rotation, multiplier: number, isLocal?: boolean): void other
按给定的旋转量随时间平滑地旋转对象
rotateTo(targetRotation: Quaternion Rotation, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前旋转平滑变化至目标旋转
scaleBy(scale: Vector, isLocal?: boolean): void other
按每秒给定的缩放矢量随时间平滑缩放对象
scaleTo(targetScale: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前缩放平滑变化至目标缩放
setAbsolute(absolutePosition?: boolean, absoluteRotation?: boolean, absoluteScale?: boolean): void
设置物体localTransform是相对于父物体或者世界
setCustomProperty(propertyName: string, value: undefined CustomPropertyType): void
设置自定义属性
setVisibility(status: boolean PropertyStatus, propagateToChildren?: boolean): void
设置物体是否被显示
stopMove(): void other
中断moveTo()、moveBy()的进一步移动
stopRotate(): void other
中断从rotateTo()或rotateBy()的进一步旋转
stopScale(): void other
中断从ScaleTo()或ScaleBy()的进一步缩放
asyncFindGameObjectById(gameObjectId: string): Promise<GameObject>
通过 gameObjectId 异步查找 GameObject
asyncGetGameObjectByPath(path: string): Promise<GameObject>
通过路径异步查找物体
asyncSpawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): Promise<T: extends GameObject<T>>
异步构造一个物体
bulkPivotTo(gameObjects: GameObject[], transforms: Transform[]): void
批量设置位置
findGameObjectById(gameObjectId: string): GameObject
通过 gameObjectId 查找物体
findGameObjectByName(name: string): GameObject
通过名字查找物体
findGameObjectsByName(name: string): GameObject[]
通过名字查找物体
findGameObjectsByTag(tag: string): GameObject[]
通过自定义标签获取物体
getGameObjectByPath(path: string): GameObject
通过路径查找物体
spawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): T: extends GameObject<T>
构造一个物体

Properties ​

onFinish
​

• onFinish: MulticastDelegate<() => void>

声音结束事件

onPause
​

• onPause: MulticastDelegate<() => void>

声音暂停事件

onPlay
​

• onPlay: MulticastDelegate<() => void>

声音开始事件

Accessors ​

attenuationDistanceModel
​

• get attenuationDistanceModel(): AttenuationDistanceModel client

• set attenuationDistanceModel(model): void other

获取音效的衰减方式

Returns ​

AttenuationDistanceModel衰减方式

设置音效的衰减方式

Parameters ​

modelAttenuationDistanceModel

attenuationShape
​

• get attenuationShape(): AttenuationShape client

• set attenuationShape(shape): void other

获取音效的形状

Returns ​

AttenuationShape形状

设置音效的形状

Parameters ​

shapeAttenuationShape

attenuationShapeExtents
​

• get attenuationShapeExtents(): Vector client

• set attenuationShapeExtents(ShapeExtents): void client

获取音效形状范围

Returns ​

Vector音效范围

设置音效形状范围 用于衰减形状的尺寸，每个形状的值解释不同。

球体 X是球体半径，Y和Z未使用

胶囊 X是半高，Y是半径，Z未使用

长方体 X、Y和Z是长方体的尺寸

圆锥体 X是圆锥体半径，Y是圆锥体角度，Z是圆锥体衰减角度

Parameters ​

ShapeExtents Vector设置形状范围

falloffDistance
​

• get falloffDistance(): number client

• set falloffDistance(falloffDistance): void client

获取衰减距离

Returns ​

number距离

设置衰减距离

Parameters ​

falloffDistance number距离

isLoop
​

• get isLoop(): boolean client

• set isLoop(Loop): void client

获取是否循环播放

Returns ​

boolean是否循环

设置循环播放

Parameters ​

Loop boolean设置是否开启循环

isSpatialization
​

• get isSpatialization(): boolean client

• set isSpatialization(spatialization): void client

获取音效空间化

Returns ​

boolean是否开启音效空间化

设置音效空间化，若是，则开启空间传播衰减

Parameters ​

spatialization boolean设置开启音效空间化

isUISound
​

• get isUISound(): boolean client

• set isUISound(isUISound): void client

获取是否是UI音效

Returns ​

booleanboolean

设置是否是UI音效，注意：UI音效不依赖游戏逻辑

Parameters ​

isUISound boolean是否用于UI

playState
​

• get playState(): SoundPlayState client

获取音效播放状态

Returns ​

SoundPlayState是否正在播放

timeLength
​

• get timeLength(): number client

获取音效时长

Returns ​

number音效时长(ms)

timePosition
​

• get timePosition(): number client

获取当前已播放时长

Returns ​

number已播放时长

volume
​

• get volume(): number client

• set volume(volume): void client

获取音量比例

Returns ​

number音量比例

设置音量 0~1

Parameters ​

volume number音量比例

Methods ​

pause
​

• pause(bPause?): void

暂停播放音效

Parameters ​

bPause? boolean设置暂停状态 default:true

play
​

• play(startTime?, onSuccess?): void

播放音效

Parameters ​

startTime? number设置起始播放时间 default:0 range: 不大于音效的时长 type: 浮点数
onSuccess? () => void播放完成后回调 default: null

setSoundAsset
​

• setSoundAsset(assetGUID): void client

通过 GUID 设置音效

Parameters ​

assetGUID string音效资源 ID range: 依据 ID 长度而定

stop
​

• stop(): void

停止播放音效