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

AudioListener2D

节点继承关系

继承链：Node -> AudioListener2D

Node

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

定义

AudioListener2D 是 2D 世界中的"耳朵"。它定义了"听声音的人"在 2D 空间中的位置。AudioStreamPlayer2D 播放的声音，就是根据声源（播放器）和这只"耳朵"之间的距离和方向来计算音量和左右声道的。

一句话理解：如果 AudioStreamPlayer2D 是"喇叭"，那 AudioListener2D 就是"你的耳朵"——声音的大小和方向感取决于喇叭离你多远、在左边还是右边。

想象你在一个房间里，墙上挂着两个音箱。你的耳朵就是 AudioListener，音箱就是 AudioStreamPlayer2D。你往音箱走，声音变大；你走到音箱左边，左声道更响。如果房间里没有"耳朵"（没有 AudioListener2D），即使音箱在播放，你也不会听到任何空间音效——所有声音都会退化成普通的无定位音效。

使用频率：★★ 偶尔使用（大多数情况不需要手动添加）

节点用途

• 定义 2D 空间中"听声音的人"的位置
• 让 AudioStreamPlayer2D 的空间音效生效
• 在需要自定义监听位置时使用（比如跟随非摄像机物体）

使用场景

典型场景

• Camera2D 默认自带：绝大多数情况下你不需要手动添加 AudioListener2D，因为 Camera2D 默认就带了一个。摄像机能看到什么区域，"耳朵"就在那个位置。
• 分屏游戏：两个玩家各有一个 Camera2D，各自带着自己的 AudioListener2D，这样每个玩家听到的声音都是基于自己视角的空间音效。
• 自定义监听位置：比如声音不跟随摄像机，而是跟随玩家角色。

不适用场景

• 如果你只需要默认的监听行为（声音跟着摄像机走），不需要手动添加。
• 3D 游戏请使用 AudioListener3D。

常用节点搭配

搭配节点	用途	必需？
Camera2D	自带 AudioListener2D，通常不需要额外添加	通常已有
AudioStreamPlayer2D	空间音效需要至少一个监听器才能生效	是（配对使用）

生效必备素材/资源

AudioListener2D 本身不需要任何外部资源。但要让它的空间音效功能有意义，场景中需要有 AudioStreamPlayer2D 节点。

节点属性与信号

监听器属性

属性	类型	默认值	继承自	说明
Current	bool	true	—	是否是当前激活的监听器。场景中同一时间只能有一个激活的 AudioListener2D

注意

一个场景中同一时间只应该有一个 Current = true 的 AudioListener2D。如果有多个，Godot 会使用最后一个激活的监听器，结果可能不符合预期。

信号

AudioListener2D 没有自定义信号。

常用方法

AudioListener2D 没有自定义方法，它只有继承自 Node 的通用方法。

代码示例

分屏游戏中的双监听器

C

using Godot;

public partial class SplitScreenManager : Node
{
    private Camera2D _camera1;
    private Camera2D _camera2;

    public override void _Ready()
    {
        // 获取两个玩家的摄像机
        _camera1 = GetNode<Camera2D>("Player1/Camera2D");
        _camera2 = GetNode<Camera2D>("Player2/Camera2D");

        // Camera2D 自带 AudioListener2D，可以通过子节点访问
        // 默认两个都是 current = true，需要手动管理切换
        // 分屏模式下两个监听器可以同时激活
    }

    /// <summary>
    /// 切换到单人模式（只激活一个监听器）
    /// </summary>
    public void SwitchToSinglePlayer()
    {
        // 通过子节点获取 AudioListener2D
        var listener1 = _camera1.GetChild<AudioListener2D>(0);
        listener1.Current = true;

        var listener2 = _camera2.GetChild<AudioListener2D>(0);
        listener2.Current = false;
    }
}

GDScript

extends Node

@onready var _camera1: Camera2D = $Player1/Camera2D
@onready var _camera2: Camera2D = $Player2/Camera2D

func _ready():
    # Camera2D 自带 AudioListener2D
    # 默认两个都是 current = true
    # 分屏模式下两个监听器可以同时激活
    pass

## 切换到单人模式（只激活一个监听器）
func switch_to_single_player():
    var listener1 = _camera1.get_child(0)  # AudioListener2D
    listener1.current = true

    var listener2 = _camera2.get_child(0)
    listener2.current = false

在非摄像机节点上添加监听器

C

using Godot;

public partial class PlayerWithCustomListener : CharacterBody2D
{
    private AudioListener2D _listener;

    public override void _Ready()
    {
        // 在角色身上（而非摄像机上）添加监听器
        // 这样声音的方向感基于角色位置而非摄像机位置
        _listener = new AudioListener2D();
        _listener.Current = true;
        AddChild(_listener);
    }
}

GDScript

extends CharacterBody2D

var _listener: AudioListener2D

func _ready():
    # 在角色身上（而非摄像机上）添加监听器
    # 这样声音的方向感基于角色位置而非摄像机位置
    _listener = AudioListener2D.new()
    _listener.current = true
    add_child(_listener)