最后同步日期：2026-04-15 | Godot 官方原文 — AudioStreamPlayer2D

AudioStreamPlayer2D

节点继承关系

继承链：Node -> AudioStreamPlayer2D

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

AudioStreamPlayer2D 是带有 2D 空间定位功能的音频播放节点。声音会根据它和监听器（通常是摄像机）之间的距离和方向发生变化——越近越响，越远越轻；偏左则左声道响，偏右则右声道响。

一句话理解：它就像你站在街边，一辆汽车从左到右开过去——声音先从左边传来，经过你面前时最响，然后慢慢从右边消失。

想象你在玩一个 2D 横版游戏，画面里有个爆炸特效在屏幕右边。如果用普通播放器，声音从左右音箱同时发出；但如果用 AudioStreamPlayer2D，声音会明显偏右，而且如果你走远了，声音会变小——这就叫"空间音效"。

使用频率：★★★★ 常用（2D 游戏中经常用到）

节点用途

• 播放与 2D 位置相关的声音（脚步声、枪声、爆炸声）
• 让声音随着距离自然衰减
• 实现左右声道的立体声效果
• 营造 2D 游戏中的空间感

使用场景

典型场景

• 2D 射击音效：枪声在屏幕右上方响起，声音自然偏右且有一定距离感。
• 角色脚步声：脚步声跟随角色移动，玩家离角色越近，脚步声越清晰。
• NPC 说话：靠近 NPC 时能听清对话，走远了就变得模糊。
• 环境音效：比如远处瀑布的声音、篝火燃烧的声音。

不适用场景

• 背景音乐、UI 音效等不需要空间定位的声音 → 使用 AudioStreamPlayer
• 3D 游戏中的空间音效 → 使用 AudioStreamPlayer3D

常用节点搭配

搭配节点	用途	必需？
AudioListener2D	接收声音的"耳朵"	是（Camera2D 自带）
Camera2D	自带 AudioListener2D，是默认的监听位置	通常已有
CharacterBody2D / RigidBody2D	将播放器作为子节点跟随物体移动	视需求
AudioStreamPlayer	同时管理非定位音频（BGM 等）	视需求

生效必备素材/资源

资源类型	格式	说明
音频文件	.ogg、.wav、.mp3	需要加载为 AudioStream 资源
AudioListener2D	—	场景中必须有至少一个激活的监听器，否则 2D 空间音效不会生效

提示

如果你已经用了 Camera2D，它默认就带了 AudioListener2D，不需要额外添加。只有在需要自定义监听位置时才需要手动添加 AudioListener2D。

节点属性与信号

音频属性

属性	类型	默认值	继承自	说明
Stream	AudioStream?	null	—	要播放的音频资源
VolumeDb	float	0.0	—	音量（分贝），0 是原始音量
PitchScale	float	1.0	—	播放速度和音调的缩放
Autoplay	bool	false	—	是否在场景加载后自动播放
Bus	StringName	"Master"	—	音频总线名称
MaxPolyphony	int	1	—	同时播放的最大声音数量
Playing	bool	false	—	是否正在播放（只读）
StreamPaused	bool	false	—	是否暂停

空间音频属性（2D 特有）

属性	类型	默认值	继承自	说明
MaxDistance	float	2000.0	—	超过这个距离（像素）后声音完全听不到
Attenuation	float	1.0	—	衰减系数。值越大，声音随距离变小得越快
PanningStrength	float	1.0	—	左右声道分离强度。0 = 不分离（像普通播放器），1 = 完全分离
AreaMask	uint	1	—	区域遮罩，只对匹配该遮罩的 AudioListener2D 产生空间效果

信号

信号	触发时机	说明
Finished	音频播放完毕时	非循环音频播完会触发

常用方法

方法	返回值	说明
Play(double fromPosition = 0.0)	void	从指定位置开始播放
Stop()	void	停止播放
Seek(double position)	void	跳到指定时间点
GetPlaybackPosition()	double	获取当前播放进度（秒）
SetStreamPaused(bool paused)	void	暂停或恢复播放

代码示例

角色脚步声

C

using Godot;

public partial class Player2D : CharacterBody2D
{
    [Export] public AudioStream FootstepSound { get; set; }
    [Export] public float StepInterval { get; set; } = 0.4f;

    private AudioStreamPlayer2D _footstepPlayer;
    private double _stepTimer;

    public override void _Ready()
    {
        // 创建脚步声播放器并设为子节点
        _footstepPlayer = new AudioStreamPlayer2D();
        _footstepPlayer.Stream = FootstepSound;
        _footstepPlayer.MaxDistance = 500.0f;   // 500 像素外听不到
        _footstepPlayer.Attenuation = 2.0f;     // 较快的衰减
        _footstepPlayer.PanningStrength = 0.8f; // 适度的左右分离
        AddChild(_footstepPlayer);
    }

    public override void _PhysicsProcess(double delta)
    {
        Vector2 inputDir = Input.GetVector("ui_left", "ui_right", "ui_up", "ui_down");

        if (inputDir.LengthSquared() > 0.01f)
        {
            _stepTimer += delta;
            if (_stepTimer >= StepInterval)
            {
                _footstepPlayer.Play();
                _stepTimer = 0.0;
            }
        }
        else
        {
            _stepTimer = StepInterval; // 站着不动时，下次一动就立刻播放
        }
    }
}

GDScript

extends CharacterBody2D

@export var footstep_sound: AudioStream
@export var step_interval: float = 0.4

var _footstep_player: AudioStreamPlayer2D
var _step_timer: float

func _ready():
    # 创建脚步声播放器并设为子节点
    _footstep_player = AudioStreamPlayer2D.new()
    _footstep_player.stream = footstep_sound
    _footstep_player.max_distance = 500.0    # 500 像素外听不到
    _footstep_player.attenuation = 2.0       # 较快的衰减
    _footstep_player.panning_strength = 0.8  # 适度的左右分离
    add_child(_footstep_player)

func _physics_process(delta):
    var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")

    if input_dir.length_squared() > 0.01:
        _step_timer += delta
        if _step_timer >= step_interval:
            _footstep_player.play()
            _step_timer = 0.0
    else:
        _step_timer = step_interval  # 站着不动时，下次一动就立刻播放

2D 爆炸音效

C

using Godot;

public partial class Explosion2D : Node2D
{
    [Export] public AudioStream ExplosionSound { get; set; }
    [Export] public float ExplosionRadius { get; set; } = 800.0f;

    private AudioStreamPlayer2D _audioPlayer;

    public override void _Ready()
    {
        _audioPlayer = new AudioStreamPlayer2D();
        _audioPlayer.Stream = ExplosionSound;
        _audioPlayer.MaxDistance = ExplosionRadius;
        _audioPlayer.VolumeDb = 5.0f; // 爆炸声比普通音效大一点
        AddChild(_audioPlayer);
    }

    public void Explode()
    {
        _audioPlayer.Play();
        // 爆炸特效等其他逻辑...
    }
}

GDScript

extends Node2D

@export var explosion_sound: AudioStream
@export var explosion_radius: float = 800.0

var _audio_player: AudioStreamPlayer2D

func _ready():
    _audio_player = AudioStreamPlayer2D.new()
    _audio_player.stream = explosion_sound
    _audio_player.max_distance = explosion_radius
    _audio_player.volume_db = 5.0  # 爆炸声比普通音效大一点
    add_child(_audio_player)

func explode():
    _audio_player.play()
    # 爆炸特效等其他逻辑...