声音与音乐

The sound module is a wrapper around the Tone.js library. 它提供了简洁的调用接口，并自动记录每一步骤（step）的播放状态，方便存档回溯。

它由以下元素构成（后文将频繁引用）：

• sound（管理器）是整个音频系统的控制器。 负责通道（channels）管理、媒体（media）启停、资源（assets）查询与参数调整。 可以设置值来调整整体的音频电平。 这些设置不会存入存档，适合用于游戏运行时的统一调控。
• channels是隶属于 sound 管理器的子级容器，可理解为音频的"分组"。 用于容纳、启动和管理具体的音频媒体。 你对频道做的设置只会影响其内部的媒体。 这些设置不会存入存档，适合用于游戏运行时的统一调控。
• media是每次播放声音时生成的独立实例。 你可以为每个实例单独设置参数。 此处所有的设置都会随游戏存档保存。 这些设置主要用于剧情推进过程中的动态调整。 一个频道可以包含多个 media，二者是一对多的关系。 每个 media 都有唯一的别名（alias）用于识别。
• assets（声音资源），顾名思义，就是游戏中实际用到的音频文件。 对资源做的设置会作用于所有使用该资源的 media 实例。 这些配置不会被保存，通常在游戏初始化加载资源时一次性设定好。

import { narration, newLabel, sound } from "@drincs/pixi-vn";

export const startLabel = newLabel("start", [
    async () => {
        await sound.play("sfx_whoosh", { delay: 0.1 });
        await sound.play("bgm_cheerful", { loop: true, channel: "bgm" });
        narration.dialogue =
            "Hello, I'm a cheerful background music that will loop forever until you stop me.";
    },
    () => {
        sound.pause("bgm_cheerful");
        narration.dialogue = "I'm paused, but I can be resumed.";
    },
    () => {
        sound.resume("bgm_cheerful");
        narration.dialogue = "I'm back!";
    },
]);

初始化

First of all, you need to define the asset matrix exactly as with other components. After that, it is recommended to load sounds at the start of the game using the functions provided by sound.

import { Assets, sound } from "@drincs/pixi-vn";
import manifest from "../assets/manifest";

/**
 * Define all the assets that will be used in the game.
 * This function will be called before the game starts.
 * You can read more about assets management in the documentation: https://pixi-vn.web.app/start/assets-management.html
 */
export async function defineAssets() {
    await Assets.init({ manifest });

    // The audio bundle will be loaded in the background, so it will be available when needed, but it won't block the game start.
    sound.backgroundLoadBundle("audio"); 
}

It is also recommended to define channels immediately after game initialization. During the definition of channels, you can configure their settings, which are all intuitive and based on PixiJS Sound, except for:

• background (Optional): this is a boolean value that can be used to define channels intended for background sounds such as music or ambient audio. Unlike other sounds, they will not be stopped between narrative steps.

import { Game, sound } from "@drincs/pixi-vn";

Game.init(body, {
    // ...
}).then(() => {
    sound.addChannel("bgm", { background: true });
    sound.addChannel("sfx");
    sound.defaultChannelAlias = "sfx";
});

Play

The basic functionality is to start a sound (asset). This can be done using the play function. The play function generates a media instance that you can interact with to control the produced sound.

This function has the following parameters:

• alias: The alias to identify the media.
• soundUrl (Optional): The URL or path. If you have initialized the asset matrix, you can use the alias of the sound. If you don't provide the URL, then the alias is used as the URL.
• options (Optional): The options for the media.
  • delay: The delay before the sound starts, in seconds.
  • loop: Override default loop, default to the Sound's loop setting.
  • speed: Override default speed, default to the Sound's speed setting.
  • volume: Override default volume, default to the Sound's volume setting.
  • start: Start time offset in seconds.
  • end: End time in seconds.
  • muted: If sound instance is muted by default.
  • filters: Filters that apply to play. Only supported with WebAudio.
  • channel: The alias of the channel to which the media will be assigned. If not specified, it will be assigned to sound.defaultChannelAlias.

Pause and resume

There are various ways to pause individual or multiple media.

编辑

It is possible to edit almost all settings at any time for different purposes.

Stop

To stop a sound, you can use the stop function.

音频滤镜

Filters are elements that allow advanced customization of sounds.

其他功能