用途:该技能用于让 .ink 剧本文件通过井号命令控制音效与音乐,包括播放背景音乐或音效、暂停/恢复/停止单个声音或整个通道、调整正在播放声音的属性(如音量、循环等),以及一次性操作全部声音。
主要能力:
- 播放:# play sound <alias> [<source>] [<key> <value> ...]。alias 用于后续命令识别该声音;source 可选,省略时默认使用 alias 本身作为资源别名/URL。参数对应 PixiVNJsonSoundPlayProps,包括 channel(播放所用已注册通道)、loop、volume、delay 等,均可选。示例:# play sound sfx_whoosh delay 0.1、# play sound bgm_cheerful loop true channel bgm。
- 暂停/恢复:# pause sound <alias> / # resume sound <alias> 针对单个正在播放的声音;# pause channel <alias> / # resume channel <alias> 针对该通道当前所有声音;# pause all sounds / # resume all sounds 暂停或恢复全部声音,不区分通道。
- 编辑:# edit sound <alias> [<key> <value> ...],属性对应 PixiVNJsonSoundEditProps,作用于已由 alias 标识的正在播放声音,可调整 volume、loop 等运行时属性。示例:# edit sound bgm_cheerful volume 50。
- 停止:# stop sound <alias> 停止并丢弃一个声音;# stop all sounds 停止全部声音。资料指出 # remove sound <alias> 是 # stop sound <alias> 的已弃用别名,建议使用 stop。
使用方式:需先运行 addBaseHashtagCommands()(其声音部分默认开启,参见 pixi-vn-ink);并假定 Pixi'VN 声音通道已设置好(例如通过 sound.addChannel 建立 bgm 和 sfx 通道)。随后在 .ink 文件中直接书写上述井号命令。资料附带完整示例,演示播放、暂停、恢复背景音乐的过程。
适用场景:视觉小说剧本中需要由 ink 脚本直接调度背景音乐与音效的场合,包括按剧情节点播放、暂停、恢复、停止声音,或动态调整音量与循环属性。
限制与关联:依赖 addBaseHashtagCommands() 已执行及声音通道预先配置;音频资源需先加载/注册别名,参见 pixi-vn-ink-assets;画布对应命令参见 pixi-vn-ink-canvas;底层 JS/TS 声音 API 与通道设置见 pixi-vn.com/start/sound。官方文档为 pixi-vn.com/ink/sound。