pyxen.Sound

附加到 Entity 作为组件的短音频片段。

Sound 完全加载到内存中——用于跳跃、击中和拾取等短效果。

有关音频概念，请参见音频。

构造函数

Sound(filename)

一个必需的位置参数：项目中 WAV 音频素材的名称。

参数

参数类型描述
filenamestrWAV 素材的名称

示例

jump_sound = Sound("jump")

附加 Sound

在生成时：

sfx = world.spawn(sound=Sound("jump"))

或稍后：

entity.sound = Sound("jump")

分配声音会立即开始播放。

组件属性

通过 entity.sound 访问：

属性类型读/写描述
loopbool读/写启用循环
volumefloat读/写增益（限制 >= 0.0）
panfloat读/写立体声声像（-1.0 到 1.0）
timefloatR/W当前播放位置（秒）
delayfloatR/W开始播放前的静音秒数
durationfloat只读总时长（秒）
finishedbool只读播放完成时为 True

loop

entity.sound.loop = True

启用后，声音结束后自动重新开始。

volume

entity.sound.volume = 0.5

低于 0.0 的值被限制为 0.0。

pan

entity.sound.pan = -1.0  # full left
entity.sound.pan =  1.0  # full right
entity.sound.pan =  0.0  # center

限制在 -1.0 到 1.0 范围内。

time

t = entity.sound.time
entity.sound.time = 0.25     # 跳过开头的四分之一秒

播放位置（秒）。为它赋值即可定位；超过结尾的值会被限制到结尾，而对已经结束的声音定位会让 它重新播放。

delay

entity.sound.delay = 0.002   # 两毫秒后开始

声音开始前的静音秒数。与 time 不同，它不会跳过任何内容——声音仍然从第一个采样开始，只是开始 得更晚。

当同一个音效在一帧内被触发多次时，应该用它。 同一波形的多个副本若从同一个采样开始，就会 同相叠加：两个是两倍振幅而不是 1.4 倍，十个则无论每一个的音量调得多仔细，都会让混音超出满 刻度。相隔几毫秒就足以让它们去相关，而这个长度远不足以被听成一个空隙。

延迟分开的是起音，所以它对短促的打击类音效最有效，对持续音则毫无作用。

duration

d = entity.sound.duration

只读。声音的总时长（秒）。

finished

if entity.sound.finished:
    world.destroy(entity)

只读。当声音播放完成时为 True（且 loop 为 False）。

格式

Sound 素材必须是 WAV 文件。

常见错误

缺少文件名

Sound()
ValueError: Sound must have a file

无效素材

Sound("nonexistent")

声音对象会被创建，但播放会静默失败并记录警告。