/**
 * Звук: процедурные SFX + фоновая музыка + свои mp3 + 3D-позиционный звук.
 */
declare namespace game {
    interface SoundApi {
        /**
         * Воспроизвести встроенный звук или свой загруженный.
         * @param name 'jump' | 'pickup' | 'coin' | 'win' | 'lose' | 'click' | 'hit'
         *             или ID своего звука из библиотеки.
         * @example
         * game.sound.play('coin');
         * game.sound.play('hit', { volume: 0.5, pitch: 1.2 });
         */
        play(
            name: 'jump' | 'pickup' | 'coin' | 'win' | 'lose' | 'click' | 'hit' | string,
            opts?: { volume?: number; pitch?: number; position?: game.Vector3 }
        ): void;

        /** Привязать звук к 3D-объекту (3D-позиционный звук). */
        attach(ref: game.Ref, soundName: string, opts?: {
            volume?: number; pitch?: number; loop?: boolean; range?: number;
        }): string;

        /** Остановить звук, привязанный к объекту. */
        detach(handle: string): void;
    }
    const sound: SoundApi;

    interface AudioApi {
        /** Воспроизвести встроенный SFX (алиас sound.play). */
        playSfx(name: string, opts?: { volume?: number; pitch?: number }): void;

        /** Включить фоновую музыку (пресет). */
        playMusic(preset: 'calm' | 'happy' | 'epic' | 'mystery' | string): void;

        /** Остановить фоновую музыку. */
        stopMusic(): void;

        /** Полностью отключить весь звук. */
        setMuted(muted: boolean): void;
    }
    const audio: AudioApi;
}
