API 参考 / capability 包：服务、状态与游玩访问

AudioAccess

音频控制能力（游玩中可用，随游玩场景注册 / 注销）：播放 / 停止音效与 BGM、设置 BGM 音量、查询当前正在播放的音效。音频资源本身须先经 ctx.registerSound / ctx.registerMusic 注册，本能力只负责播放控制。经 ctx.capabilities().get(AudioAccess.class) 取用。

方法速览

方法	用途
`playSound(String, double)`	播放音效
`stopSound(String)`	停止指定音效
`playMusic(String)`	播放 BGM（同一首正在播放则跳过）
`stopMusic()`	停止当前 BGM
`setMusicVolume(double)`	设置 BGM 音量
`playingSounds()`	当前正在播放的音效快照

完整签名

java

public interface AudioAccess {

    void playSound(String soundId, double volume);

    void stopSound(String soundId);

    void playMusic(String musicId);

    void stopMusic();

    void setMusicVolume(double volume);

    default List<PlayingSound> playingSounds();
}

playSound(String soundId, double volume)

签名：

java

void playSound(String soundId, double volume);

行为：播放已注册的音效（类别须为 SOUND）。

soundId 为资源注册 id；未注册或类别不是 SOUND 时宿主只打印错误日志并忽略（无异常）。
volume 为本次播放的额外音量倍率，宿主夹取到 [0,1]，再与主音量 / 类别音量 / 资源自带音量相乘。
宿主对同一 id 维护 3 个 Clip 的轮转池：连续播放会重叠（最多 3 个并发），第 4 次播放复用并重头播放最早那个 Clip——不是"相同 id 打断前一个"。
播放成功时宿主投递 SoundPlayEvent。

示例：

java

audio.playSound("mymod:sounds/click.wav", 0.8);

stopSound(String soundId)

签名：

java

void stopSound(String soundId);

行为：停止该 id 下轮转池中的全部音效实例；未在播放时无操作。

示例：

java

audio.stopSound("mymod:sounds/click.wav");

playMusic(String musicId)

签名：

java

void playMusic(String musicId);

行为：播放已注册的 BGM（类别为 BGM，受 BGM 音量控制），循环播放。同一 musicId 正在播放时直接跳过（场景切换不重启）；未注册 id 打印错误日志并忽略。

示例：

java

audio.playMusic("mymod:music/theme.ogg");

stopMusic()

签名：

java

void stopMusic();

行为：停止当前正在播放的 BGM（不要求模组知道其 id）；当前无 BGM 时为无操作。

示例：

java

audio.stopMusic();

setMusicVolume(double volume)

签名：

java

void setMusicVolume(double volume);

行为：设置宿主音频引擎的 BGM 音量，钳制到 [0,1]；若当前有 BGM 在播，立即按新音量重算（与主音量 / 类别音量相乘）。

示例：

java

audio.setMusicVolume(0.6);

playingSounds()

签名：

java

List<PlayingSound> playingSounds();

行为：返回宿主当前正在播放的音效快照列表（可能为空）。每项含注册 id、文件路径与类别（见 PlayingSound）。仅统计经宿主音效引擎启动且仍在播放的 SOUND；同一音效多实例并发播放时只出现一次。默认实现返回空列表（旧宿主安全退化）。

示例：

java

for (PlayingSound s : audio.playingSounds()) {
    ctx.getLogger().info("playing: " + s.id());
}

线程：能力在游玩场景 onEnter / onExit 时注册 / 注销，因此只在游玩中可取到（其它场景 get 返回 null）。播放调用落在宿主音频引擎，源码未声明额外线程约束。

稳定性：2.0 起冻结：2.x 内只增不破。

上一页StoryContext 下一页InputAccess